Editing ORCID Support (section)

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