Introduction
DSpace-CRIS provides the most advanced and complete integration between a CRIS / Repository system and ORCID achieving most of the ORCID integration use cases.
The available functionalities depend on the kind of API Key that you have, Public or Member. You must configure your client-id, client secret and specify the endpoint appropriate for your API level in the
[dspace-installDir]/config/modules/authentication-oauth.cfg (via build.properties)
# The client id value <client-id> from ORCID client application registration application-client-id=${authentication-oauth.application-client-id} # The client secret value <client-secret> from ORCID client application registration application-client-secret=${authentication-oauth.application-client-secret} # Public API: http://pub.orcid.org/ # Public API Sandbox: http://pub.sandbox.orcid.org/ # Member API: https://api.orcid.org/ # Member API Sandbox: http://api.sandbox.orcid.org/ orcid-api-url=${authentication-oauth.orcid-api-url} # Th Redirect URL should be constructed off your dspace url in the following manner: # http://dspace.my/jspui/oauth-login # or if deployed as ROOT application # http://dspace.my/oauth-login application-redirect-uri=${authentication-oauth.application-client-redirect} # Developers Sandbox http://sandbox.orcid.org/oauth/authorize # Production Registry http://orcid.org/oauth/authorize application-authorize-url=${authentication-oauth.application-authorize-url} # PUBLIC API authentication-oauth.application-client-scope =/authenticate # MEMBER API #authentication-oauth.application-client-scope =/authenticate /orcid-profile/read-limited /orcid-bio/update /orcid-works/create /orcid-works/update /funding/create /funding/update /activities/update
Authentication
The ORCID authentication is enabled by default in DSpace-CRIS, nevertheless you need to configure the key properties listed in the above introduction.
The following properties are specific of the authentication integration
autoregister=true choice-page=false orcid-embedded-login=true
the autoregister flag is auto-explaining, choice-page if true list the ORCID authentication explicitly as an authentication methods so that if you have multiple authentication methods configured such as LDAP, Shibboleth, etc. ORCID is listed in the choice page. The orcid-embedded-login is the preferred mode, a Login with ORCID button is displayed side-by-side the password or ldap authentication.
Profile claiming
When the ORCID Authentication is enabled and the autoregister flag is true it is possible for a researcher to claim an existent researcher profile that have an ORICD in DSpace-CRIS just logging in. Indeed, when the user login the system will create an user account using the information from ORCID and if his ORCID match one already assigned to an orphan researcher profile this new account become the owner of the profile. In such way, external collaborators can login in the system and gains limited privileges to improve their profile without any explicit activity by the repository staff.
Creation of a local researcher profile
When the user is logged in via ORCID and proceed to create his local researcher profile the system automatically captures from ORCID several information:
Submission lookup
A special authority is build-in DSpace-CRIS to use the ORCID registry togheter with the internal directory of researchers as authority list for metadata editing
More information on the authority framework can be found in the official DSpace documentation, the relevant configuration are in the dspace.cfg file as listed below
plugin.named.org.dspace.content.authority.ChoiceAuthority = \ org.dspace.app.cris.integration.ORCIDAuthority = RPAuthority,\ ... choices.plugin.dc.contributor.author = RPAuthority choices.presentation.dc.contributor.author = lookup authority.controlled.dc.contributor.author = true ...
For this functionality the use of a member API key or a public API key impact only on the performance and acceptable rate of request to the ORCID service. As you are looking for ORCID profile of unknown researchers only the public information about such researcher are returned
The org.dspace.app.cris.integration.ORCIDAuthority combines the result retrieved from the internal researchers database with the ones found in ORCID giving precedence to the internal matches. When an author name is selected from the ORCID registry returned list a temporary authority key tracking the ORCID is assigned to the metadata. This information is used when the publication is approved to generate a local researcher profile retrieving further information about the researcher from the ORCID registry such as his biography, email address, name variants, etc more information on this process are available here
Synchronization
DSpace-CRIS is able to capture (Public or Member API) and send information (Member API only) from and to ORCID.
from ORCID to DSpace-CRIS
The dataflow from ORCID to DSpace-CRIS happen in two scenarios:
- when an user that has been authenticated via ORCID create his researcher profile
- when an author of a publication is looked up in the ORCID registry during the submission
The scenario #1 has been discussed in the Authentication > Creating a local researcher profile section
The scenario #2 has been discussed in the Submission lookup section.
Currently it is not possible to import from ORCID information related to other entities like:
- publications
- projects
- organisations
from DSpace-CRIS to ORCID
If the researcher grants permission to DSpace-CRIS to update his ORCID profile, this is done during the authentication via ORCID or directly from the ORCID tab in the researcher profile, DSpace-CRIS is able to send these local information to ORCID (below the shortname of the property as in the default configuration):
affiliation
authorid
biography
education
email
fullName
country
keywords
otheremails
other-emails
personalsite
preferredName
scopusid
variants
the researcher can set his own preferences about the synchronization both about which information needs to be send than how/when this happen (automatically or manually). All the preferences are stored as property in the researcher profile.
To configure which information are sent to ORCID the researcher needs to edit his profile, in the default configuration a tab named ORCID (shortname:"orcid") with a box named ORCID Synchronization settings (shortname:"orcidsyncsettings") is included that allow to
- define which publications to send: all, only publications selected, only publications not hidden (see ), none
- define which projects to send: all, only projects selected, only projects not hidden (see ), none
- define which biographic information will be send
The synchronization procedures use a convention to discover which preference are available, see Mapping local properties to ORCID below.
The system monitors changes to the researcher profile and linked entities (publications and projects) putting in a queue (the orcid_queue table on the database) the list of objects that it is necessary to synchronize. This is done for the DSpace items via a consumer enabled by default in the dspace.cfg
event.dispatcher.default.consumers = versioning, discovery, eperson, harvester, orcidpush, crisorcid, itemauthority, dedup ... # orcid push consumer event.consumer.orcidpush.class = org.dspace.app.cris.integration.authority.CrisOrcidQueueConsumer event.consumer.orcidpush.filters = Item+INSTALL|MODIFY_METADATA|MODIFY
and for the CRIS entites with a model listner org.dspace.app.cris.model.listener.OrcidQueueListener enabled via spring
<bean id="ORCIDListener" class="org.dspace.app.cris.model.listener.OrcidQueueListener"> <property name="orcidPreferencesUtils" ref="orcidPreferencesUtils" /> </bean>
The synchronization can happen automatically via a batch script that need to be configured as a CRON Job without parameters
./dspace dsrun org.dspace.app.cris.batch.ScriptPushOrcid
or triggered manually by the researcher. A custom box ORCID Registry Queue ("orcidsyncqueue") is included in the default configuration to show the queue of object to synchronize and allow manual processing.
If a researcher set the synchronization mode to "manual" the normal execution of the synchronization script cause to send a reminder email to the researcher with pending synchronization actions (email template: orcid-alerts)
The script can be also used from the command line to force a first push of information to ORCID indipendently by the content of the ORCID queue table
./dspace dsrun org.dspace.app.cris.batch.ScriptPushOrcid [-a | -s <crisID>] [-p]
-a process all the researcher
-s process a single researcher, whom with the specified crisID
-p force the script to use POST call to ORCID instead of PUT (put is more efficient but replace all the existent publications, projects, organisations in the ORCID profile created from DSpace-CRIS with the new value. POST will just append the new values). Please note that information input manually by the researcher in his ORCID profile or created in his profile by other system (like crossref, scopus, etc.) cannot be never overridden by DSpace-CRIS
Mapping local properties to ORCID
The shortname of all the ORCID preference flags start with orcid-profile-pref- and end with the shortname of the property that need to be syncronized with ORCID. The label of the preference property must match the name of the target Element in the ORCID XML message in this way you can easily set a custom mapping for your extra or renamed properties.
The default configuration is
Preference shortname | DSpace-CRIS property | ORCID property |
---|---|---|
orcid-profile-pref-affiliation | affiliation | affiliations-employment |
orcid-profile-pref-authorid | authorid | external-identifier-Researcher ID |
orcid-profile-pref-biography | biography | biography |
orcid-profile-pref-education | education | affiliations-education |
orcid-profile-pref-email | primary-email | |
orcid-profile-pref-fullName | fullName | name |
orcid-profile-pref-iso-3166-country | country | iso-3166-country |
orcid-profile-pref-keywords | keywords | keywords |
orcid-profile-pref-otheremails | otheremails | other-emails |
orcid-profile-pref-personalsite | personalsite | researcher-urls |
orcid-profile-pref-preferredName | preferredName | credit-name |
orcid-profile-pref-scopusid | scopusid | external-identifier-Scopus Author ID |
orcid-profile-pref-variants | variants | other-names |
ORCID as a local profile URL
Each property containing unique values can be used to address an researcher profile in DSpace-CRIS with a more meaningful URL than using the internal stable CRIS ID. This functionality is very useful in conjuction with ORCID so that
[dspace.url]/cris/rp/details.html?lt=orcid&lv=[ORCiD ID]