EPrints Documentation - User contributions [en-gb]

COAR Notify Overview

2024-05-16T11:49:50Z

Rwf1v07@soton.ac.uk: Created page with "Initial work on COAR Notify integration for EPrints is taking place at: https://github.com/eprints/eprints3.4/pull/387 (Signposting) https://github.com/eprintsug/coar_notify..."

Initial work on COAR Notify integration for EPrints is taking place at:

https://github.com/eprints/eprints3.4/pull/387 (Signposting)

https://github.com/eprintsug/coar_notify (COAR Notify plugin)

https://github.com/eprintsug/notifications (Notifications UI)

ORCID Support

2022-04-13T12:08:31Z

Rwf1v07@soton.ac.uk: /* ORCID Support Advance */

[[Category: ORCID]]
[[Category: Plugins]]
[[Category: Bazaar Package]]
=Introduction=
The [[ORCID_Support#ORCID_Support | ORCID Support]] and [[ORCID_Support#ORCID_Support_Advance | ORCID Support Advance]] plugins have been developed to group together various ORCID developments from across a range of repositories

[[ORCID_Support#ORCID_Support | 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#ORCID_Support_Advance | ORCID Support Advance]] builds upon the functionality of [[ORCID_Support#ORCID_Support | 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 <tt>orcid</tt> field to both the <tt>creators</tt> and <tt>editors</tt> 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 <tt>orcid</tt>, a special type of text field that validates the ORCID is of the [https://support.orcid.org/hc/en-us/articles/360006897674-Structure-of-the-ORCID-Identifier 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.

[[File:orcid_creators.png|800px|thumb|none]]

[[File:orcid_user_profile.png|800px|thumb|none]]

[[File:orcid_warning.png|800px|thumb|none]]

The lookup script for the <tt>creators</tt> and <tt>editors</tt> 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 <tt>creators</tt> and <tt>editors</tt> fields will also be automatically be populated from user profiles if the <tt>creators</tt> or <tt>editors</tt> 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.

[[File:orcid_rendering.png|800px|thumb|none]]

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.

[[File:orcid_tooltip.png|800px|thumb|none]]

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

[[File:orcid_all_users_report.png|800px|thumb|none]]

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 <tt>creators</tt> values with ORCIDs assigned to them.

[[File:orcid_creators_report.png|800px|thumb|none]]

==RIOXX==
Where the [http://bazaar.eprints.org/390/ 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:
# As a sub-field of <tt>creators</tt> for an EPrint. Check the <tt>Details</tt> stage of your EPrint workflow.
# As a sub-field of <tt>editors</tt> for an EPrint. Check the <tt>Details</tt> stage of your EPrint workflow when the EPrint id of type <tt>Book</tt> or <tt>Book Section</tt>.
# As a field for a <tt>user</tt>. Check the <tt>Profile</tt> stage in your user workflow.
If you already have an <tt>orcid</tt> 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 <tt>orcid</tt> type. Therefore if one or more of the fields exist you will need to edit them manually to change their type from <tt>text</tt> to <tt>orcid</tt> 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 <tt>creators</tt>' or <tt>editors</tt>' <tt>orcid</tt> sub-field, this will likely be in your archive's <tt>cfg/cfg.d/eprint_fields.pl</tt>. The user's <tt>orcid</tt> field will most likely be in your archive's <tt>cfg/cfg.d/user_fields.pl</tt>.

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

<pre>

<print expr="people_with_orcids(creators)" />


<print expr="people_with_orcids(editors)" />
</pre>

==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 [http://bazaar.eprints.org/581/ ORCID Support Bazaar Plugin] and [https://orcid.org/about/membership ORCID membership] is required for [http://bazaar.eprints.org/1102/ 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.

[[File:connect_to_orcid.jpg|800px|thumb|none]]

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.

[[File:connect_to_orcid_screen.jpg|800px|thumb|none]]

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.

[[File:authorize_orcid.jpg|800px|thumb|none]]

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:

[[File:orcid_import_button.png|800px|thumb|none]]

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.

[[File:import_from_orcid.jpg|800px|thumb|none]]

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:

[[File:orcid_export_button.png|800px|thumb|none]]

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.

[[File:export_to_orcid.jpg|800px|thumb|none]]

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.

[[File:orcid_advance_user_report.jpg|800px|thumb|none]]

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

[[File:orcid_mismatch.png|800px|thumb|none]]

==For Developers==
Configuration for the ORCID Support Advance plugin is stored in <tt>z_orcid_support_advance.pl</tt> at the local archive level.

To use the plugin, a <tt>client_id</tt> and <tt>client_secret</tt> 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 <tt>cgi/orcid/authenticate</tt>;'''

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

For non-members, a sandbox API is also provided which only gives access to ORCID details stored in the ORCID Sandbox. The [https://sandbox.orcid.org 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 [https://support.orcid.org/hc/en-us/articles/360006897474-Is-the-Sandbox-different-from-the-Production-Registry- Sandbox FAQ]).

<pre>
###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";
</pre>

===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 <tt>z_orcid_support_advance.pl</tt> at the local archive level:

<pre>
# 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 )};
# ...
# ...
</pre>

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

<pre>
# 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' );
}
}
# ...
</pre>

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':

<pre>
# 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' );
}
}
</pre>

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 [https://support.orcid.org/hc/en-us/articles/360006973513-How-are-organizations-identified-in-ORCID- RINGGOLD identifier].

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

<pre>
#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
}
}
};
</pre>

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.

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

==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 [https://github.com/eprints/orcid_support_advance/issues/5 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: <tt>cfg/cfg.d/z_orcid_support_advance_rdf_triples.pl</tt>

'''v1.3.1'''

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

= Additional Resources =
* [[:File:ORCID_Support_Plugins_Presentation.pdf|ORCID Support plugins presentation]] - A minimally technical presentation of the features of the ORCID Support and ORCID Support Advance plugins.

ORCID Support

2022-04-13T11:58:45Z

Rwf1v07@soton.ac.uk: /* For Developers */

[[Category: ORCID]]
[[Category: Plugins]]
[[Category: Bazaar Package]]
=Introduction=
The [[ORCID_Support#ORCID_Support | ORCID Support]] and [[ORCID_Support#ORCID_Support_Advance | ORCID Support Advance]] plugins have been developed to group together various ORCID developments from across a range of repositories

[[ORCID_Support#ORCID_Support | 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#ORCID_Support_Advance | ORCID Support Advance]] builds upon the functionality of [[ORCID_Support#ORCID_Support | 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 <tt>orcid</tt> field to both the <tt>creators</tt> and <tt>editors</tt> 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 <tt>orcid</tt>, a special type of text field that validates the ORCID is of the [https://support.orcid.org/hc/en-us/articles/360006897674-Structure-of-the-ORCID-Identifier 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.

[[File:orcid_creators.png|800px|thumb|none]]

[[File:orcid_user_profile.png|800px|thumb|none]]

[[File:orcid_warning.png|800px|thumb|none]]

The lookup script for the <tt>creators</tt> and <tt>editors</tt> 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 <tt>creators</tt> and <tt>editors</tt> fields will also be automatically be populated from user profiles if the <tt>creators</tt> or <tt>editors</tt> 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.

[[File:orcid_rendering.png|800px|thumb|none]]

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.

[[File:orcid_tooltip.png|800px|thumb|none]]

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

[[File:orcid_all_users_report.png|800px|thumb|none]]

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 <tt>creators</tt> values with ORCIDs assigned to them.

[[File:orcid_creators_report.png|800px|thumb|none]]

==RIOXX==
Where the [http://bazaar.eprints.org/390/ 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:
# As a sub-field of <tt>creators</tt> for an EPrint. Check the <tt>Details</tt> stage of your EPrint workflow.
# As a sub-field of <tt>editors</tt> for an EPrint. Check the <tt>Details</tt> stage of your EPrint workflow when the EPrint id of type <tt>Book</tt> or <tt>Book Section</tt>.
# As a field for a <tt>user</tt>. Check the <tt>Profile</tt> stage in your user workflow.
If you already have an <tt>orcid</tt> 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 <tt>orcid</tt> type. Therefore if one or more of the fields exist you will need to edit them manually to change their type from <tt>text</tt> to <tt>orcid</tt> 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 <tt>creators</tt>' or <tt>editors</tt>' <tt>orcid</tt> sub-field, this will likely be in your archive's <tt>cfg/cfg.d/eprint_fields.pl</tt>. The user's <tt>orcid</tt> field will most likely be in your archive's <tt>cfg/cfg.d/user_fields.pl</tt>.

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

<pre>

<print expr="people_with_orcids(creators)" />


<print expr="people_with_orcids(editors)" />
</pre>

==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 [http://bazaar.eprints.org/581/ ORCID Support Bazaar Plugin] and [https://orcid.org/about/membership ORCID membership] is required for [http://bazaar.eprints.org/1102/ 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.

[[File:connect_to_orcid.jpg|800px|thumb|none]]

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.

[[File:connect_to_orcid_screen.jpg|800px|thumb|none]]

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.

[[File:authorize_orcid.jpg|800px|thumb|none]]

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:

[[File:orcid_import_button.png|800px|thumb|none]]

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.

[[File:import_from_orcid.jpg|800px|thumb|none]]

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:

[[File:orcid_export_button.png|800px|thumb|none]]

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.

[[File:export_to_orcid.jpg|800px|thumb|none]]

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.

[[File:orcid_advance_user_report.jpg|800px|thumb|none]]

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

[[File:orcid_mismatch.png|800px|thumb|none]]

==For Developers==
Configuration for the ORCID Support Advance plugin is stored in <tt>z_orcid_support_advance.pl</tt> at the local archive level.

To use the plugin, a <tt>client_id</tt> and <tt>client_secret</tt> 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 <tt>cgi/orcid/authenticate</tt>;'''

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

For non-members, a sandbox API is also provided which only gives access to ORCID details stored in the ORCID Sandbox. The [https://sandbox.orcid.org 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 [https://support.orcid.org/hc/en-us/articles/360006897474-Is-the-Sandbox-different-from-the-Production-Registry- Sandbox FAQ]).

<pre>
###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";
</pre>

===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 <tt>z_orcid_support_advance.pl</tt> at the local archive level:

<pre>
# 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 )};
# ...
# ...
</pre>

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

<pre>
# 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' );
}
}
# ...
</pre>

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':

<pre>
# 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' );
}
}
</pre>

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 [https://support.orcid.org/hc/en-us/articles/360006973513-How-are-organizations-identified-in-ORCID- RINGGOLD identifier].

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

<pre>
#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
}
}
};
</pre>

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.

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

==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 [https://github.com/eprints/orcid_support_advance/issues/5 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: <tt>cfg/cfg.d/z_orcid_support_advance_rdf_triples.pl</tt>

'''v1.3.1'''

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

= Additional Resources =
* [[:File:ORCID_Support_Plugins_Presentation.pdf|ORCID Support plugins presentation]] - A minimally technical presentation of the features of the ORCID Support and ORCID Support Advance plugins.

ORCID Support

2022-04-13T11:51:00Z

Rwf1v07@soton.ac.uk: /* Users with ORCIDs */

[[Category: ORCID]]
[[Category: Plugins]]
[[Category: Bazaar Package]]
=Introduction=
The [[ORCID_Support#ORCID_Support | ORCID Support]] and [[ORCID_Support#ORCID_Support_Advance | ORCID Support Advance]] plugins have been developed to group together various ORCID developments from across a range of repositories

[[ORCID_Support#ORCID_Support | 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#ORCID_Support_Advance | ORCID Support Advance]] builds upon the functionality of [[ORCID_Support#ORCID_Support | 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 <tt>orcid</tt> field to both the <tt>creators</tt> and <tt>editors</tt> 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 <tt>orcid</tt>, a special type of text field that validates the ORCID is of the [https://support.orcid.org/hc/en-us/articles/360006897674-Structure-of-the-ORCID-Identifier 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.

[[File:orcid_creators.png|800px|thumb|none]]

[[File:orcid_user_profile.png|800px|thumb|none]]

[[File:orcid_warning.png|800px|thumb|none]]

The lookup script for the <tt>creators</tt> and <tt>editors</tt> 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 <tt>creators</tt> and <tt>editors</tt> fields will also be automatically be populated from user profiles if the <tt>creators</tt> or <tt>editors</tt> 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.

[[File:orcid_rendering.png|800px|thumb|none]]

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.

[[File:orcid_tooltip.png|800px|thumb|none]]

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

[[File:orcid_all_users_report.png|800px|thumb|none]]

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 <tt>creators</tt> values with ORCIDs assigned to them.

[[File:orcid_creators_report.png|800px|thumb|none]]

==RIOXX==
Where the [http://bazaar.eprints.org/390/ 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:
# As a sub-field of <tt>creators</tt> for an EPrint. Check the <tt>Details</tt> stage of your EPrint workflow.
# As a sub-field of <tt>editors</tt> for an EPrint. Check the <tt>Details</tt> stage of your EPrint workflow when the EPrint id of type <tt>Book</tt> or <tt>Book Section</tt>.
# As a field for a <tt>user</tt>. Check the <tt>Profile</tt> stage in your user workflow.
If you already have an <tt>orcid</tt> 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 <tt>orcid</tt> type. Therefore if one or more of the fields exist you will need to edit them manually to change their type from <tt>text</tt> to <tt>orcid</tt> 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 <tt>creators</tt>' or <tt>editors</tt>' <tt>orcid</tt> sub-field, this will likely be in your archive's <tt>cfg/cfg.d/eprint_fields.pl</tt>. The user's <tt>orcid</tt> field will most likely be in your archive's <tt>cfg/cfg.d/user_fields.pl</tt>.

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

<pre>

<print expr="people_with_orcids(creators)" />


<print expr="people_with_orcids(editors)" />
</pre>

==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 [http://bazaar.eprints.org/581/ ORCID Support Bazaar Plugin] and [https://orcid.org/about/membership ORCID membership] is required for [http://bazaar.eprints.org/1102/ 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.

[[File:connect_to_orcid.jpg|800px|thumb|none]]

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.

[[File:connect_to_orcid_screen.jpg|800px|thumb|none]]

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.

[[File:authorize_orcid.jpg|800px|thumb|none]]

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:

[[File:orcid_import_button.png|800px|thumb|none]]

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.

[[File:import_from_orcid.jpg|800px|thumb|none]]

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:

[[File:orcid_export_button.png|800px|thumb|none]]

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.

[[File:export_to_orcid.jpg|800px|thumb|none]]

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.

[[File:orcid_advance_user_report.jpg|800px|thumb|none]]

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

[[File:orcid_mismatch.png|800px|thumb|none]]

==For Developers==
Configuration for the ORCID Support Advance plugin is stored in <tt>z_orcid_support_advance.pl</tt> at the local archive level.

To use the plugin, a <tt>client_id</tt> and <tt>client_secret</tt> 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 <tt>cgi/orcid/authenticate</tt>;'''

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

For non-members, a sandbox API is also provided which only gives access to ORCID details stored in the ORCID Sandbox. The [https://sandbox.orcid.org 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 [https://support.orcid.org/hc/en-us/articles/360006897474-Is-the-Sandbox-different-from-the-Production-Registry- Sandbox FAQ]).

<pre>
###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";
</pre>

===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 <tt>z_orcid_support_advance.pl</tt> at the local archive level:

<pre>
# 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 )};
# ...
# ...
</pre>

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

<pre>
# 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' );
}
}
# ...
</pre>

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':

<pre>
# 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' );
}
}
</pre>

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.

===Employment/Education Affiliation===
ORCID identifies institutions using a [https://support.orcid.org/hc/en-us/articles/360006973513-How-are-organizations-identified-in-ORCID- RINGGOLD identifier].

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

<pre>
#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
}
}
};
</pre>

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.

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

==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 [https://github.com/eprints/orcid_support_advance/issues/5 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: <tt>cfg/cfg.d/z_orcid_support_advance_rdf_triples.pl</tt>

'''v1.3.1'''

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

= Additional Resources =
* [[:File:ORCID_Support_Plugins_Presentation.pdf|ORCID Support plugins presentation]] - A minimally technical presentation of the features of the ORCID Support and ORCID Support Advance plugins.

File:Orcid advance user report.jpg

2022-04-13T11:50:48Z

Rwf1v07@soton.ac.uk:

ORCID Support

2022-04-13T11:48:02Z

Rwf1v07@soton.ac.uk: /* Export to orcid.org */

[[Category: ORCID]]
[[Category: Plugins]]
[[Category: Bazaar Package]]
=Introduction=
The [[ORCID_Support#ORCID_Support | ORCID Support]] and [[ORCID_Support#ORCID_Support_Advance | ORCID Support Advance]] plugins have been developed to group together various ORCID developments from across a range of repositories

[[ORCID_Support#ORCID_Support | 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#ORCID_Support_Advance | ORCID Support Advance]] builds upon the functionality of [[ORCID_Support#ORCID_Support | 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 <tt>orcid</tt> field to both the <tt>creators</tt> and <tt>editors</tt> 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 <tt>orcid</tt>, a special type of text field that validates the ORCID is of the [https://support.orcid.org/hc/en-us/articles/360006897674-Structure-of-the-ORCID-Identifier 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.

[[File:orcid_creators.png|800px|thumb|none]]

[[File:orcid_user_profile.png|800px|thumb|none]]

[[File:orcid_warning.png|800px|thumb|none]]

The lookup script for the <tt>creators</tt> and <tt>editors</tt> 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 <tt>creators</tt> and <tt>editors</tt> fields will also be automatically be populated from user profiles if the <tt>creators</tt> or <tt>editors</tt> 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.

[[File:orcid_rendering.png|800px|thumb|none]]

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.

[[File:orcid_tooltip.png|800px|thumb|none]]

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

[[File:orcid_all_users_report.png|800px|thumb|none]]

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 <tt>creators</tt> values with ORCIDs assigned to them.

[[File:orcid_creators_report.png|800px|thumb|none]]

==RIOXX==
Where the [http://bazaar.eprints.org/390/ 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:
# As a sub-field of <tt>creators</tt> for an EPrint. Check the <tt>Details</tt> stage of your EPrint workflow.
# As a sub-field of <tt>editors</tt> for an EPrint. Check the <tt>Details</tt> stage of your EPrint workflow when the EPrint id of type <tt>Book</tt> or <tt>Book Section</tt>.
# As a field for a <tt>user</tt>. Check the <tt>Profile</tt> stage in your user workflow.
If you already have an <tt>orcid</tt> 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 <tt>orcid</tt> type. Therefore if one or more of the fields exist you will need to edit them manually to change their type from <tt>text</tt> to <tt>orcid</tt> 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 <tt>creators</tt>' or <tt>editors</tt>' <tt>orcid</tt> sub-field, this will likely be in your archive's <tt>cfg/cfg.d/eprint_fields.pl</tt>. The user's <tt>orcid</tt> field will most likely be in your archive's <tt>cfg/cfg.d/user_fields.pl</tt>.

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

<pre>

<print expr="people_with_orcids(creators)" />


<print expr="people_with_orcids(editors)" />
</pre>

==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 [http://bazaar.eprints.org/581/ ORCID Support Bazaar Plugin] and [https://orcid.org/about/membership ORCID membership] is required for [http://bazaar.eprints.org/1102/ 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.

[[File:connect_to_orcid.jpg|800px|thumb|none]]

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.

[[File:connect_to_orcid_screen.jpg|800px|thumb|none]]

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.

[[File:authorize_orcid.jpg|800px|thumb|none]]

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:

[[File:orcid_import_button.png|800px|thumb|none]]

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.

[[File:import_from_orcid.jpg|800px|thumb|none]]

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:

[[File:orcid_export_button.png|800px|thumb|none]]

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.

[[File:export_to_orcid.jpg|800px|thumb|none]]

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 ORCIDs'' reports has been updated to include the permissions the user has granted for the repository to interact with their orcid.org profile.

[[File:orcid_user_perms.png|800px|thumb|none]]

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

[[File:orcid_mismatch.png|800px|thumb|none]]

==For Developers==
Configuration for the ORCID Support Advance plugin is stored in <tt>z_orcid_support_advance.pl</tt> at the local archive level.

To use the plugin, a <tt>client_id</tt> and <tt>client_secret</tt> 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 <tt>cgi/orcid/authenticate</tt>;'''

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

For non-members, a sandbox API is also provided which only gives access to ORCID details stored in the ORCID Sandbox. The [https://sandbox.orcid.org 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 [https://support.orcid.org/hc/en-us/articles/360006897474-Is-the-Sandbox-different-from-the-Production-Registry- Sandbox FAQ]).

<pre>
###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";
</pre>

===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 <tt>z_orcid_support_advance.pl</tt> at the local archive level:

<pre>
# 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 )};
# ...
# ...
</pre>

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

<pre>
# 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' );
}
}
# ...
</pre>

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':

<pre>
# 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' );
}
}
</pre>

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.

===Employment/Education Affiliation===
ORCID identifies institutions using a [https://support.orcid.org/hc/en-us/articles/360006973513-How-are-organizations-identified-in-ORCID- RINGGOLD identifier].

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

<pre>
#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
}
}
};
</pre>

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.

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

==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 [https://github.com/eprints/orcid_support_advance/issues/5 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: <tt>cfg/cfg.d/z_orcid_support_advance_rdf_triples.pl</tt>

'''v1.3.1'''

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

= Additional Resources =
* [[:File:ORCID_Support_Plugins_Presentation.pdf|ORCID Support plugins presentation]] - A minimally technical presentation of the features of the ORCID Support and ORCID Support Advance plugins.

ORCID Support

2022-04-13T11:46:53Z

Rwf1v07@soton.ac.uk: /* Export to orcid.org */

[[Category: ORCID]]
[[Category: Plugins]]
[[Category: Bazaar Package]]
=Introduction=
The [[ORCID_Support#ORCID_Support | ORCID Support]] and [[ORCID_Support#ORCID_Support_Advance | ORCID Support Advance]] plugins have been developed to group together various ORCID developments from across a range of repositories

[[ORCID_Support#ORCID_Support | 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#ORCID_Support_Advance | ORCID Support Advance]] builds upon the functionality of [[ORCID_Support#ORCID_Support | 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 <tt>orcid</tt> field to both the <tt>creators</tt> and <tt>editors</tt> 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 <tt>orcid</tt>, a special type of text field that validates the ORCID is of the [https://support.orcid.org/hc/en-us/articles/360006897674-Structure-of-the-ORCID-Identifier 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.

[[File:orcid_creators.png|800px|thumb|none]]

[[File:orcid_user_profile.png|800px|thumb|none]]

[[File:orcid_warning.png|800px|thumb|none]]

The lookup script for the <tt>creators</tt> and <tt>editors</tt> 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 <tt>creators</tt> and <tt>editors</tt> fields will also be automatically be populated from user profiles if the <tt>creators</tt> or <tt>editors</tt> 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.

[[File:orcid_rendering.png|800px|thumb|none]]

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.

[[File:orcid_tooltip.png|800px|thumb|none]]

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

[[File:orcid_all_users_report.png|800px|thumb|none]]

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 <tt>creators</tt> values with ORCIDs assigned to them.

[[File:orcid_creators_report.png|800px|thumb|none]]

==RIOXX==
Where the [http://bazaar.eprints.org/390/ 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:
# As a sub-field of <tt>creators</tt> for an EPrint. Check the <tt>Details</tt> stage of your EPrint workflow.
# As a sub-field of <tt>editors</tt> for an EPrint. Check the <tt>Details</tt> stage of your EPrint workflow when the EPrint id of type <tt>Book</tt> or <tt>Book Section</tt>.
# As a field for a <tt>user</tt>. Check the <tt>Profile</tt> stage in your user workflow.
If you already have an <tt>orcid</tt> 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 <tt>orcid</tt> type. Therefore if one or more of the fields exist you will need to edit them manually to change their type from <tt>text</tt> to <tt>orcid</tt> 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 <tt>creators</tt>' or <tt>editors</tt>' <tt>orcid</tt> sub-field, this will likely be in your archive's <tt>cfg/cfg.d/eprint_fields.pl</tt>. The user's <tt>orcid</tt> field will most likely be in your archive's <tt>cfg/cfg.d/user_fields.pl</tt>.

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

<pre>

<print expr="people_with_orcids(creators)" />


<print expr="people_with_orcids(editors)" />
</pre>

==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 [http://bazaar.eprints.org/581/ ORCID Support Bazaar Plugin] and [https://orcid.org/about/membership ORCID membership] is required for [http://bazaar.eprints.org/1102/ 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.

[[File:connect_to_orcid.jpg|800px|thumb|none]]

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.

[[File:connect_to_orcid_screen.jpg|800px|thumb|none]]

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.

[[File:authorize_orcid.jpg|800px|thumb|none]]

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:

[[File:orcid_import_button.png|800px|thumb|none]]

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.

[[File:import_from_orcid.jpg|800px|thumb|none]]

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:

[[File:orcid_export_button.png|800px|thumb|none]]

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.

[[File:export_to_orcid.jpg|800px|thumb|none]]

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

[[File:orcid_user_perms.png|800px|thumb|none]]

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

[[File:orcid_mismatch.png|800px|thumb|none]]

==For Developers==
Configuration for the ORCID Support Advance plugin is stored in <tt>z_orcid_support_advance.pl</tt> at the local archive level.

To use the plugin, a <tt>client_id</tt> and <tt>client_secret</tt> 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 <tt>cgi/orcid/authenticate</tt>;'''

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

For non-members, a sandbox API is also provided which only gives access to ORCID details stored in the ORCID Sandbox. The [https://sandbox.orcid.org 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 [https://support.orcid.org/hc/en-us/articles/360006897474-Is-the-Sandbox-different-from-the-Production-Registry- Sandbox FAQ]).

<pre>
###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";
</pre>

===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 <tt>z_orcid_support_advance.pl</tt> at the local archive level:

<pre>
# 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 )};
# ...
# ...
</pre>

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

<pre>
# 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' );
}
}
# ...
</pre>

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':

<pre>
# 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' );
}
}
</pre>

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.

===Employment/Education Affiliation===
ORCID identifies institutions using a [https://support.orcid.org/hc/en-us/articles/360006973513-How-are-organizations-identified-in-ORCID- RINGGOLD identifier].

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

<pre>
#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
}
}
};
</pre>

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.

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

==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 [https://github.com/eprints/orcid_support_advance/issues/5 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: <tt>cfg/cfg.d/z_orcid_support_advance_rdf_triples.pl</tt>

'''v1.3.1'''

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

= Additional Resources =
* [[:File:ORCID_Support_Plugins_Presentation.pdf|ORCID Support plugins presentation]] - A minimally technical presentation of the features of the ORCID Support and ORCID Support Advance plugins.

ORCID Support

2022-04-13T11:46:45Z

Rwf1v07@soton.ac.uk: /* Export to orcid.org */

[[Category: ORCID]]
[[Category: Plugins]]
[[Category: Bazaar Package]]
=Introduction=
The [[ORCID_Support#ORCID_Support | ORCID Support]] and [[ORCID_Support#ORCID_Support_Advance | ORCID Support Advance]] plugins have been developed to group together various ORCID developments from across a range of repositories

[[ORCID_Support#ORCID_Support | 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#ORCID_Support_Advance | ORCID Support Advance]] builds upon the functionality of [[ORCID_Support#ORCID_Support | 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 <tt>orcid</tt> field to both the <tt>creators</tt> and <tt>editors</tt> 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 <tt>orcid</tt>, a special type of text field that validates the ORCID is of the [https://support.orcid.org/hc/en-us/articles/360006897674-Structure-of-the-ORCID-Identifier 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.

[[File:orcid_creators.png|800px|thumb|none]]

[[File:orcid_user_profile.png|800px|thumb|none]]

[[File:orcid_warning.png|800px|thumb|none]]

The lookup script for the <tt>creators</tt> and <tt>editors</tt> 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 <tt>creators</tt> and <tt>editors</tt> fields will also be automatically be populated from user profiles if the <tt>creators</tt> or <tt>editors</tt> 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.

[[File:orcid_rendering.png|800px|thumb|none]]

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.

[[File:orcid_tooltip.png|800px|thumb|none]]

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

[[File:orcid_all_users_report.png|800px|thumb|none]]

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 <tt>creators</tt> values with ORCIDs assigned to them.

[[File:orcid_creators_report.png|800px|thumb|none]]

==RIOXX==
Where the [http://bazaar.eprints.org/390/ 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:
# As a sub-field of <tt>creators</tt> for an EPrint. Check the <tt>Details</tt> stage of your EPrint workflow.
# As a sub-field of <tt>editors</tt> for an EPrint. Check the <tt>Details</tt> stage of your EPrint workflow when the EPrint id of type <tt>Book</tt> or <tt>Book Section</tt>.
# As a field for a <tt>user</tt>. Check the <tt>Profile</tt> stage in your user workflow.
If you already have an <tt>orcid</tt> 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 <tt>orcid</tt> type. Therefore if one or more of the fields exist you will need to edit them manually to change their type from <tt>text</tt> to <tt>orcid</tt> 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 <tt>creators</tt>' or <tt>editors</tt>' <tt>orcid</tt> sub-field, this will likely be in your archive's <tt>cfg/cfg.d/eprint_fields.pl</tt>. The user's <tt>orcid</tt> field will most likely be in your archive's <tt>cfg/cfg.d/user_fields.pl</tt>.

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

<pre>

<print expr="people_with_orcids(creators)" />


<print expr="people_with_orcids(editors)" />
</pre>

==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 [http://bazaar.eprints.org/581/ ORCID Support Bazaar Plugin] and [https://orcid.org/about/membership ORCID membership] is required for [http://bazaar.eprints.org/1102/ 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.

[[File:connect_to_orcid.jpg|800px|thumb|none]]

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.

[[File:connect_to_orcid_screen.jpg|800px|thumb|none]]

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.

[[File:authorize_orcid.jpg|800px|thumb|none]]

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:

[[File:orcid_import_button.png|800px|thumb|none]]

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.

[[File:import_from_orcid.jpg|800px|thumb|none]]

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:

[[File:orcid_export_button.png|800px|thumb|none]]

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.

[[File:export_to_orcid.png|800px|thumb|none]]

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

[[File:orcid_user_perms.png|800px|thumb|none]]

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

[[File:orcid_mismatch.png|800px|thumb|none]]

==For Developers==
Configuration for the ORCID Support Advance plugin is stored in <tt>z_orcid_support_advance.pl</tt> at the local archive level.

To use the plugin, a <tt>client_id</tt> and <tt>client_secret</tt> 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 <tt>cgi/orcid/authenticate</tt>;'''

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

For non-members, a sandbox API is also provided which only gives access to ORCID details stored in the ORCID Sandbox. The [https://sandbox.orcid.org 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 [https://support.orcid.org/hc/en-us/articles/360006897474-Is-the-Sandbox-different-from-the-Production-Registry- Sandbox FAQ]).

<pre>
###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";
</pre>

===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 <tt>z_orcid_support_advance.pl</tt> at the local archive level:

<pre>
# 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 )};
# ...
# ...
</pre>

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

<pre>
# 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' );
}
}
# ...
</pre>

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':

<pre>
# 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' );
}
}
</pre>

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.

===Employment/Education Affiliation===
ORCID identifies institutions using a [https://support.orcid.org/hc/en-us/articles/360006973513-How-are-organizations-identified-in-ORCID- RINGGOLD identifier].

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

<pre>
#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
}
}
};
</pre>

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.

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

==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 [https://github.com/eprints/orcid_support_advance/issues/5 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: <tt>cfg/cfg.d/z_orcid_support_advance_rdf_triples.pl</tt>

'''v1.3.1'''

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

= Additional Resources =
* [[:File:ORCID_Support_Plugins_Presentation.pdf|ORCID Support plugins presentation]] - A minimally technical presentation of the features of the ORCID Support and ORCID Support Advance plugins.

2021-11-08T14:31:24Z

Rwf1v07@soton.ac.uk:

'''This documentation relates to release candidate version of the DataCite DOI plugin, available at [https://github.com/eprintsug/DataCiteDoi/tree/datacite-documents]'''

==DataCite DOI Manager Screen==
The process for registering and minting DOIs is now managed via the '''DataCite DOI Manager''' screen, available via an eprint item’s '''Actions''' tab.

[[File:Actions tab highlighted.png|600px|thumb|center|Actions tab with the DataCite DOI Manager option.]]

The '''DataCite DOI Manager''' is only available for items in the review queue or the live archive, and only to those users with editor or administrator permissions.

Each eprint record has its own DOI that can be registered with DataCite, derived from the repository’s DataCite prefix (e.g. 10.xxx), the repository’s name, and the eprint’s ID.

[[File:Available doi.jpg|600px|thumb|center|An eprint in the live archive with an available DOI. Options are available to either reserve or mint the DOI.]]

If this DOI has not yet been registered on DataCite, it will be listed as an '''Available DOI''', and is available either to reserve or mint:

* '''Reserve:''' The DOI is created in DataCite as a Draft DOI. The DOI is not listed in the global handle system and is not publicly findable.
* '''Mint:''' The DOI is registered with the global handle system and listed as Findable in DataCite.

==Reserving DOIS==
Items in the repository’s review queue may only have DOIs reserved. Not all of the mandatory metadata is required when reserving a DOI.

[[File:Reserve doi.jpg|600px|thumb|center|An item in the review queue. A DOI may be reserved adding it as a draft DOI in DataCite.]]

Clicking the '''Reserve DOI''' button will create a draft DOI in DataCite. This process happens instantly and the '''DataCite DOI Manager''' screen will update to show when the DOI was reserved as well as adding the DOI to the item’s DOI metadata field. Draft DOIs are not registered against the global handle system, i.e. they won’t redirect to the eprint. Once a reserved DOI has been created it can be updated with the item’s current metadata.

[[File:Update reserve.jpg|600px|thumb|center|A reserved DOI, with the option to update the metadata associated with this DOI.]]

==Minting DOIs==
Minting a DOI adds it as a findable DOI in DataCite. There are two main approaches to minting a DOI:

# Using the '''Mint DOI''' button for an item in the live archive, which has all of the required metadata.
# Transferring an item with a reserved DOI and all of the required metadata, to the live archive, from the review queue.

The '''Mint DOI''' button will register the DOI with the global handle system, and the DOI will be registered as “Findable” in DataCite. This process may take a few minutes and is handled by the repository’s indexer. Upon successful completion the new DOI will be added to the eprint’s DOI metadata field.

[[File:Mint doi.jpg|600px|thumb|center|An item in the live archive with a DOI available to mint. The option to update the previously reserved DOI is still available too.]]

Once a DOI has successfully been minted for an eprint, the option to '''Update Metadata''' becomes available, which will resend the eprint metadata for this DOI.

'''This should only be used for minor updates, e.g. correcting errors or adding additional files.'''

==Tombstone Pages==
If an item which has previously had a DOI minted for it is either retired or removed from the repository, the DataCite record is updated to point to a tombstone page for the record. This consists of the basic citation metadata that was last registered with DataCite, i.e. the data available when either of the '''Mint DOI''' or '''Update Metadata''' buttons was last used.

[[File:Eprint tombstone.jpg|600px|thumb|center|A tombstone page for a retired eprint, which the DOI will now redirect to, providing basic citation information.]]

==Versioning==
When creating a new version of an eprint via the '''New version''' button in the '''Actions''' tab, any existing DOI value will be copied across to the new version of the eprint.

The '''DataCite DOI Manager''' will highlight when a Current DOI redirects to an earlier version of an eprint, and will present two options when the later version is in the live archive (i.e. has a page a DOI can successfully redirect to).

# '''Update Metadata & URL''' – this will update the current DataCite record to redirect to the new version of this eprint
# '''Reserve DOI''' and '''Mint DOI''' – the regular options available when the Available DOI for a record has not yet been reserved or registered on DataCite.

[[File:Update metadata and url.jpg|600px|thumb|center|This eprint is a later version of an existing eprint and has inherited a DOI. The metadata and URL associated with this DOI can be updated to redirect to the newer record.]]

DOIs registered for eprints which are earlier or later versions of other eprints, will use DataCite’s “HasVersion” and “IsVersionOf” properties to link forwards and backwards as appropriate.

==External DOIs==
If an eprint already has a DOI associated with it, e.g. one that has previously been provided by a journal publication, then this will be listed as the '''Current DOI'''. The DataCite DOI Manager screen will indicate where this DOI redirects to, and will still present options for an '''Available DOI''' if the DOI for this record can still be minted on DataCite.

[[File:External doi.jpg|600px|thumb|center|An eprint with an external DOI set. This can be replaced with an available DOI via DataCite.]]

The '''DataCite DOI Manager''' will also run a search of the eprint’s title against DataCites findable records, to see if a DOI has been coined previously. If one of the records matches the eprint, the '''Claim DOI''' button will set the eprint’s DOI metadata field to the DOI already on DataCite.

[[File:Claim doi.jpg|600px|thumb|center|Items with similar titles are already present on DataCite. If one matches the eprint, click "Claim DOI" to use the existing DOI rather than coining a new one.]]

==Document DOIs==
All of the above features are also available for documents uploaded to a repository. DOIs must resolve to a landing page about the record they identify, and as such these features are only available for repositories with document landing pages enabled.

[[File:Document actions.jpg|600px|thumb|center| The document "test.pdf" attached to this eprint can also have a DOI reserved or coined.]]

=Document Landing Pages=
The DataCite DOI plugin supports minting DOIs for documents uploaded to eprint records, however all DOIs must resolve to a landing page however and so in order to enable this your repository needs to support document landing pages. The following code snippets illustrate how to implement document landing pages in EPrints.

First we need a URL rewrite trigger to catch the URLs which should resolve to the landing page. The following needs to be added to the eprints or archives' configuration files, e.g. lib/cfg.d/doc_landing_pages.pl. We can also define a flag here for plugins to check to see if document landing pages are enabled on this repository.

<pre>
# configuration flag used to check if document landing pages are enabled on this repository
$c->{doc_landing_pages_enabled} = 1;

$c->add_trigger( EP_TRIGGER_URL_REWRITE, sub
{
my( %args ) = @_;

my( $uri, $rc, $request ) = @args{ qw( uri return_code request ) };

# matches https://myrepo.ac.uk/document/<doc_id>
if( defined $uri && ($uri =~ m#^/document/(.*)$# ) )
{
$request->handler('perl-script');
$request->set_handlers(PerlResponseHandler => [ 'EPrints::Apache::Document' ] );
${$rc} = EPrints::Const::OK;
}

return EP_TRIGGER_OK;

}, priority => 100 );
</pre>

This trigger uses a Document handler we need to implement, e.g. perl_lib/EPrints/Apache/Document.pm

<pre>
######################################################################
#
# EPrints::Apache::Document
#
######################################################################

package EPrints::Apache::Document;

use strict;

use EPrints;
use EPrints::Apache::AnApache;

sub handler
{
my( $r ) = @_;

my $uri = $r->uri;

if( $uri =~ m#^/document/(.*)$# )
{
my $repository = $EPrints::HANDLE->current_repository;
return DECLINED if( !defined $repository );

# Document landing pages enabled for this repository?
return DECLINED unless( $repository->config( "doc_landing_pages_enabled" ) );

my $doc_id = $1;

my $doc_ds = $repository->dataset( "document" );
my $doc = $doc_ds->dataobj( $doc_id );

if( defined $doc )
{
EPrints::ScreenProcessor->process(
session => $repository,
screenid => "Document",
document => $doc,
);
return OK;
}
}

return DECLINED;
}

1;
</pre>

The handler calls on an EPrints screen to generate the content for the landing page, e.g. perl_lib/EPrints/Plugin/Screen/Document.pm

=head1 NAME

EPrints::Plugin::Screen::Document

=cut

package EPrints::Plugin::Screen::Document;

use EPrints::Plugin::Screen;

@ISA = ( 'EPrints::Plugin::Screen' );

use strict;

sub new
{
my( $class, %params ) = @_;

my $self = $class->SUPER::new(%params);

return $self;
}

sub properties_from
{
my( $self ) = @_;

$self->{processor}->{eprint} = $self->{processor}->{document}->get_eprint;

$self->SUPER::properties_from;
}

sub render_title
{
my( $self ) = @_;

my $session = $self->{session};

my $f = $self->{session}->make_doc_fragment;

my $eprint = $self->{processor}->{eprint};
my $doc = $self->{processor}->{document};

$f->appendChild( $self->{processor}->{eprint}->render_citation( "screen" ) );

$f->appendChild( $self->{session}->html_phrase( "document_join" ) );

$f->appendChild( $self->{processor}->{document}->render_citation( "screen" ) );

return $f;
}

sub render
{
my( $self ) = @_;

my $repo = $self->{repository};
my $doc = $self->{processor}->{document};

my $page = $repo->make_doc_fragment;

my $div = $repo->make_element( "div", class => "doc_citation" );

$div->appendChild( $doc->render_citation( "landing_page", eprint => $self->{processor}->{eprint} ) );

return( $div );
}

1;
</pre>

And finally, the screen uses a citation file to display the document landing page content in an easily customisable fashion, e.g. lib/defaultcfg/citations/document/landing_page.xml

<pre>

<?xml version="1.0" ?>



<cite:citation xmlns="http://www.w3.org/1999/xhtml" xmlns:epc="http://eprints.org/ep3/control" xmlns:cite="http://eprints.org/ep3/citation" >


<epc:print expr="$eprint.citation_link('default')" />


<table>
<tr>
<td valign="top" align="right"><epc:print expr="$item.icon( 'HoverPreview', 'noNewWindow' )" /></td>
<td valign="top">
<epc:print expr="$item.citation('default')" /><br />
<a href="{$item.url()}" class="ep_document_link"><epc:phrase ref="summary_page:download"/> (<epc:print expr="$item.doc_size().human_filesize()" />)</a>
</td>
</tr>
</table>

</cite:citation>
</pre>