Workflow: Vendor systems

Vendors can offer clients ready-built ORCID integrations, providing them the full benefits of their ORCID membership without having to build their own integration. This workflows outlines overall guidelines for building an ORCID integration as a vendor offering software to customers. It is not industry specific.

For specific technical workflows for systems in various sectors, refer to our thematic workflows.


Contents


Vendor requirements

When building your ORCID integration you will need to ensure that your integration allows your customers to meet the elements of Collect and Connect -- both technically and in terms of good user communications about what the system does and why.

We recommend that your system at least meet the first two elements of Collect & Connect:

  • Collect authenticated ORCID iDs using the OAuth process for individuals to ensure they’re correctly associated with their affiliations and contributions.
  • Display the authenticated iDs in your system as per our display guidelines, to signal to researchers that your system is plumbed to support their use of ORCID.
  • Connect users’ data from your system to their ORCID records, enabling your customers to update their researchers records where required.
  • Synchronize your system’s data with the ORCID Registry via a bidirectional information flow.

System setup

All systems that connect with ORCID need to store the ORCID iDs and access tokens collected, and you can also store information read from the ORCID record.

  • Your system must be able to accept and store ORCID iDs together with the user’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 the full token response together with the user's information, including:
    • Persistent access tokens
    • Refresh tokens
    • Requested scopes
    • Scope expiry
  • Customized interaction messages: We recommend creating or designating at least three pages where messages can be displayed:
    • Start connection: Where users initiate the connection process.
    • Connection-success: The page the user will be 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 -- as well as the option to unlink the ORCID iD.
    • Connection-failure: The page the user will be redirected to after denying authorization to your system. It should give the reasons you requested permission from the researcher and offer the opportunity to again grant permission.
  • If your system will write data to ORCID records:
    • Your system must be able to save a put code for each item added toan ORCID record. Put codes are unique identifiers for items within the ORCID Registry (read more).
    • Your system must be able to send data in XML or JSON formatted in the ORCID message schema.
  • 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.
  • If your clients can use either public or member API, then your system should allow clients to select with API they are using.
  • Your system must offer a way for your clients to export the stored ORCID iDs and token exchange data (access tokens, refresh tokens, scopes, scope expiry). If your system also writes data, then it must also include the relevant put codes with data exports. 

ORCID API credentials

ORCID requires that the organization requesting the data, i.e. your client, use their own ORCID API credentials. This clearly indicates who is requesting access to update ORCID records and is required by ORCID’s membership agreement. The organization must obtain the ORCID API credentials on their own. If you are assisting the organization in managing the system and their API credentials require changes such as updating the redirect URIs, the organization must submit the request for changes. 

When talking to your clients about what they need to do to obtain, set up, and test credentials to access the ORCID APIs, please:

  • Clearly explain which API is required to use your system:
    • Public API: authenticate and read public data only
    • Member API: read limited access data and update records
    • Premium Member API: register webhook notifications
  • Provide clear direction on how to complete the application forms for ORCID credentials, particularly noting:
    • Where to fill out the application
    • The full list of redirect URIs
    • System website URL
    • A suggested description (the API client name should include the organization which owns the credentials, not just your system name)
    • Populating the note to ORCID staff that they are using your system
  • Allow your clients to enter their ORCID credentials (client ID and secret) within your system -- they should not be sending this data to you.
  • Provide an option for testing on the ORCID sandbox, where clients can enter sandbox credentials and make test connections to the sandbox system
  • Consider providing an option to test that credentials were entered correctly by requesting a two-legged OAuth /read-public access token

Communicating about ORCID to your users

Researchers will be connecting to ORCID from your interface, so we strongly encourage you to make sure that they understand how and why, including providing information about how your system interacts with ORCID. This will help you and your clients meet the communications component of each element of the Collect & Connect program. Check our web presentation guidelines for suggested language and graphics.

This includes:

  • Providing a hyperlinked ORCID-branded button for collecting authenticated ORCID iDs: 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
  • Displaying ORCID iDs in your system formatted per our our iD Display Guidelines

    ORCID iD icon  orcid.org/0000-0001-2345-6789

  • Clearly communicating your integration and its benefits to users: Why your system collects ORCID iDs, why it requests permission to read/update ORCID records (where relevant), and how it benefits your users.
  • Providing a link to learn more about ORCID.
  • Allowing clients to provide links to local documentation or to customize the information provided about how they are using ORCID.

Let us know about your system

As part of our service to ORCID members, we’re happy to help you test your system and let the ORCID community know about it on our vendor systems pages.

Once you’re ready to release your system, contact us to share:

  1. Your system’s name and developer name
  2. A brief description of its functionality and how it connects to the ORCID Registry
  3. Links to pages, presentations, and demo systems to which we can refer organizations so they can learn more about your system
  4. Technical and administrative contacts with whom we liaise to share information about updates to the API so you can provide your clients with the latest functionality

We are also always interested to learn more about non-member integrations, so please keep us posted!