ORCID Support

Introduction

The ORCID Support and ORCID Support Advance plugins have been developed to group together various ORCID developments from across a range of repositories

ORCID Support provides basic ORCID functionality for the repository including the addition of a new ORCID metafield, ORCID rendering and validation, and basic reporting with the Generic Reporting Framework.

ORCID Support Advance builds upon the functionality of ORCID Support, and allows users to connect their repository profiles with their accounts on orcid.org. Once an account has been connected, the user may manage their orcid.org permissions, controlling how the repository reads and writes from orcid.org. If read permissions have been granted, works from orcid.org may be imported to the user's work area. If write permissions have been granted, records where the user's ORCID is present may be exported to their orcid.org profile.

ORCID Support

ORCID Field

ORCID Support adds a new orcid field to both the creators and editors field, as well as the adding a new stage to the edit user workflow where an ORCID may be stored. All of these fields are of type orcid, a special type of text field that validates the ORCID is of the correct format (16 digits broken into 4 groups of 4 separated by a dash, e.g. 0000-0003-1495-7122). The field also checks that the final digit of the ORCID, the checksum, is valid and a warning is displayed if the ORCID is invalid in any way.

The lookup script for the creators and editors fields has also been updated to include the ORCID where this can be retrieved from other records where the ORCID has already been stored.

The creators and editors fields will also be automatically be populated from user profiles if the creators or editors ID subfields can be used to lookup a corresponding user profile.

Display ORCIDS

ORCIDs are always displayed next to a small, green ORCID badge, and in form of a link to the corresponding orcid.org profile.

Where space on the screen is more restricted, such as in citations, the ORCID itself is removed and only the green ORCID badge is displayed. The badge still links to the orcid.org profile and when hovered over, the ORCID is displayed in a green tooltip.

Reports

Where the Generic Reporting Framework plugin has been installed, new reports will become available, under the heading ORCID Dashboard.

The All users with and without ORCIDs report will show all the users in the repository, showing users without an ORCID as non-compliant and users with an ORCID as compliant.

The Users with ORCIDs report, is similar to the All users report, but instead only shows the users who have ORCIDs in their user profile.

Finally, the Creators with ORCIDs report will highlight all EPrint records that have creators values with ORCIDs assigned to them.

RIOXX

Where the RIOXX plugin has been installed, ORCIDs will be added as the 'id' attribute for <rioxxterms:author> elements.

For Developers

Existing ORCID Fields

The ORCID Support plugin will add an ORCID field in the the following three places:

1. As a sub-field of creators for an EPrint. Check the Details stage of your EPrint workflow.
2. As a sub-field of editors for an EPrint. Check the Details stage of your EPrint workflow when the EPrint id of type Book or Book Section.
3. As a field for a user. Check the Profile stage in your user workflow.

If you already have an orcid field in any of these three locations, the ORCID Support will skip creating its own. However, it will not update the existing field to the new orcid type. Therefore if one or more of the fields exist you will need to edit them manually to change their type from text to orcid after the ORCID Support plugin has been installed:

{
  'sub_name' => 'orcid',
  'type' => 'text',
  'input_cols' => 20,
  'allow_null' => 1,
}

becomes

{
  'sub_name' => 'orcid',
  'type' => 'orcid',
  'input_cols' => 20,
  'allow_null' => 1,
}

If you have pre-configured the creators' or editors' orcid sub-field, this will likely be in your archive's cfg/cfg.d/eprint_fields.pl. The user's orcid field will most likely be in your archive's cfg/cfg.d/user_fields.pl.

Updating Citations

ORCID Support provides a function for rendering green ORCID badges which show the user's ORCID in a tooltip when hovered over. To add these in a citation, simply include the following when displaying creator or editor fields.

<!-- For Creators -->
<print expr="people_with_orcids(creators)" /> 

<!-- For Editors -->
<print expr="people_with_orcids(editors)" /> 

Change Log

v2.0

Accessibility fixes through additional of alt text to images.

Refactor application of ORCID field to a list of contributor fields, rather than arbitrarily hardcoding implementation for creators/editors.

Additional Editors with ORCID report.

Update logo to use svg version of image.

Merge phrases into a single file.

v1.7

Update reports to show custom content in headers, i.e. change outputs to users and hide compliance information when not relevant.

v1.6

Update ORCID rendering to display in format starting with https://orcid.org/

v1.5

Add German phrases and add missing ORCID search form phrases.

ORCID Support Advance

The ORCID Support Bazaar Plugin and ORCID membership is required for ORCID Support Advance.

Connecting to orcid.org

Before users can import or export from orcid.org, they first need to connect their repository user profiles with their orcid.org user profiles. This can be done via the Connect to ORCID® link that appears in the menu area when the logged in user does not have an ORCID associated with their account.

When clicked, the user will be taken to a new screen where they may specify which permissions they grant the repository when connecting to their orcid.org profile. By default all permissions are granted unless specified otherwise, which includes allowing the repository to connect with the orcid.org profile, read restricted works from the profile, and update activities on the profile.

Once the user has specified which permissions they would like to grant the repository, clicking the Create or Connect your ORCID iD button, will take the user to the ORCID site where they may sign in to connect their existing ORCID, or may create a new ORCID if they do not already have one.

Upon completion of this process, the user will be redirected to the Manage ORCID Permissions screen.

Each time the permissions are updated by clicking the Connect to ORCID button, the user will once again be asked to sign in to ORCID, as per the initial connection, so that orcid.org is aware of the permissions the user has granted to the repository.

When the Create and update publication details on your ORCID record check box is selected, the repository will try to update the user's orcid.org profile with details about their institution. By default, the institution will be added to the ORCID profile's Employment section. However the plugin's configuration may specify that certain user types should have their Education section updated instead.

First orcid.org Connection

When a user first connects their repository account to their ORCID account, and their ORCID is set in their user profile as a result, the repository does a search for all the eprints in the repository where that user's email is associated with one of ORCID contributor fields (i.e. creators or editors). These eprints are then recommitted, updating the ORCID contributor fields with the user's ORCID.

Import from orcid.org

With the Retrieve restricted details from your ORCID profile option selected in the Manage ORCID Permissions screen, a Import from orcid.org button should appear on the Manage deposits screen:

This screen will display all of the records from the user's orcid.org profile which the user has given permission to be read. Users can select which records they would like to appear by selecting the check boxes (all checkboxes are selected by default). If the record has been imported previously, the option to select the record for importing again will not be presented. Users can also filter which records appear by publication date, to help ensure only ORCID works from the relevant period are shown.

The Import from orcid.org will also appear on user profile screens, allowing admin users to import records from orcid.org on behalf of the repository's users.

Export to orcid.org

When the Create and update publication details on your ORCID record option is selected in the Manage ORCID Permissions screen, the Export to orcid.org button appears on the Manage deposits screen:

The Export to orcid.org will also appear on user profile screens, allowing admin users to export records from the repository to the user's orcid.org profile, on behalf of the repository's users.

Like the import screen, here the user may select which records they wish to export to their orcid.org profile using the checkboxes. The records presented are any of those where the user's ORCID is listed in one of the contributor fields (e.g. creator, editor, etc.). Items may also be filtered based on when they were last modified.

Items that have been exported to an orcid.org profile, may also be removed using this screen, via the Remove from orcid.org profile button.

New Reports

Users with ORCIDs

With ORCID Support Advance installed, the Users with an ORCID reports has been updated to include the permissions the user has granted for the repository to interact with their orcid.org profile, as well as the ORCID token expiry date.

orcid.org Name Mismatch

This report highlights where a user's name in their repository user profile differs from their name in their orcid.org profile.

For Developers

Configuration for the ORCID Support Advance plugin is stored in z_orcid_support_advance.pl at the local archive level.

To use the plugin, a client_id and client_secret will need to be provided. ORCID members may acquired these credentials by registering the repository as a client application at https://orcid.org/content/register-client-application-production-trusted-party.

When registering the redirect URI should be your repository's address followed by cgi/orcid/authenticate;

e.g. https://test-eprints.org/cgi/orcid/authenticate/

For non-members, a sandbox API is also provided which only gives access to ORCID details stored in the ORCID Sandbox. The Sandbox is a test website, which only sends emails to @mailinator email addresses and does not contain the records found in the Production Registry (for more info please see the Sandbox FAQ).

###General ORCID Support Advance config###
$c->{ORCID_contact_email} = $c->{adminemail};

$c->{orcid_support_advance}->{client_id} = "XXXX";
$c->{orcid_support_advance}->{client_secret} = "YYYY";

$c->{orcid_support_advance}->{orcid_apiv2} = "https://api.sandbox.orcid.org/v2.0/";
$c->{orcid_support_advance}->{orcid_org_auth_uri} = "https://sandbox.orcid.org/oauth/authorize";
$c->{orcid_support_advance}->{orcid_org_exch_uri} = "https://api.sandbox.orcid.org/oauth/token";
$c->{orcid_support_advance}->{redirect_uri} = $c->{"perl_url"} . "/orcid/authenticate";

Updating Creators Automatically

With the ORCID Support Advance plugin installed, the only way ORCIDs can be added to the creators table is via an automatic lookup of the user's repository profile, where their authenticated ORCID should be stored following a successful connection to orcid.org.

The trigger that carries out this lookup is found in z_orcid_support_advance.pl at the local archive level:

# In: z_orcid_support_advance.pl
# ...
#automatic update of eprint creator field - orcid should be set to user's orcid value
$c->add_dataset_trigger( 'eprint', EPrints::Const::EP_TRIGGER_BEFORE_COMMIT, sub
{
    my( %args ) = @_;
    my( $repo, $eprint, $changed ) = @args{qw( repository dataobj changed )};
    # ...
    # ...

The lookup assumes that user emails are stored in the creators_id field and looks for a corresponding user profile based on this field's value:

# In: z_orcid_support_advance.pl
# ...
my $email = $c->{id};
$email = lc($email) if defined $email;
my $user = EPrints::DataObj::User::user_with_email($eprint->repository, $email);
if( $user )
{
   if( EPrints::Utils::is_set( $user->value( 'orcid' ) ) ) #user has an orcid
   {
      #set the orcid
      $new_c->{orcid} = $user->value( 'orcid' );
   }
}
# ...

If your repository is configured differently however then you may need to adjust this lookup, e.g. if your repository stores usernames in 'creators_id':

# In: z_orcid_support_advance.pl
# ...
my $username = $c->{id};
$username= lc($username) if defined $username;
my $user = EPrints::DataObj::User::user_with_username($eprint->repository, $username);
if( $user )
{
   if( EPrints::Utils::is_set( $user->value( 'orcid' ) ) ) #user has an orcid
   {
      #set the orcid
      $new_c->{orcid} = $user->value( 'orcid' );
   }
}

Similarly, when a user first connects their user profile to orcid.org and the ORCID is added to their repository user account, a user commit trigger is called which will attempt to find all of the eprint records where that user is listed as a creator, and then commit those eprints so the new ORCID is pulled through. This trigger is also found in z_orcid_support_advance.pl and will need updating to ensure the lookup for a user's eprints, based on creators_id, is using the correct field.

ORCID Log Dataset (v1.9.4+)

A new ORCID log dataset is added to the repository to store details of communications between the repository and orcid.org when users first connect their accounts. The main purpose of this dataset is twofold:

• To store the state when making the OAuth connection, to ensure the response we get back has a matching state
• To store the repository permissions that are not explicitly shared with orcid.org, namely the permission to allow the repository to automatically update orcid.org every time a new item is published or a live item is updated.

Employment/Education Affiliation

ORCID identifies institutions using a RINGGOLD identifier.

The RINGGOLD identifier for the repository's institution may be defined in z_orcid_support_advance.pl, as used by ORCID Support Advance when trying to update the user's orcid.org profile:

#Details of the organization for affiliation inclusion - the easiest way to obtain the RINGGOLD id is to add it to your ORCID user record manually, then pull the orcid-profile via the API and the identifier will be on the record returned.
$c->{"plugins"}->{"Event::OrcidSync"}->{"params"}->{"affiliation"} = {
                                                "organization" => {
                                                        "name" => "My University Name", #name of organization - REQUIRED
                                                        "address" => {
                                                                "city" => "My Town",  # name of the town / city for the organization - REQUIRED if address included
                                                        #       "region" => "Countyshire",  # region e.g. county / state / province - OPTIONAL
                                                                "country" => "GB",  # 2 letter country code - AU, GB, IE, NZ, US, etc. - REQUIRED if address included
                                                        },
                                                        "disambiguated-organization" => {
                                                                "disambiguated-organization-identifier" => "ZZZZ",  # replace ZZZZ with Institutional identifier from the recognised source
                                                                "disambiguation-source" => "RINGGOLD", # Source for institutional identifier should be RINGGOLD or ISNI
                                                        }
                                                }
};

To specify which user types should have their Education section updated on their orcid.org profile, instead of the Employment section, add the user types to the following array.

$c->{orcid_support_advance}->{education_user_types} = [];

Change Log

v2.0

• Accessibility fixes

• Updated text for the static about page with clearer details about the permissions requests

• New intro paragraphs for the import/export screens

• Items exported to an orcid.org profile can now be removed from the orcid.org profile via the Export to ORCID screen

• Bespoke mapping for ORCID work types to eprint types (rather than just reverse the eprint type to work type mapping)

• Add token expiry to ORCID permissions report

• Import screen checks the review queue for potential duplicate items, not just the live archive

• Refactor fields ORCID changes are applied to, so they may be defined in a config array, rather than arbitrarily only applying ORCID related changes to creator/editor fields.

v1.9.4

• Configurable date field used when filtering results on the import screen (e.g. filter by publication date rather than last modified date)

• Allow name mismatches to be flagged to prevent them from re-appearing in the Name Mismatch report

• Default to using GRID as the institution identifier source as opposed to RINGGOLD

• Additional new auto-update permission subfield which when checked adds eprints to a user's connected ORCID profile when those eprints are published in the repository's live archive

• New revoke call to ensure any current ORCID permissions are removed before updating with new permissions

• Updated ORCID badge icon to better conform with ORCID brand guidelines

• Additional ORCID Log dataset to save state during the OAuth authentication process, and save repository based permissions.

v1.7

• When disconnecting repository account from orcid.org user account, include a revoke call which removes the repository from the list of trusted organizations.

v1.6

• Update ORCID Support Advance report exports to work with the up-to-date version of the Generic Reporting Framework (v3.0+)

v1.5.2

• When a user connects/disconnects their user account with their orcid.org account, eprints where they are listed as a creator are now updated via a post-commit trigger on the user, rather than via an indexer event.

• CheckOrcidName and OrcidSync Event plugins now return messages gracefully, rather than simply die on failed or successful outcomes/

v1.5.1

• Add BibTeX citation import functionality to retrieve more metadata when importing from orcid.org.

• Hide Creator and Editor Put Code fields from the deposit workflow using Javascript.

• Stop Put Code fields from being cloned when existing EPrint is used as a template for a new record.

v1.4.2

Fix bug with CheckOrcidName event which would cause event to keep retriggering if there was any leading/trailing white space in the name returned from orcid.org.

v1.4.1

• Minor bug fixes to stop the CheckName event from triggering when it is guaranteed to failed due to missing access_token, and fix that allows UpdateCreatorOrcid event to be carried out even if user hasn't given an access_token (as the event doesn't need one).

v1.4

• Add German phrases and static pages

• Fix issue where new institutions weren't being added to a user's orcid.org profile.

v1.3.2

• Fix indexer error message when trying to concatenate an undefined string: cfg/cfg.d/z_orcid_support_advance_rdf_triples.pl

v1.3.1

• Fix bug with error message appearing after CheckName event, even if event was carried out successfully: lib/plugins/EPrints/Plugin/Event/CheckOrcidName.pm

Additional Resources

• ORCID Support plugins presentation - A minimally technical presentation of the features of the ORCID Support and ORCID Support Advance plugins.