Workflow: Publishing systems

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

Not every manuscript submission system will fulfil every element of this process—many systems may only collect researchers’ iDs and display them in works and metadata. You can also take your integration one step further by recognizing reviewers’ peer review activity on their records.

Introduction

ORCID can streamline the publishing process, improve the management of author and reviewer databases, and enhance the accuracy of name-based article repository searches.

Publishers use ORCID to clearly link authors and reviewers—and all their name variants—with their research work, by embedding ORCID iDs into their publication metadata and displaying them on finished publications. By including validated iDs in your metadata you can free researchers from having to manually update their ORCID records, help speed the communication of research works, and reduce the risk of errors.

Publishers can also take advantage of ORCID’s auto-update feature when they send publication metadata embedded with ORCID iDs to Crossref or DataCite. For more, see Connect below.

Common integration points for publishing systems:

  1. Before you start: system setup
  2. Collect authors' and reviewers' iDs and biographical information
  3. Display iDs within your system, in publication metadata, and in finished publications
  4. Connect published works and review activity to authors'/reviewers' ORCID records
  5. Synchronize ORCID records with your own systems
  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, if you upgrade your system to support new scopes, or if you want to give researchers the ability to revoke or the token or limit its permissions from within your system.
  • Customized interaction messages: We recommend creating at least three:
    • 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’ and reviewers’ iDs and biographical information

Publishers can integrate ORCID into manuscript submission systems to collect authenticated ORCID iDs and to gain permission to read from/write to authors’ and reviewers’ ORCID records, either immediately or in the future.

The author iDs that you collect should be embedded into the work’s metadata enabling them to be used throughout the publishing workflow. This means that, for example, when you submit publication data embedded with authors’ ORCID iDs to Crossref or DataCite, they can automatically update the ORCID record of the associated author(s). You can also use data from the ORCID record such as researchers’ names, education history, and current affiliations to populate profiles in your own system to save your users time and reduce errors.

It is critical that you collect ORCID iDs and obtain permission to read from/write to the authors’ 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 authors and reviewers.

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 author’s personal profile, on the submission form itself, when co-authors confirm their role in a submission, or even in a customized email to a potential author or reviewer. 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

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.

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 and publications, then you need only /read-limited access to an ORCID record. (If you are using the public API, replace this with /authenticate.)

If you are planning to connect authors’ publications and review activity data to their ORCID records, then you should request both /read-limited and /activities/update access.

The below example requests permission to read data visible to trusted parties as well as to write activities to ORCID records on the ORCID sandbox. Replace 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&redirect_uri=[Your landing page]

Obtain access token to get 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. The authorization code expires upon use.

  URL=https://sandbox.orcid.org/oauth/token
  METHOD: POST
  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 information you'll need to access their record:

{"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","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, expiry) 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, and can be used to read public data on ORCID records.

Use the author’s iD and access token to read their ORCID 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:

  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.1/[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.1 for more information on interpreting the ORCID message schema.


Display iDs in your system and in the metadata and text of publications

Publishers can use ORCID to clearly link authors—and all their name variants—with their research work by embedding ORCID iDs into publication metadata and finished publications during the production process. And you can take advantage of ORCID’s auto-update feature when you send publication data embedded with ORCID iDs to Crossref or DataCite, which can then automatically push that information to your authors’ ORCID records.

Including ORCID iDs in metadata and finished publications requires that you have collected validated ORCID iDs from researchers as described above in Collect. The steps to complete the Display process are:

Displaying within your system: Once a researcher has connected their ORCID iD to your system, clearly display their iD within their profile and/or on their submission 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 iconhttps://orcid.org/0000-0001-2345-6789

Displaying in publications

  • Embed ORCID iDs in metadata: Doing this allows you to take advantage of ORCID auto-update using Crossref and DataCite—both services will only send an auto-update request when <orcid authenticated="true">. It also means that the researchers’ ORCID iDs will be searchable in databases that support searching by ORCID iDs, such as PubMed.
     
  • Display iDs in publication text: Display the ORCID iDs of identified authors in the print and hypertext versions of your finished publications, formatted as URLs, per our iD Display Guidelines.

Connect information about the final publication to 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. Document the final publication by adding an entry to the works section of authors’ ORCID records, and acknowledge reviewers’ contributions by adding an entry to the Peer Review section of their ORCID records. You can also submit review activity data to third-party peer review recognition services that can assist in adding that activity to ORCID records.

Using ORCID auto-update to connect works to ORCID records

Including validated ORCID iD for your authors in the metadata you send to Crossref or DataCite metadata deposit means they can benefit from automatic updating of their ORCID records. When Crossref or DataCite mint a new DOI for a publication with an authorized ORCID iD they contact the author to request permission to add it to their ORCID record. If the author grants long-lasting permissions to Crossref or DataCite, their ORCID record will also be automatically updated with any future publication that includes their validated ORCID.

You can help by reminding your authors to authorize Crossref and DataCite to make this updates, which save researchers time and correctly connects them with their works, as well as ensuring that other systems they use are updated based on record data and ultimately increasing trust in digital research.

Using your system to connect works

The steps to complete the Connect process are listed below. Note that these only cover adding published works to researchers’ records; for peer review activity, we recommend that you follow our peer review workflow.

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

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

  • Title
  • Work type
  • Unique work identifier—add as many of these as your system is aware; works are grouped automatically based on identifiers, 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 ORCID Member API. The example below adds a single work item 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 a single work item to add]
  URL: https://api.sandbox.orcid.org/v2.1/[ORCID iD]/work
  Example call: GitHub
  Example XML: 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 returned.

  HTTP/1.1 201 Created [...] 
  Location: https://api.sandbox.orcid.org/v2.1/0000-0001-2345-6789/work/739286

Synchronize your systems’ data with authors’ ORCID records

Updating authors’ profiles within your system to reflect changes in their affiliations or in recognition of other published work helps reduce the reporting burden for your authors and reviewers 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 publishers who also curate databases 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

Send a call to the API to update using the ORCID iD, access token, the updated work, and the work’s put code. 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="[put-code]" [...]  >
    [...] 
    </work:work>
  Example XML: GitHub

Add the updated work to the ORCID record using the HTTP PUT command: The final end point 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.1/[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.1/[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:

  1. 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.
  2. Add a link to the researcher’s author profile within your system: Add a link to your authors’ and reviewers personal profile under the Websites section of their researcher’s ORCID record. See more on adding personal information such as websites at the Research information and profile systems workflow.