Workflow: Repository systems

This workflow sets out a process in which a typical repository system may integrate with the ORCID API. It gives a walkthrough of the process of receiving authenticated ORCID iDs from researchers, retrieving data from ORCID records, adding research works to ORCID records, and updating information you have previously added to ORCID records. It is based on version 2.0 of the ORCID message schema.

Not every integration will fulfil every element of this process—many may only collect researchers’ iDs and display them within their systems. You can also take your integration one step further by adding biographical information, affiliations, funding information, and peer review activity for your organization.

Introduction

ORCID can be used in repository systems to clearly link authors—and all their name variants—with their research work, improving search and retrieval to support networking and collaboration. Using the ORCID API, repository systems can exchange data with the ORCID Registry to populate local author profiles. They can also update ORCID records with publication information each time a repository deposit is made.

Repository systems integrations with ORCID add visibility to repository content and their authors, facilitate collaboration and networking, and help organizations with institutional reporting systems and national assessment programs.

Common integration points for repository systems:

  1. Before you start: system setup
  2. Collect authors’ iDs and biographical information
  3. Display iDs within your repository system
  4. Connect research output information to researchers’ ORCID records
  5. Synchronize your researchers’ ORCID records with your system
  6. Take your system one step further

Before you start: System setup

Please be sure to check that your system meets the requirements below. Additional setup requirements for more advanced integrations can be found in the relevant section(s).

  • Your system must be able to accept and store ORCID iDs together with the researcher’s information.
  • Your system must be able to capture a six-digit authorization code and exchange it for an access token immediately.
  • Your system must also be able to accept and store persistent access tokens together with the researcher’s information. We strongly recommend that you store all of the token response, including refresh tokens, scopes, and token expiry, as these can be useful if access tokens are lost, or if you upgrade your system to support new scopes.
  • Customized interaction messages: We recommend creating at least three messages:
    • Start message: Where researchers initiate the connection process
    • Connection-success message: This message should display on the page the researcher is redirected to after successfully authorizing the connection with your system. It should display their ORCID iD and can also display a thank you or acknowledgement message.
    • Connection-failure message: This message should display on the page the researcher is redirected to after denying authorization to your system. It should give the reasons you requested permission from the researcher and again offer the opportunity to grant permission.
  • Log interactions: Your system should record both calls made to the ORCID API and responses received; this is necessary so our team can help if a problem develops later.

Collect authors’ iDs and biographical information

Repository systems can integrate ORCID to collect authenticated ORCID iDs and to gain permission to read from/write to researchers’ ORCID records, either immediately or in the future. The iDs that you collect can be stored and display within your system and shared with other systems in your organization.

It is critical that you collect ORCID iDs and obtain permission to read and update ORCID records by requiring users to sign into ORCID from within your system and then retrieving their data from the ORCID Registry using the ORCID API. It is also essential to provide information within your system about why you are collecting ORCID iDs and why this is beneficial to your users.

The steps to complete the Collect process are:

Provide a hyperlinked ORCID-branded button for collecting authenticated ORCID iDs: This can be at sign-in, within the researcher’s personal profile, at the time of deposit to the repository, or even in a customized email to the researcher. Using the ORCID button consistently helps ensure that researchers associate it with being asked to securely provide their iD, which in turn builds trust in ORCID as a reliable identifier.


Example button graphics and code

Configure the button’s link to request permissions to access the researcher’s ORCID record via the API: You'll be getting the ORCID iD by obtaining an access token through three-legged OAuth authorization, and this starts with a link customized with your API credentials and scopes that represent the access permissions you're requesting. If you are only planning to collect and display ORCID iDs within your system then you need only /read-limited access to an ORCID record. (If you are using the public API, replace this with /authenticate.)

Customize the user experience! You can specify a display language, pre-fill the researcher’s name, and include a state parameter which will be returned with the user to your system.

If you are planning to connect to researchers’ ORCID records then you should request both /read-limited and /activities/update access. If you plan to add biographical information, such as a link to their profile page within your system to the Websites or External identifiers section of the ORCID record, you should request  /person/update.

The below example requests permission to read limited-access data as well as to add and update biographical information and information about research activities to ORCID records. Replace the bracketed data with your client information and paste directly into your web browser to generate an access token for testing (be sure to remove the brackets!).

https://sandbox.orcid.org/oauth/authorize?client_id=[Your client ID]&response_type=code&scope=/read-limited%20/activities/update%20/person/update&redirect_uri=[Your landing page]

Obtain an access token to get the researcher’s ORCID iD: The researcher signs into their ORCID account and simultaneously authorizes the connection. They are sent back to your landing page—the Redirect URI specified in the OAuth link. Appended to the end of that link will be a six-digit authorization code:

https://[Your landing page]?code=gtYn37

At this point, your system’s user interface should display a helpful message to the researcher, e.g. “Thanks for connecting your ORCID iD!” or simply display their iD in full—see Display below.

In the system backend, immediately exchange the authorization code—within 10 minutes at most. The authorization code expires upon use.

  URL=https://sandbox.orcid.org/oauth/token
  HEADER: Accept: application/json
  DATA: 
    client_id=[Your client ID]
    client_secret=[Your client secret]
    grant_type=authorization_code
    code=[Six-digit code]
    redirect_uri=[Your landing page]

  Example call: 3-legged OAuth

ORCID will then return the researcher’s validated ORCID iD and an access token:

{"access_token":"c47026d9-90bf-4480-a259-a953bc103495","token_type":"bearer",
"refresh_token":"2d76d8d0-6fd6-426b-a017-61e0ceda0ad2","expires_in":631138517,
"scope":"/read-limited /activities/update /person/update","orcid":"0000-0001-2345-6789","name":"Sofia Garcia"}

If the user denies your system access: ORCID returns the researcher to the specified landing page and attaches an error message:

https://[your landing page]?error=access_denied&error_description=User%20denied%20access 

Your system should read this and automatically direct the researcher to the connection-denied landing page. We strong recommend that you use this opportunity to explain more fully to the researcher why you are collecting ORCID iDs and requesting permission to access their record, and to prompt them again to sign in and authorize the connection to your system.

Store the token exchange response (ORCID iD, access token, refresh token, scope, exipriy) in your system in a safe and secure manner. The ORCID iD and access token will be required to perform any action to their ORCID record: read, write, update. If you are only requesting /authenticate access, access tokens can be stored to indicate that the iD has been authenticated.

Use the researcher’s iD and access token to read their record and populate their profile in your system: Save researchers time by allowing them to quickly and easily transfer data from their ORCID records to your system by making a quick call to their record; the below example calls the member API on the sandbox server:

  Method: GET
  Accept: application/vnd.orcid+xml or application/vnd.orcid+json
  Authorization type: Bearer
  Access token: [Stored access token]
  URL:  https://api.sandbox.orcid.org/v2.0/[ORCID iD]/record
  Example call: GitHub 

Once you have obtained the record data, you can use it to update your system. Our recommended process is by searching the external identifiers for the relevant item, e.g. works, and then querying the identifier source to obtain robust metadata for each item. Alternatively, you can use the put code to read all of the data that was added to the ORCID record for that specific item. See Read data on an ORCID record for more information on reading the ORCID record, and Read ORCID XML 2.0 for more information on interpreting the ORCID message schema.


Display iDs of researchers within your system

Repository systems can use ORCID to clearly signal to your researchers and affiliates that your system supports ORCID. Displaying ORCID iDs requires that you have collected validated ORCID iDs from researchers as described above in Collect.

Once a researcher has connected their ORCID iD to your system, clearly display their iD on their profile within your system so that they know that they have successfully connected and asserted their identity. Format the iD as a hyperlinked URI and include the green iD icon, per our iD Display Guidelines.

ORCID iD iconorcid.org/0000-0001-2345-6789

You may also wish to display researchers’ iDs in other systems that are connected to your repository system—see Take your system one step further for more.


Connect research output information to researchers’ ORCID records

You can help make life easier for your authors and reviewers by connecting validated information about publications to their ORCID records—and you will also be helping to build trust in scholarly communications. Repositories can add research activity information, including affiliations, research works, funding, and peer review activity, to researchers’ records.

Adding information to ORCID records requires that you have collected both ORCID iDs and update permissions as described in Collect above.

System setup:

  • Your system must be able to save a put code, a unique identifier for items within the ORCID Registry, for each work item added to the ORCID Registry. Every item that is added to the activities section of the ORCID record is returned a put code—even if you add multiple items at once. If you ever need to read, edit, or delete the item you added, you will use the put code.
  • Your system must be able to send data in XML or JSON formatted in the ORCID message schema.

The steps to complete the Connect progress for by adding works to researchers’ ORCID records are listed below. For research organizations, we also highly recommend that you assert researchers’ affiliation with your institution; read more about how to do this at our research information and profile systems workflow.

Adding work(s) to an ORCID record

Format the work in ORCID message schema: The work must be created in XML or JSON in the ORCID schema. Sample XML for for creating a single work item or multiple work items can be found in our GitHub repository.

At the minimum, the work must include the following elements:  

  • Work title
  • Work type
  • Unique work identifier—add as many of these as your system is aware; it aids in grouping on ORCID records, so researchers don’t have to group works manually
    • Work identifier type
    • Value of the identifier
    • Identifier URL (optional)
    • Relationship: self/part of
      This is to indicate the relationship of the work to the identifier. For example, if the work is a book chapter, and the identifier is the ISBN for the book, then the relationship would be “part of”; if the identifier is the DOI for the book chapter itself, then the relationship would be “self”.

We also suggest that you include all other known metadata available for a work , in particular:

  • Publication date, which aids display sorting
  • Journal title (where relevant)
  • Citation (we recommend BibTeX), which can be used to record any additional metadata not captured by the schema, e.g. co-authors, page numbers

Add the work(s) to the relevant author’s ORCID record: Use the ORCID iD and access token you have stored for the author to add the work(s) using an HTTP POST call to the member API. The example below adds multiple work items to a record on the sandbox server.

  Method: POST
  Content-type: application/vnd.orcid+xml or application/vnd.orcid+json
  Authorization type: Bearer
  Access Token: [Stored access token]
  Data: [Link to file or text of multiple work items to add]
  URL: https://api.sandbox.orcid.org/v2.0/[ORCID iD]/works
  Example call: GitHub

Save the returned put code(s) in your system in association with the work(s). For a single work, the API will return a 201 Created message to indicate that the item posted correctly. For multiple works, the API will return a 200 OK message to indicate that the items posted correctly. Check our troubleshooting page if a different message is sent.

  HTTP/1.1 200 OK [...]
  <?xml version="1.0"  encoding="UTF-8" standalone="yes"?>
  <ns22:bulk [...]>
    <work:work put-code="741242"  visibility="public">
    [...]
    </work:work>
    <work:work put-code="741243"  visibility="public">
    [...]
    </work:work>
  </ns22:bulk>

Synchronize your researchers’ ORCID records with your system

Updating your researchers’ profiles within your system to reflect changes in their affiliations or in recognition of other published work helps reduce their reporting burden and improves data quality.

Synchronize data between your system and ORCID by automatically updating ORCID records and regularly querying the researcher’s ORCID records for any new changes. This requires persistent (long-term) update tokens. (Premium members can register Webhooks to receive pings from ORCID when monitored records are updated.)

Be sure to check the last modified date to find the latest information.

  <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  <record:record  [...]>
  <history:history>
    <common:last-modified-date>2016-11-29T11:29:23.584Z
    </common:last-modified-date>
  </history:history>
  [...]
  Example XML: GitHub

Search & link wizards: Large repositories which are open and accessible to researchers can create Search & Link wizards to benefit the entire community. These are links from the ORCID Registry user interface which first request researchers’ update permission and then redirect to your system. They require considerable testing between the provider and ORCID. Get in contact with the ORCID Community Team if you are interested in creating a Search & Link wizard.

Updating a work on an ORCID record

Works added by your system may in future need to be amended or deleted from researchers’ records. Works should be updated as a best practice, rather than deleted and reposted, but there are some cases where deletion is preferable:

Update

Delete

Correcting data, e.g. typos, formatting errors

Work incorrectly attributed to researcher

Adding new data, e.g. identifiers

Peer review or funding item incorrectly added as work

Use the ORCID iD, access token, the work formatted in the ORCID message schema, and the work’s put code to update the work. Only one work can be updated at a time.

Format the updated work in ORCID message schema with the changed information and include the stored put code.

  <?xml  version="1.0" encoding="UTF-8"?>
    <work:work put-code="741243" [...]  >
    [...] 
    </work:work>
  Example XML: GitHub

Add the updated work to the ORCID record: The final endpoint must be the corresponding put code of the work to be updated.

  Method: PUT
  Content-type: application/vnd.orcid+xml or application/vnd.orcid+json
  Authorization type: Bearer
  Access token: [Stored access token]
  Data: [Link to file or text of work to update]
  URL: https://api.sandbox.orcid.org/v2.0/[ORCID iD]/work/[put code]
  Example call: GitHub 

The API will return a 200 OK message to indicate that the item updated correctly. Check our troubleshooting page if a different message is sent.

Deleting a work on an ORCID record

Use the ORCID iD, access token, and the work’s put code to delete the work via an HTTP DELETE command. Only one publication can be deleted at a time.

  Method: DELETE
  Authorization type: Bearer
  Access token: [Stored access token]
  URL: https://api.sandbox.orcid.org/v2.0/[ORCID iD]/work/[put code]
  Example call: GitHub 

The API will return a 204 NO CONTENT message to indicate that the item updated correctly. Check our troubleshooting page if a different message is sent.


Take your system one step further

Besides collecting researchers’ iDs and connecting them with their publications, your system can also:

  • Assert a researcher's affiliation with your institution: We strongly encourage research institutions to assert a researcher's affiliation—you're the only party you can do this with authority. See more on adding affiliations at the research information and profile systems workflow. 
  • Add a link to the researcher’s author profile within your system: You can add a link to your researcher’s personal profile under the Websites section of the researcher’s ORCID record—this requires additionally requesting the /person/update scope. See more on adding personal information such as websites at the research information and profile systems workflow.
  • Add researchers’ funding activity to their ORCID record: Many research organizations collect and verify information about researchers’ funding information to aid the reporting process. You can use the same access tokens used to add works to add funding information—see more at funding submission systems workflow.
  • Recognize researchers’ peer review activity: Connect information about your peer reviewers’ activities to their ORCID record with as much or little detail as appropriate—see more at the peer review workflow.