Scenario: A new researcher joins the institution and logins for the first time in the repository. The publication claim services found most of their publications in the OpenAIRE network and prompts for import. The researcher reviews the list, confirms the authorship and imports the publication saving a significant amount of (often publicly payed) time. Moreover, the authorship confirmation will come back later to OpenAIRE offering useful information about the data quality and potential enrichment. The same applies for publications authored by researchers in different institutes, having the data in multiple repositories makes the data more reliable and raises the chance to get more information and content from any of the authors.
The goal of the Publication Claim service is to support such scenarios by simplifying the publication import process and enhancing metadata quality across ecosystems.
This feature is designed to be provider-agnostic, supporting integration with multiple external sources simultaneously.
Currently, the service supports:
OpenAIRE Research Graph, via its Publication REST API.
OpenAlex, using its public API.
In order to use Publication Claim, you MUST first enable:
No additional settings are required, but this feature only works for users who have a Researcher Profile established, and when Quality Assurance is enabled.
The publication claim service queries external APIs (e.g., OpenAIRE and OpenAlex) using researcher information available in the repository (e.g., names, identifiers). The results are processed through a configurable pipeline of Java classes that score and filter the publications based on various criteria. Records previously rejected by the researcher are automatically filtered out to prevent redundant suggestions.
Providers are configured in the Spring configuration file:dspace/config/spring/api/suggestions.xml
The OpenAIRE Publication REST API are used to retrieve publication that could be authored by researcher at the Institution. The OpenAIRE Publication REST API are queried using the names known by the repository for its researchers, the retrieve list is later reduced passing identified publications to a pipeline of JAVA classes that can promote or reject his inclusion in the suggestion list. Publications previously discarded by the researcher are automatically filter out avoiding to re-present the same publication again and again.
The suggestion providers are defined in the dspace/config/spring/api/suggestions.xml spring configuration file.
<util:map id="suggestionProviders" map-class="java.util.HashMap"
key-type="java.lang.String" value-type="org.dspace.app.suggestion.SuggestionProvider">
<entry key="openaire" value-ref="OpenairePublicationLoader" />
<entry key="openalex" value-ref="OpenAlexPublicationLoader"/>
</util:map>
<!-- OpenAIRE -->
<bean id="OpenairePublicationLoader" class="org.dspace.app.suggestion.loader.PublicationLoader">
<property name="sourceName" value="openaire" />
<property name="primaryProvider" ref="openaireLiveImportDataProviderByAuthor" />
<property name="otherProviders">
<list>
<ref bean="openaireLiveImportDataProviderByTitle"/>
</list>
</property>
<property name="names">
<list>
<value>dc.title</value>
</list>
</property>
<property name="pipeline">
<list>
<bean
class="org.dspace.app.suggestion.scorer.AuthorNamesScorer">
<property name="contributorMetadata">
<list>
<value>dc.contributor.author</value>
</list>
</property>
<property name="names">
<list>
<value>dc.title</value>
</list>
</property>
</bean>
<bean
class="org.dspace.app.suggestion.scorer.DateScorer">
<property name="birthDateMetadata" value="person.birthDate" />
<property name="publicationDateMetadata" value="dc.date.issued" />
</bean>
</list>
</property>
</bean>
<!-- OpenAlex -->
<bean id="OpenAlexPublicationLoader" class="org.dspace.app.suggestion.openalex.OpenAlexPublicationLoader">
<property name="sourceName" value="openalex"/>
<property name="primaryProvider" ref="openalexPublicationByAuthorIdLiveImportDataProvider"/>
<property name="otherProviders">
<list>
<ref bean="openalexPublicationLiveImportDataProvider"/>
</list>
</property>
<property name="names">
<list>
<value>dc.identifier.openalex</value>
<value>dc.title</value>
</list>
</property>
<property name="pipeline">
<list>
<bean class="org.dspace.app.suggestion.scorer.AuthorNamesScorer">
<property name="contributorMetadata">
<list>
<value>dc.contributor.author</value>
</list>
</property>
<property name="names">
<list>
<value>dc.title</value>
</list>
</property>
</bean>
</list>
</property>
</bean> |
Each SuggestionProvider is identified by a unique name used as a key in the suggestionProviders map defined in the Spring configuration file.
The provider implementation is handled by the Java class org.dspace.app.suggestion.loader.PublicationLoader, and it is configured via the following properties:
primaryProvider: Specifies which ExternalDataProvider to use for retrieving publication records (e.g., openaireLiveImportDataProviderByAuthor).
otherProviders: A list of additional ExternalDataProviders that may return overlapping records. This is used to automatically remove from the suggestion list records that are imported manually by the researcher from these other providers.
names: A list of metadata fields used to construct the search query against the external data provider.
pipeline: Defines the list of scorers used to evaluate the results.
AuthorNamesScorer: Ensures the suggested publication truly belongs to the researcher, mitigating false positives due to name collisions. For example, a query for "Bollini Susanna" might incorrectly match works co-authored by "Andrea Bollini" and "Susanna Mornati".
DateScorer: Validates the publication date against an expected activity range for the researcher. This range is calculated based on available metadata like birth date or graduation date, but can also be set manually in the Researcher Profile.
The DSpace script class org.dspace.app.suggestion.runnable.PublicationLoaderRunnableCli is responsible for querying all configured suggestion providers (e.g., OpenAIRE, OpenAlex) and storing the resulting publication suggestions in the dedicated SOLR core for further processing and display.
This script is provider-agnostic: it dynamically uses the list of SuggestionProviders configured in the Spring context. Therefore, as long as a provider (like OpenAIRE or OpenAlex) is defined and enabled, its results will be retrieved and processed automatically.
You can run the script from the command line or the Script UI.
To run the loader from the dspace installation bin folder
./dspace import-loader-suggestions [-l suggestion-provider] [-s uuid-of-single-researcher] |
without the s parameter the script will process all the researcher available in the system.
The script can be also run from the Script UI so that it is also available to repository manager that cannot be access the CLI.
Two external source providers, openAIRE Publications By Title and By Author have been defined according to the standard DSpace External Sources framework. It is activated in the config/spring/api/external-services.xml as follow
<bean id="openaireLiveImportDataProviderByAuthor" class="org.dspace.external.provider.impl.LiveImportDataProvider">
<property name="metadataSource" ref="openaireImportServiceByAuthor"/>
<property name="sourceIdentifier" value="openaire"/>
<property name="recordIdMetadata" value="dc.identifier.other"/>
<property name="supportedEntityTypes">
<list>
<value>Publication</value>
</list>
</property>
</bean>
<bean id="openaireLiveImportDataProviderByTitle" class="org.dspace.external.provider.impl.LiveImportDataProvider">
<property name="metadataSource" ref="openaireImportServiceByTitle"/>
<property name="sourceIdentifier" value="openaireTitle"/>
<property name="recordIdMetadata" value="dc.identifier.other"/>
<property name="supportedEntityTypes">
<list>
<value>Publication</value>
</list>
</property>
</bean> |
with the importer services defined via the Live Import Framework in /dspace-api/src/main/resources/spring/spring-dspace-addon-import-services.xml as follow
<bean id="openaireImportServiceByAuthor"
class="org.dspace.importer.external.openaire.service.OpenAireImportMetadataSourceServiceImpl" scope="singleton">
<property name="metadataFieldMapping" ref="openaireMetadataFieldMapping"/>
<property name="queryParam" value="author"/>
</bean>
<bean id="openaireImportServiceByTitle"
class="org.dspace.importer.external.openaire.service.OpenAireImportMetadataSourceServiceImpl" scope="singleton">
<property name="metadataFieldMapping" ref="openaireMetadataFieldMapping"/>
<property name="queryParam" value="title"/>
</bean>
<bean id="openaireMetadataFieldMapping"
class="org.dspace.importer.external.openaire.service.metadatamapping.OpenAireFieldMapping">
</bean> |
The mapping between the openAIRE Publications metadata and the dspace metadata is provided in the config/spring/api/openaire-integration.xml using the usual xpath approach of the DSpace Live Import Framework.
Having used the Live Import Framework internally to the loader to perform the query has had the side benefit to make available the publication data of the openAIRE Research Graph also to the direct import functionality of DSpace, so that the researcher can now query the openAIRE graph and import publication on demand.
The OpenAlex integration defines multiple external source providers using the standard DSpace External Sources framework. These providers enable live import of metadata for various entity types such as publications, people, journals, institutions, and more.
They are configured in the config/spring/api/external-services.xml file and follow the LiveImportDataProvider model.
Only two external providers are used in the context of publication claim:
<bean id="openalexPublicationLiveImportDataProvider"
class="org.dspace.external.provider.impl.LiveImportDataProvider">
<property name="metadataSource" ref="openalexImportPublicationService"/>
<property name="sourceIdentifier" value="openalexPublication"/>
<property name="recordIdMetadata" value="dc.identifier.openalex"/>
<property name="supportedEntityTypes">
<list>
<value>Publication</value>
<value>none</value>
</list>
</property>
</bean>
<bean id="openalexPublicationByAuthorIdLiveImportDataProvider"
class="org.dspace.external.provider.impl.LiveImportDataProvider">
<property name="metadataSource" ref="openalexImportPublicationByAuthorIdService"/>
<property name="sourceIdentifier" value="openalexPublicationByAuthorId"/>
<property name="recordIdMetadata" value="dc.identifier.openalex"/>
<property name="supportedEntityTypes">
<list>
<value>Publication</value>
<value>none</value>
</list>
</property>
</bean> |
metadataSource: The service responsible for retrieving and transforming data from OpenAlex.
sourceIdentifier: A unique string used to refer to this source throughout the system.
recordIdMetadata: The metadata field used to store the unique OpenAlex identifier (e.g., dc.identifier.openalex).
supportedEntityTypes: Lists which DSpace entity types this provider supports (e.g., Publication, Person, OrgUnit).
Each provider bean is linked to a metadata source service (or "importer service") defined via the Live Import Framework. These services are configured in the file:
/dspace-api/src/main/resources/spring/spring-dspace-addon-import-services.xml |
They are defined as follows:
<bean id="openalexImportPublicationService"
class="org.dspace.importer.external.openalex.service.OpenAlexImportMetadataSourceServiceImpl">
<property name="metadataFieldMapping" ref="openalexPublicationMetadataFieldMapping"/>
<property name="url" value="${openalex.url.works}"/>
</bean>
<bean id="openalexImportPublicationByAuthorIdService"
class="org.dspace.importer.external.openalex.service.OpenAlexImportMetadataSourceServiceImpl">
<property name="metadataFieldMapping" ref="openalexPublicationMetadataFieldMapping"/>
<property name="url" value="${openalex.url.works}?filter=authorships.author.id:"/>
</bean> |
The mapping between the OpenAlex metadata and DSpace metadata fields is defined in the file:
config/spring/api/openalex-integration.xml |
NOTE: To use the publication claim feature with OpenAlex, the Researcher Profile (Person Entity) must include a dc.identifier.openalex metadata (e.g., A1969205037). It won't work if you set the dc.identifier.openalex with the full url (e.g., `https://openalex.org/A1969205037`).
One way to automatically set this dc.identifier.openalex field is by importing the author from OpenAlex using live import and then create the researcher profile.
The selected author contains the openalex id that will be mapped to `dc.identifier.openalex`.
The SOLR suggestion core has the following structure
<fields>
<field name="source" type="string" indexed="true" stored="true" omitNorms="true" />
<field name="suggestion_fullid" type="string" indexed="true" stored="true" omitNorms="true" />
<field name="suggestion_id" type="string" indexed="true" stored="true" omitNorms="true" />
<field name="target_id" type="string" indexed="true" stored="true" omitNorms="true" />
<field name="title" type="string" indexed="true" stored="true" omitNorms="true" />
<field name="date" type="string" indexed="true" stored="true" omitNorms="true" />
<field name="display" type="string" indexed="true" stored="true" omitNorms="true" />
<field name="contributors" type="string" indexed="true" stored="true" omitNorms="true" multiValued="true" />
<field name="abstract" type="string" indexed="true" stored="true" omitNorms="true" />
<field name="category" type="string" indexed="true" stored="true" omitNorms="true" multiValued="true"/>
<field name="external-uri" type="string" indexed="true" stored="true" omitNorms="true" />
<field name="processed" type="boolean" indexed="true" stored="true" omitNorms="true" />
<field name="trust" type="double" indexed="true" stored="true" omitNorms="true" />
<field name="evidences" type="string" indexed="false" stored="true" omitNorms="true" />
</fields>
<uniqueKey>suggestion_id</uniqueKey> |
the source field would allow the reuse of such structure by other sources than openAIRE.
Three endpoints have been designed to expose the result of the processing to the DSpace UI and so to the Repository Managers and single researchers:
/api/integration/suggestionsources to provide access to summary information about the available suggestion from each source (openaire, orcid, etc.)
/api/integration/suggestiontargets to provide access to summary information about the available suggestions for a specific researcher
/api/integration/suggestions to provide access to the detailed suggestions so that they can be reviewed and managed by the repository manager or the researcher to whom they related
The detailed REST contract for such endpoints are available on the 4Science Rest7Contract repository and embedded at the bottom of the page for easy reference.
Log in as the researcher. You should see a suggestions pop-up in MyDSpace.
Click "Review suggestions" to see the list of suggested publications.
Click "Approve & Import" to create a workspace item from a suggestion.
Admins can access all suggestions under Notifications > Publication Claim.
You can filter by suggestion source (e.g., OpenAlex) using the Actions menu.
The resulting UI is accessible for the Repository Manager from the administrative menu. As entry point for the features a “Notifications” menu entry has been added to the DSpace administrative menu, from where the repository manager will be able to manage the suggestions got from the different sources.
A list of local profiles with candidate publications will be shown so that the repository manager can review them directly or support the researcher:
For each candidate the available suggestions are shown, sorted by the evaluated total score (summing up all the processed evidences ). Using the buttom see evidence is possible to get detailed information about the score
The suggested authorship of each article can be confirmed importing the data locally, or rejected. This operation can be performed individually but also simultaneously for all the selected suggestions, speeding up the process. The decision can also be guided by inspecting the matching evidences which are displayed for each suggestion by clicking on 'See evidence'
The suggestions list can be sorted by total score descending or ascending (highlighting the weakest candidates).
This functionality requires to implement a mechanism to uniquely link user accounts with Person profiles. Such mechanism is implemented out-of-box in DSpace-CRIS. Where the link is not implemented, the Repository Manager UI can still be used.
The single researcher is also allowed to directly review his suggestions. Upon login he is informed about the availability of suggestions from one or more providers
and can proceed to review the suggestions list in the same way than the Repository Manager, the notification message is also always available at the top of the mydspace
The backend is responsible to process the repository manager or researcher decisions taken over the received suggestions. The publication to be imported are processed according to the Import from External Sources normal data flow of DSpace 7. Upon import the suggestion document is removed from the SOLR core, in case of rejection the document is updated flagging it as rejected so that it will be not longer proposed to the user.
Three endpoints have been designed to interact with the publication claim service. They are documented in our REST Contract.
/api/integration/suggestionsources to provide access to summary information about the available suggestion from each source (openaire, orcid, etc.)/api/integration/suggestiontargets to provide access to summary information about the available suggestions for a specific researcher/api/integration/suggestions to provide access to the detailed suggestions so that they can be reviewed and managed by the repository manager or the researcher to whom they related