pt.ptcris

Class PTCRISync

java.lang.Object

pt.ptcris.PTCRISync

public final class PTCRISync
extends java.lang.Object

An implementation of the PTCRISync synchronization service based on the version 5.0 of the specification. This service allows CRIS services to maintain their repositories synchronized with ORCID. This requires the CRIS service to have access to the ORCID Member API.

The service has two main functionalities: to keep a set of local productions updated in an ORCID user profile through an export procedure, and import productions not known locally from the ORCID profile, either through the import for completely new productions or through the import for new information for already known productions. Works must meet certain quality criteria to be imported (the set of invalid works can be retrieved as well through importInvalid(ORCIDClient, List, ProgressHandler).

The implementation of the service assumes that the local CRIS communicates the local productions following the established ORCID schema, according to the Member API 2.0rc2. This uniforms the API and simplifies the synchronization process. The current version focuses on synchronizing research productions, which must be encoded as ORCID works.

The communication with ORCID is encapsulated in an ORCID client that contains information regarding the CRIS Member API and the ORCID profile that is to be managed. An helper provides utility methods for the synchronization of works.

The procedures do not currently consider the contributors (authors) of works when assessing the quality criteria nor when assessing whether works are up-to-date, as this information is not available in ORCID summaries and would require additional calls to the ORCID API.

See Also:

https://ptcris.pt/hub-ptcris/

Constructor Summary

Constructors

Constructor and Description
PTCRISync()

Method Summary

Modifier and Type	Method and Description
static java.util.Map<java.math.BigInteger,PTCRISyncResult>	export(ORCIDClient client, java.util.List<org.um.dsi.gavea.orcid.model.work.Work> localWorks, ProgressHandler handler) A version of the export procedure that tests whether the meta-data is up-to-date prior to updating a work in ORCID.
static java.util.Map<java.math.BigInteger,PTCRISyncResult>	exportForce(ORCIDClient client, java.util.List<org.um.dsi.gavea.orcid.model.work.Work> localWorks, ProgressHandler handler) A version of the export procedure that forces the update of the CRIS sourced works at ORCID, even if they are already up-to-date.
static java.lang.Integer	importCounter(ORCIDClient client, java.util.List<org.um.dsi.gavea.orcid.model.work.Work> localWorks, ProgressHandler handler) Counts new valid works in an ORCID profile given a set of known local CRIS productions, following the criteria of importWorks(ORCIDClient, List, ProgressHandler).
static java.util.Map<org.um.dsi.gavea.orcid.model.work.Work,java.util.Set<java.lang.String>>	importInvalid(ORCIDClient client, java.util.List<org.um.dsi.gavea.orcid.model.work.Work> localWorks, ProgressHandler handler) Discovers new invalid works (that do not pass the quality criteria) in an ORCID profile given a set of known local CRIS productions, as well as the causes for invalidity (defined at ORCIDHelper).
static java.util.List<org.um.dsi.gavea.orcid.model.work.Work>	importUpdates(ORCIDClient client, java.util.List<org.um.dsi.gavea.orcid.model.work.Work> localWorks, ProgressHandler handler) Discovers updates to existing local CRIS productions in an ORCID profile.
static java.util.List<org.um.dsi.gavea.orcid.model.work.Work>	importWorks(ORCIDClient client, java.util.List<org.um.dsi.gavea.orcid.model.work.Work> localWorks, ProgressHandler handler) Discovers new valid works in an ORCID profile given a set of known local CRIS productions.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PTCRISync

public PTCRISync()

Method Detail

export

public static java.util.Map<java.math.BigInteger,PTCRISyncResult> export(ORCIDClient client,
                                                                         java.util.List<org.um.dsi.gavea.orcid.model.work.Work> localWorks,
                                                                         ProgressHandler handler)
                                                                  throws org.um.dsi.gavea.orcid.client.exception.OrcidClientException,
                                                                         java.lang.NullPointerException

A version of the export procedure that tests whether the meta-data is up-to-date prior to updating a work in ORCID.

A work is assumed to be up-to-date if the external identifiers, title, type and publication year are the same (see ORCIDHelper.isUpToDate(Work, WorkSummary)).

Parameters:

client - the ORCID client defining the CRIS Member API and user the profile to be managed

localWorks - the list of local productions to be exported that should be kept synchronized in the ORCID user profile

handler - the progress handler responsible for receiving progress updates

Returns:

the result of the synchronization of each of the provided local works.

Throws:

org.um.dsi.gavea.orcid.client.exception.OrcidClientException - if the communication with ORCID fails when getting the activities summary

java.lang.NullPointerException - if any of the arguments is null

See Also:

exportBase(ORCIDClient, List, ProgressHandler, boolean)

exportForce

public static java.util.Map<java.math.BigInteger,PTCRISyncResult> exportForce(ORCIDClient client,
                                                                              java.util.List<org.um.dsi.gavea.orcid.model.work.Work> localWorks,
                                                                              ProgressHandler handler)
                                                                       throws org.um.dsi.gavea.orcid.client.exception.OrcidClientException,
                                                                              java.lang.NullPointerException

A version of the export procedure that forces the update of the CRIS sourced works at ORCID, even if they are already up-to-date.

The caller of this method should guarantee that the input local works have been effectively updated, otherwise there will be unnecessary calls to the ORCID API.

Parameters:

client - the ORCID client defining the CRIS Member API and user the profile to be managed

localWorks - the list of local productions to be exported that should be kept synchronized in the ORCID user profile

handler - the progress handler responsible for receiving progress updates

Returns:

the result of the synchronization of each of the provided local works.

Throws:

org.um.dsi.gavea.orcid.client.exception.OrcidClientException - if the communication with ORCID fails when getting the activities summary

java.lang.NullPointerException - if any of the arguments is null

See Also:

exportBase(ORCIDClient, List, ProgressHandler, boolean)

importWorks

public static java.util.List<org.um.dsi.gavea.orcid.model.work.Work> importWorks(ORCIDClient client,
                                                                                 java.util.List<org.um.dsi.gavea.orcid.model.work.Work> localWorks,
                                                                                 ProgressHandler handler)
                                                                          throws org.um.dsi.gavea.orcid.client.exception.OrcidClientException,
                                                                                 java.lang.InterruptedException,
                                                                                 java.lang.NullPointerException

Discovers new valid works in an ORCID profile given a set of known local CRIS productions. Creates creation notifications for each work group at ORCID (merged into as a single work by the helper) without matching local productions (i.e., those without shared external identifiers). To import updates for works with shared external identifiers importUpdates(ORCIDClient, List, ProgressHandler) should be used instead.

Currently, these creation notifications simply take the shape of ORCID works themselves (representing a merged work group). The group merging selects the meta-data of the preferred work and the external identifiers of the whole group (see ORCIDHelper.groupToWork(WorkGroup)). The selection of the meta-data from a group could be changed without affecting the correction of the procedure.

Since the put-code attribute is used as a local key of each work, it is null for these creation notifications (and not the put-code of the remote ORCID works that gave origin to it). Since only the external identifiers of the local productions are used to search for matches, the remainder meta-data of the input local works could be left null.

ORCID works without minimal quality are ignored by this procedure. Currently, the quality criteria forces the existence of external identifiers, the title, publication year and publication type (see ORCIDHelper.testMinimalQuality(Work)). Works that do not match the criteria can be imported with importInvalid(ORCIDClient, List, ProgressHandler). Note that currently group merging simply collects the meta-data (other than the external identifiers) from the preferred work, which is used in the quality assessment.

This procedure performs a GET call to the API to obtain the summaries and an additional GET call for each work identified as valid. The procedure only fails if the initial GET fails. Asynchronous workers are used for getting the full works.

Parameters:

client - the ORCID client defining the CRIS Member API and user the profile to be managed

localWorks - the full list of local productions

handler - the progress handler responsible for receiving progress updates

Returns:

the list of new valid works found in the ORCID profile

Throws:

org.um.dsi.gavea.orcid.client.exception.OrcidClientException - if the communication with ORCID fails when getting the activities summary

java.lang.InterruptedException - if the asynchronous GET process is interrupted

java.lang.NullPointerException - if any of the arguments is null

importCounter

public static java.lang.Integer importCounter(ORCIDClient client,
                                              java.util.List<org.um.dsi.gavea.orcid.model.work.Work> localWorks,
                                              ProgressHandler handler)
                                       throws org.um.dsi.gavea.orcid.client.exception.OrcidClientException,
                                              java.lang.NullPointerException

Counts new valid works in an ORCID profile given a set of known local CRIS productions, following the criteria of importWorks(ORCIDClient, List, ProgressHandler).

This procedure simply performs a GET call to the API to obtain the summaries, since the remainder meta-data is irrelevant, rendering it more efficient than importWorks(ORCIDClient, List, ProgressHandler).

Parameters:

client - the ORCID client defining the CRIS Member API and user the profile to be managed

localWorks - the full list of local productions

handler - the progress handler responsible for receiving progress updates

Returns:

the number of new valid works found in the ORCID profile

Throws:

org.um.dsi.gavea.orcid.client.exception.OrcidClientException - if the communication with ORCID fails when getting the activities summary

java.lang.NullPointerException - if any of the arguments is null

See Also:

importWorks(ORCIDClient, List, ProgressHandler)

importInvalid

public static java.util.Map<org.um.dsi.gavea.orcid.model.work.Work,java.util.Set<java.lang.String>> importInvalid(ORCIDClient client,
                                                                                                                  java.util.List<org.um.dsi.gavea.orcid.model.work.Work> localWorks,
                                                                                                                  ProgressHandler handler)
                                                                                                           throws org.um.dsi.gavea.orcid.client.exception.OrcidClientException,
                                                                                                                  java.lang.InterruptedException,
                                                                                                                  java.lang.NullPointerException

Discovers new invalid works (that do not pass the quality criteria) in an ORCID profile given a set of known local CRIS productions, as well as the causes for invalidity (defined at ORCIDHelper). Other than the criteria, the behavior is similar to that of importWorks(ORCIDClient, List, ProgressHandler). Note that currently group merging simply collects the meta-data (other than the external identifiers) from the preferred work, which is used in the quality assessment.

This procedure performs a GET call to the API to obtain the summaries and an additional GET call for each work identified as valid. The procedure only fails if the initial GET fails. Asynchronous workers are used for getting the full works.

Parameters:

client - the ORCID client defining the CRIS Member API and user the profile to be managed

localWorks - the full list of local productions

handler - the progress handler responsible for receiving progress updates

Returns:

the list of new invalid works found in the ORCID profile, as well as the reasons for invalidity

Throws:

org.um.dsi.gavea.orcid.client.exception.OrcidClientException - if the communication with ORCID fails when getting the activities summary

java.lang.InterruptedException - if the asynchronous GET process is interrupted

java.lang.NullPointerException - if any of the arguments is null

See Also:

importWorks(ORCIDClient, List, ProgressHandler)

importUpdates

public static java.util.List<org.um.dsi.gavea.orcid.model.work.Work> importUpdates(ORCIDClient client,
                                                                                   java.util.List<org.um.dsi.gavea.orcid.model.work.Work> localWorks,
                                                                                   ProgressHandler handler)
                                                                            throws org.um.dsi.gavea.orcid.client.exception.OrcidClientException

Discovers updates to existing local CRIS productions in an ORCID profile. For each work group at ORCID (merged into as a single work by the helper), finds matching local productions (i.e., those with shared external identifiers) and creates update notifications if not already up to date. To import works without shared external identifiers, importWorks(ORCIDClient, List, ProgressHandler) should be used instead.

Currently, these update notifications simply take the shape of ORCID works themselves (representing a matching work group). These works contain only the meta-data that needs to be updated locally. Currently, only the introduction of newly found external identifiers is considered (i.e., those that were already present in the local productions that is being updated are removed from the returned updates). Thus, the remainder fields are returned null.

The local productions are tested to be up-to-date by simply checking whether they contain every external identifiers in the ORCID group (see ORCIDHelper.updateWork(BigInteger, Work)). Thus the remainder meta-data of the local productions can be currently left null.

The put-code attribute is used as a local key of each CRIS productions. This means that the returned works representing the updates have the put-code of the local work that is to be updated (and not the put-code of the ORCID works that gave origin to it).

This procedure simply performs a GET call to the API to obtain the summaries, since the remainder meta-data is irrelevant.

Parameters:

client - the ORCID client defining the CRIS Member API and user the profile to be managed

localWorks - the list of local productions for which we wish to discover updates, i.e., keep synchronized with ORCID

handler - the progress handler responsible for receiving progress updates

Returns:

the list of updates found in the ORCID profile, pointing to the respective local work

Throws:

org.um.dsi.gavea.orcid.client.exception.OrcidClientException - if the communication with ORCID fails when getting the activities summary

java.lang.NullPointerException - if any of the arguments is null