Page History

...

User features

Login via ORCID

Once enabled an option to login via ORCID is provided to the user among the other authentication method configured in the system. The ORCID authentication doesn't allow the user to reset his password from DSpace.

Image Added..coming soon...

Connect/Disconnect the locat profile to ORCID

...coming soon...

Manage synchronization preferences

...coming soon...

Import publications from ORCID

...coming soon...

Configuration

Enable the integration

All the ORCID features requires a minimal common set of properties to configure in the local.cfg

The researcher can connect (or disconnect) his DSpace local profile with ORCID from the Person item detail page

Image Added

Once that a profile has been connected he can manage his synchronization preferences deciding what need to be pushed to ORCID among the biographic data, the publications and projects associated with his profile

Image Added

The synchronization can happen automatically over the night or manually, the list of information that need to be pushed or updated from DSpace to ORCID is presented in a queue and can be manually discarded or immediately pushed by the researcher.

Import publications from ORCID

It is possible to import publication from ORCID using the Import from external sources button in the home page. Once you select the Publication entity type you will be able to find ORCID as a Source and you can get the list of publications (ORCID works) that appear in an ORCID profile searching for its ORCID iD

Image Added

Configuration

Enable the integration

All the ORCID features requires a minimal common set of properties to configure in the local.cfg

Code Block

# Switch to production API once ready https://github.com/ORCID/ORCID-Source/tree/master/orcid-api-web#endpoints 
orcid.domain-url= https://sandbox.orcid.org
orcid.api-url = https://api

Code Block

# Switch to production API once ready https://github.com/ORCID/ORCID-Source/tree/master/orcid-api-web#endpoints 
orcid.domain-url= https://sandbox.orcid.org
orcid.api-url = https://api.sandbox.orcid.org/v3.0
orcid.application-client-id = <YOUR-ORCID-CLIENT-ID>
orcid.application-client-secret = <YOUR-ORCID-CLIENT-SECRET>

...

In the ORCID API Credentials request form you will be asked to enter one or more redirect URLs for you application (DSpace), you will need to enter here the root URL of your REST and Angular interfaces that could eventually be different, otherwise it will be sufficient to put the URL of your angular UI. For the DSpace 7 official demo these are

Angular: https://demo7.dspace.org (please note the absence of a /home or any subrouting)
REST: https://api7.dspace.org (please note the absence of a /server or any subrouting)

Once ORCID has reviewed and approved your request, you will get from them the Client ID and Client Secret that need to be set in the local.cfg among other properties (see below)

Code Block

# the properties below are required only for the sync / linking part (not for authentication or import)
orcid.synchronization-enabled = true
# you need to enable the orcidqueue consumer to keep track of what need to be sync between DSpace and ORCID
event.dispatcher.default.consumers = versioning, discovery, eperson, orcidqueue

By default DSpace will request permissions to READ and WRITE all the information from the ORCID profile as this will enable support for all the features. You can eventually fine-tuning that overriding the following properties, please note that if you are going to configure Public API Credential you MUST update this configuration keeping only the /authenticate scope as all the other scopes require member API

Code Block

# The scopes to be granted by the user during the login on ORCID (see https://info.orcid.org/faq/what-is-an-oauth-scope-and-which-scopes-does-orcid-support/)
orcid.scope = /authenticate
orcid.scope = /read-limited
orcid.scope = /activities/update
orcid.scope = /person/update

The push of DSpace data (Person, Publication, Project) to ORCID is based on mapping defined in the config/modules/orcid.cfg file,

URL of your REST and Angular interfaces that could eventually be different, otherwise it will be sufficient to put the URL of your angular UI. For the DSpace 7 official demo these are

Angular: https://demo7.dspace.org (please note the absence of a /home or any subrouting)
REST: https://api7.dspace.org (please note the absence of a /server or any subrouting)

Once ORCID has reviewed and approved your request, you will get from them the Client ID and Client Secret that need to be set in the local.cfg among other properties (see below)

Code Block

# the properties below are required only for the sync / linking part (not for authentication or import)
orcid.synchronization-enabled = true
# you need to enable the orcidqueue consumer to keep track of what need to be sync between DSpace and ORCID
event.dispatcher.default.consumers = versioning, discovery, eperson, orcidqueue

Please note that by default DSpace will request permissions to READ and WRITE all the information from the ORCID profile as this will enable support for all the features. You can eventually fine-tuning that overriding the following properties, please note that if you are going to configure Public API Credential you MUST update this configuration keeping only the /authenticate scope as all the other scopes require member API

Code Block

# The scopes to be granted by the user during the login on ORCID (see https://info.orcid.org/faq/what-is-an-oauth-scope-and-which-scopes-does-orcid-support/)
orcid.scope = /authenticate
orcid.scope = /read-limited
orcid.scope = /activities/update
orcid.scope = /person/update

The push of DSpace data (Person, Publication, Project) to ORCID is based on mappings defined in the config/modules/orcid.cfg file, more details below in the dedicated paragraphs.

To enable the ORCID Authentication you need to uncomment the following line in the modules/authentication.cfg file or adding it to your local.cfg

Code Block
plugin.sequence.org.dspace.authenticate.AuthenticationMethod = org.dspace.authenticate.OrcidAuthentication

Please note that you are NOT required to enable the ORCID Authentication to use the other ORCID features, including the synchronisation ones. It is also possible to use just the ORCID Authentication without enabling all the other features.

When an user logged-in via ORCID the system will attempt to reuse an existing account looking up by email, if none is found a new account is created in DSpace. It is eventually possible to disable the creation of new accounts settings the following property

Code Block
authentication-orcid.can-self-register = false

Configure the push of information from DSpace to ORCID

Please note that many fields on the ORCID side are subject to validation, i.e. only values from controlled-list can be used and some fields are mandatory. The table below summarize the validation that are defined at the time of DSpace 7.3, ORCID update such rules periodically usually modifying (enlarging) the controlled-list, change to the mandatory fields can also happen

ORCID Entity	Mandatory fields	Controlled fields
Person		Country (iso-3166 2 code letter)
Work	Title Type Publication Date (>= 1900) External Identifier (at least one)	Type (https://info.orcid.org/documentation/integration-and-api-faq/#easy-faq-2682) Identifier.Type (https://pub.orcid.org/v3.0/identifiers)
Funding	Title External Identifier (at least one) Funding Agency (Organisation) Currency if an Amount is provided	Amount.Currency (https://www.iso.org/iso-4217-currency-codes.html)
Organisation	External Identifier (at least one) Address City Country	See https://support.orcid.org/hc/en-us/articles/360006894674-Metadata-in-the-Funding-section Country (iso-3166 2 code letter) Identifier.Type (ROR, LEI, CrossRef Funder ID, RINGOLD, GRID)

To provide more meaningful message to the user DSpace implements a local validation before to try to push the record to ORCID. This validation verify the rules above so that a specific message is displaied to the user. If for any reason another errors is returned by ORCID a generic message is show to the user and the exact technical message received by ORCID is logged in the dspace.log file and stored in the orcidhistory table.

The local validation can be eventually turned-off, this is mainly intended as a development/debug option and should be not enabled in production

Code Block
orcid.validation.work.enabled = true orcid.validation.funding.enabled = true

Mapping of the DSpace Person Items to ORCID Works

Metadata in a DSpace "Person" item, once that the item has been linked to ORCID by the researcher owning the ORCID profile, can be pushed to ORCID to fill specific Profile Section of the ORCID Person using the org.dspace.orcid.service.OrcidProfileSectionFactoryService configured via this mapping bean

Code Block

    <!-- Configuration of ORCID profile sections factory. 
    Each entry of sectionFactories must be an implementation of OrcidProfileSectionFactory.-->
    <bean class="org.dspace.orcid.service.impl.OrcidProfileSectionFactoryServiceImpl">
    	<constructor-arg name="sectionFactories">
    		<list>
    		
    			<bean class="org.dspace.orcid.model.factory.impl.OrcidSimpleValueObjectFactory">
					<constructor-arg name="sectionType" value="OTHER_NAMES" />
					<constructor-arg name="preference" value="BIOGRAPHICAL" />
					<property name="metadataFields" value="${orcid.mapping.other-names}" />
				</bean>
				
    			<bean class="org.dspace.orcid.model.factory.impl.OrcidSimpleValueObjectFactory">
					<constructor-arg name="sectionType" value="KEYWORDS" />
					<constructor-arg name="preference" value="BIOGRAPHICAL" />
					<property name="metadataFields" value="${orcid.mapping.keywords}" />
				</bean>
				
    			<bean class="org.dspace.orcid.model.factory.impl.OrcidSimpleValueObjectFactory">
					<constructor-arg name="sectionType" value="COUNTRY" />
					<constructor-arg name="preference" value="BIOGRAPHICAL" />
					<property name="metadataFields" value="${orcid.mapping.country}" />
				</bean>
				
    			<bean class="org.dspace.orcid.model.factory.impl.OrcidPersonExternalIdentifierFactory">
					<constructor-arg name="sectionType" value="EXTERNAL_IDS" />
					<constructor-arg name="preference" value="IDENTIFIERS" />
					<property name="externalIds" value="${orcid.mapping.person-external-ids}" />
				</bean>
				
    			<bean class="org.dspace.orcid.model.factory.impl.OrcidSimpleValueObjectFactory">
					<constructor-arg name="sectionType" value="RESEARCHER_URLS" />
					<constructor-arg name="preference" value="IDENTIFIERS" />
					<property name="metadataFields" value="${orcid.mapping.researcher-urls}" />
				</bean>
				
    		</list>
    	</constructor-arg>
    </bean>

the above configuration link each piece of information that can be synchronized from DSpace to ORCID to a preference that the user can manage on the DSpace side (i.e. sync of the keywords is linked to the BIOGRAPHICAL preference) and define which DSpace metadata will be used to fill the ORCID field. The bean reads the metadata mapping from the config/modules/orcid.cfg

Code Block

### Other names mapping ###
orcid.mapping.other-names = person.name.variant
orcid.mapping.other-names = person.name.translated

### Keywords mapping ###
orcid.mapping.keywords = dc.subject

### Country mapping ###
orcid.mapping.country = person.country
orcid.mapping.country.converter =

### Person External ids mapping ###
##orcid.mapping.person-external-ids syntax is <metadatafield>::<type>
orcid.mapping.person-external-ids = person.identifier.scopus-author-id::SCOPUS
orcid.mapping.person-external-ids = person.identifier.rid::RID

### Researcher urls mapping ###
orcid.mapping.researcher-urls = dc.identifier.uri

Mapping of DSpace Publication items to ORCID Works

A DSpace "Publication" item is pushed to ORCID as a "Work" using the org.dspace.orcid.model.factory.impl.OrcidWorkFactory configured via this mapping bean

Code Block

	<bean id="orcidWorkFactoryFieldMapping" class="org.dspace.app.orcid.model.OrcidWorkFieldMapping" >
		<property name="contributorFields" value="${orcid.mapping.work.contributors}" />
		<property name="externalIdentifierFields" value="${orcid.mapping.work.external-ids}" />
		<property name="publicationDateField" value="${orcid.mapping.work.publication-date}" />
		<property name="titleField" value="${orcid.mapping.work.title}" />
		<property name="journalTitleField" value="${orcid.mapping.work.journal-title}" />
		<property name="shortDescriptionField" value="${orcid.mapping.work.short-description}" />
		<property name="subTitleField" value="${orcid.mapping.work.sub-title}" />
		<property name="languageField" value="${orcid.mapping.work.language}" />
		<property name="languageConverter" ref="${orcid.mapping.work.language.converter}" />
		<property name="typeField" value="${orcid.mapping.work.type}" />
		<property name="typeConverter" ref="${orcid.mapping.work.type.converter}" />
		<property name="citationType" value="${orcid.mapping.work.citation.type}" />
	</bean>

that respectively read the mapping from the config/modules/orcid.cfg file

Code Block

### Work (Publication) mapping ###
orcid.mapping.work.title = dc.title
orcid.mapping.work.sub-title =
orcid.mapping.work.short-description = dc.description.abstract
orcid.mapping.work.publication-date = dc.date.issued
orcid.mapping.work.language = dc.language.iso
orcid.mapping.work.language.converter = mapConverterDSpaceToOrcidLanguageCode
orcid.mapping.work.journal-title = dc.relation.ispartof
orcid.mapping.work.type = dc.type
orcid.mapping.work.type.converter = mapConverterDSpaceToOrcidPublicationType

##orcid.mapping.work.contributors syntax is <metadatafield>::<role>
orcid.mapping.work.contributors = dc.contributor.author::author
orcid.mapping.work.contributors = dc.contributor.editor::editor

##orcid.mapping.work.external-ids syntax is <metadatafield>::<type> or $simple-handle::<type>
##The full list of available external identifiers is available here https://pub.orcid.org/v3.0/identifiers
orcid.mapping.work.external-ids = dc.identifier.doi::doi
orcid.mapping.work.external-ids = dc.identifier.scopus::eid
orcid.mapping.work.external-ids = dc.identifier.pmid::pmid
orcid.mapping.work.external-ids = $simple-handle::handle
orcid.mapping.work.external-ids = dc.identifier.isi::wosuid
orcid.mapping.work.external-ids = dc.identifier.issn::issn

in the above configuration the "simple" properties are mapped matching the ORCID field name on the left (i.e. short-description) with the DSpace metadata that holds such information (i.e dc.description.abstract). For the ORCID Type field a special "converter" is configured so that the value of the DSpace metadata (i.e. dc.type) is mapped to the controlled-list of types accepted by ORCID (https://info.orcid.org/faq/what-work-types-does-orcid-support/). The value of the orcid.mapping.work.type.converter matches the name of a bean defined in the config/spring/api/orcid-services.xml

Code Block

    <bean name="mapConverterDSpaceToOrcidPublicationType" class="org.dspace.util.SimpleMapConverter" init-method="init">
		<property name="converterNameFile" value="orcid/mapConverter-dspace-to-orcid-publication-type.properties" />
		<property name="configurationService" ref="org.dspace.services.ConfigurationService" />
		<property name="defaultValue" value="other"/>
	</bean>

Finally a special treatment is needed for the external ids as this is a complex field on the ORCID side composed by two value, the identifier type (from a controlled-list) and the identifier value. In this case the configuration allow to map a DSpace metadata (i.e. dc.identifier.doi) to a specific identifier type (i.e. the part after :: , doi).

Mapping of DSpace Project items to ORCID Funding

A DSpace "Project" item is pushed to ORCID as a "Funding" using the org.dspace.orcid.model.factory.impl.OrcidFundingFactory configured via this mapping bean

Code Block

	<bean id="orcidFundingFactoryFieldMapping" class="org.dspace.orcid.model.OrcidFundingFieldMapping" >
		<property name="contributorFields" value="${orcid.mapping.funding.contributors}" />
		<property name="externalIdentifierFields" value="${orcid.mapping.funding.external-ids}" />
		<property name="titleField" value="${orcid.mapping.funding.title}" />
		<property name="typeField

Code Block

	<bean id="orcidWorkFactoryFieldMapping" class="org.dspace.app.orcid.model.OrcidWorkFieldMapping" >
		<property name="contributorFields" value="${orcid.mapping.workfunding.contributorstype}" />
		<property name="externalIdentifierFieldstypeConverter" valueref="${orcid.mapping.funding.worktype.external-idsconverter}" />
		<property name="publicationDateFieldamountField" value="${orcid.mapping.workfunding.publication-dateamount}" />
		<property name="titleFieldamountCurrencyField" value="${orcid.mapping.funding.workamount.titlecurrency}" />
		<property name="journalTitleFieldamountCurrencyConverter" valueref="${orcid.mapping.funding.work.journal-titleamount.currency.converter}" />
		<property name="shortDescriptionFielddescriptionField" value="${orcid.mapping.workfunding.short-description}" />
		<property name="subTitleFieldstartDateField" value="${orcid.mapping.workfunding.substart-titledate}" />
		<property name="languageFieldendDateField" value="${orcid.mapping.workfunding.languageend-date}" />
		<property name="languageConverterorganizationRelationshipType" refvalue="${orcid.mapping.work.language.converterfunding.organization-relationship-type}" />
		<property name="typeField" value="${</bean>

that respectively read the mapping from the config/modules/orcid.cfg file

Code Block

### Funding mapping ###
orcid.mapping.funding.title = dc.title
orcid.mapping.workfunding.type}" />
		<property name="typeConverter" ref="${ 
orcid.mapping.workfunding.type.converter}" />
		<property name="citationType" value="${orcid.mapping.work.citation.type}" />
	</bean>

that respectively read the mapping from the config/modules/orcid.cfg file

Code Block

### Work (Publication) mapping ###.converter = mapConverterDSpaceToOrcidFundingType
##orcid.mapping.funding.external-ids syntax is <metadatafield>::<type> 
##The full list of available external identifiers is available here https://pub.orcid.org/v3.0/identifiers
orcid.mapping.workfunding.titleexternal-ids = dc.titleidentifier::grant_number
orcid.mapping.workfunding.subexternal-titleids = dc.identifier.other::other-id
orcid.mapping.workfunding.short-description = dc.description.abstract
orcid.mapping.workfunding.publicationstart-date = dc.date.issued
orcidproject.startDate
orcid.mapping.funding.end-date = project.endDate
##orcid.mapping.workfunding.languagecontributors syntax = dc.language.isois <metadatafield>::<type>
orcid.mapping.workfunding.language.convertercontributors = mapConverterDSpaceToOrcidLanguageCodeproject.investigator::lead
orcid.mapping.workfunding.journalorganization-relationship-titletype = dc.relation.ispartofisOrgUnitOfProject
orcid.mapping.workfunding.typeamount = dcproject.typeamount
orcid.mapping.workfunding.typeamount.convertercurrency = mapConverterDSpaceToOrcidPublicationType

##orcidproject.amount.currency
orcid.mapping.work.contributors syntax is <metadatafield>::<role>
orcid.mapping.work.contributors = dc.contributor.author::author
orcid.mapping.work.contributors = dc.contributor.editor::editor

##orcid.mapping.work.external-ids syntax is <metadatafield>::<type> or $simple-handle::<type>
##The full list of available external identifiers is available here https://pub.orcid.org/v3.0/identifiers
orcid.mapping.work.external-ids = dc.identifier.doi::doi
orcid.mapping.work.external-ids = dc.identifier.scopus::eid
orcid.mapping.work.external-ids = dc.identifier.pmid::pmid
orcid.mapping.work.external-ids = $simple-handle::handle
orcid.mapping.work.external-ids = dc.identifier.isi::wosuid
orcid.mapping.work.external-ids = dc.identifier.issn::issn

To enable the ORCID Authentication you need to uncomment the following line in the modules/authentication.cfg file or adding it to your local.cfg

Code Block
plugin.sequence.org.dspace.authenticate.AuthenticationMethod = org.dspace.authenticate.OrcidAuthentication

...

funding.amount.currency.converter = mapConverterDSpaceToOrcidAmountCurrency

in the above configuration the "simple" properties are mapped matching the ORCID field name on the left (i.e. description) with the DSpace metadata that holds such information (i.e dc.description). For the ORCID Type field a special "converter" is configured so that the value of the DSpace metadata (i.e. dc.type) is mapped to the controlled-list of types accepted by ORCID (https://support.orcid.org/hc/en-us/articles/360006894674-Metadata-in-the-Funding-section). The value of the orcid.mapping.funding.type.converter matches the name of a bean defined in the config/spring/api/orcid-services.xml the same apply for the currency orcid.mapping.funding.amount.currency.converter = mapConverterDSpaceToOrcidAmountCurrency

Code Block

<bean name="mapConverterDSpaceToOrcidFundingType" class="org.dspace.util.SimpleMapConverter" init-method="init">
	<property name="converterNameFile" value="orcid/mapConverter-dspace-to-orcid-funding-type.properties" />
	<property name="configurationService" ref="org.dspace.services.ConfigurationService" />
	<property name="defaultValue" value=""/>
</bean>

<bean name="mapConverterDSpaceToOrcidAmountCurrency" class="org.dspace.util.SimpleMapConverter" init-method="init">
	<property name="converterNameFile" value="orcid/mapConverter-dspace-to-orcid-amount-currency.properties" />
	<property name="configurationService" ref="org.dspace.services.ConfigurationService" />
	<property name="defaultValue" value=""/>
</bean>

Finally a special treatment is needed for Funder that is a mandatory field on the ORCID side, in this case the mapping allow to define which relation is used to link the Project with the Funder (OrgUnit)

Code Block
orcid.mapping.funding.organization-relationship-type = isOrgUnitOfProject

Configure the import features

...

that respectively read the mapping from the config/modules/orcid.cfg file

Info
Please note that such mapping is separated from the mapping used to push information from DSpace to ORCID but usually, as provided in the default configuration, the mapping should be the same

Code Block

### Work (Publication) external-data.mapping ###
orcid.external-data.mapping.publication.title = dc.title

orcid.external-data.mapping.publication.description = dc.description.abstract
orcid.external-data.mapping.publication.issued-date = dc.date.issued
orcid.external-data.mapping.publication.language = dc.language.iso
orcid.external-data.mapping.publication.language.converter = mapConverterOrcidToDSpaceLanguageCode
orcid.external-data.mapping.publication.is-part-of = dc.relation.ispartof
orcid.external-data.mapping.publication.type = dc.type
orcid.external-data.mapping.publication.type.converter = mapConverterOrcidToDSpacePublicationType

##orcid.external-data.mapping.publication.contributors syntax is <metadatafield>::<role>
orcid.external-data.mapping.publication.contributors = dc.contributor.author::author
orcid.external-data.mapping.publication.contributors = dc.contributor.editor::editor

##orcid.external-data.mapping.publication.external-ids syntax is <metadatafield>::<type> or $simple-handle::<type>
##The full list of available external identifiers is available here https://pub.orcid.org/v3.0/identifiers
orcid.external-data.mapping.publication.external-ids = dc.identifier.doi::doi
orcid.external-data.mapping.publication.external-ids = dc.identifier.scopus::eid
orcid.external-data.mapping.publication.external-ids = dc.identifier.pmid::pmid
orcid.external-data.mapping.publication.external-ids = dc.identifier.isi::wosuid
orcid.external-data.mapping.publication.external-ids = dc.identifier.issn::issn

...

via an ORCID lookup authority available for DSpace repository that are not using Configurable Entities
via a relation among the research output item (Publication, etc.) and a Person Item bind to the ORCID Person External Source defined in the previous paragraph

Configure the push of information from DSpace to ORCID

...

Trouble-shooting & common issues

...

All Versions

DSpace Documentation

Page tree

Versions Compared

Old Version 2

New Version 3

Key

User features

Login via ORCID

Connect/Disconnect the locat profile to ORCID

Manage synchronization preferences

Import publications from ORCID

Configuration

Enable the integration

Import publications from ORCID

Configuration

Enable the integration

Configure the push of information from DSpace to ORCID

Mapping of the DSpace Person Items to ORCID Works

Mapping of DSpace Publication items to ORCID Works

Mapping of DSpace Project items to ORCID Funding

Configure the import features

Configure the push of information from DSpace to ORCID

Trouble-shooting & common issues