ORCID Support

From EPrints Documentation
Revision as of 16:00, 26 January 2021 by Rwf1v07@soton.ac.uk (talk | contribs) (→‎Change Log)
Jump to: navigation, search

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.

Orcid creators.png
Orcid user profile.png
Orcid warning.png

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.

Orcid rendering.png

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.

Orcid tooltip.png

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.

Orcid all users report.png

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.

Orcid creators report.png

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

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 Create or Connect your ORCID iD link that appears in the menu area when the logged in user does not have an ORCID associated with their account.

Orcid create or connect.png

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.

Orcid manage permissions.png

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.

Orcid sign in.png

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.

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:

Orcid import button.png

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.

Orcid import.png

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:

Orcid export button.png

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.

Orcid export.png

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 the creators field.

New Reports

Users with ORCIDs

With ORCID Support Advance installed, the Users with ORCIDs reports has been updated to include the permissions the user has granted for the repository to interact with their orcid.org profile.

Orcid user perms.png


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.

Orcid mismatch.png

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 there 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, an indexer event (UpdateCreatorOrcid.pm) ensures that the user's old publications have an ORCID added to them, by doing a search for all records where that user's email appears in the creators_id column. 

# In: UpdateCreatorEvent.pm
# ...
if( $user->is_set( "email" ) )
{
   my $email = $user->get_value( "email" );

   #get all records with this user's email listed as a creator
   my $ds = $repo->get_repository->get_dataset("eprint");
   my $search_exp = $ds->prepare_search();
   $search_exp->add_field(
     fields => [ $ds->field( 'creators_id' ) ],
     value => $email,
   );
   my $list = $search_exp->perform_search;
   $list->map(sub{
      my($session, $dataset, $eprint) = @_;

      # Update all existing eprints
   });
}
# ...

If your repository is configured differently, this event plugin may need reimplementing at the local archive level so that this search works differently, e.g. 

# In: LocalUpdateCreatorEvent.pm
# ...
if( $user->is_set( "email" ) )
{
   my $username= $user->get_value( "username" );

   #get all records with this user's email listed as a creator
   my $ds = $repo->get_repository->get_dataset("eprint");
   my $search_exp = $ds->prepare_search();
   $search_exp->add_field(
     fields => [ $ds->field( 'creators_id' ) ],
     value => $username,
   );
   my $list = $search_exp->perform_search;
   $list->map(sub{
      my($session, $dataset, $eprint) = @_;

      # Update all existing eprints
   });
}
# ...

Once the event plugin has been updated, you will need to restart your repository's indexer to make use of the new event.

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

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.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

Retrieved from ‘https://wiki.eprints.org/w/index.php?title=ORCID_Support&oldid=13540’