Members setting up vendor systems with the ORCID API

Posted:   Updated: Categories Technical

Many of the UK consortium member institutions use vendor systems that are ORCID-enabled. This means that the institution simply needs to obtain institution-specific credentials from ORCID for the member API which can then be set up in the vendor system. This blog post provides a convenient walk-through of the ORCID pages and information that are most relevant to those using vendor systems, in order to get credentials and set them up in the CRIS (or repository) system to connect to the ORCID member API. It draws on existing ORCID documentation to deliver a dedicated path to be followed by those that meet this specific use case (see: who can use these instructions?). It does not attempt to address all the information related to vendors that are ORCID-enabled and their system set-up. A list of the systems that are ORCID-enabled and have an approved integration is provided by ORCID. Further vendor-specific information should be obtained from system suppliers.

Who can use these instructions?

These instructions assume that you are already a member organisation of ORCID (e.g. by joining the UK ORCID consortium through Jisc) and that you are using a system that is considered integration-ready. The list of systems that are considered ORCID-integration-ready can be found in the link above. The CRIS systems on that list include: PURE from Elsevier, Symplectic Elements and Converis (Clarivate Analytics, previously Thomson Reuters).

What are member credentials and what does integration-ready mean?

All members of the UK JISC ORCID consortium acquire premium level membership and can access the ORCID member API if they have an appropriate integration. Client applications (including vendor integrations) that make calls to the ORCID API need to present credentials as a means of proving identity and right to access the API at the correct level. The credentials consist of a client ID and a client secret. Institutions need to apply to ORCID for their credentials to be used with their vendor system, by filling in a client application form. In order to be issued with member API production credentials, applications are required to meet best practices as set out in the member credential checklist. Vendor systems listed in the ORCID-enabled list have already been considered by ORCID to meet the best practices and are therefore integration-ready. This means that an institution using one of these systems can move directly to applying for member credentials.

Applying for production member credentials.

The form to register a client application Production Trusted Party should be filled in to request member credentials from ORCID. Assistance with filling in this form is available from ORCID’s knowledgebase – see the ‘Filling in the client application form’ section. As mentioned previously, when using an integration-ready vendor system from ORCID’s list of ORCID-enabled systems, there is no need to consult the member credential checklist (although it can be helpful to understand that content) and the demo step can be skipped, so you can proceed to filling in the form.

Some helpful tips

  • The process is not fully automated, therefore there may be a small delay (hours to a couple of days) between filling in the form and the credentials being sent
  • For the first time that you set up the vendor system, and if you have not registered for credentials for this vendor system before, select No for Update existing credentials?
  • The application credentials consist of a Client ID (consumer KEY) and Client Secret (consumer SECRET). Your application will use these credentials as it interacts with the ORCID API. They look like this: client ID: APP-NPXKK6HFN6TJ4YYI client SECRET: 060c36f2-cce2-4f74-bde0-a17d8bb30a97
  • You will need to provide a second email address or a mobile phone number or another way to be contacted, since the client secret is obtained separately to the client ID, and will need a PIN sent by ORCID to access it
  • To use your client iD you’ll also need your client secret, which we will be sent separately in order to ensure your credentials are kept secure. You will receive a message with a link to your full credentials, including your client secret, which is protected by a PIN. ORCID send the PIN separately to the alternate contact you provide.
  • Make sure you mention that you are using a vendor system, name the system and the version, when completing the notes for staff. This will be useful information if you require further assistance and it helps future planning and communications, since vendor system versions and their capabilities are taken into account when considering moving between ORCID API versions, deprecating features that older versions may have relied on, etc.
  • You will need at least one redirect URL. For vendor systems discuss these URLs with your system suppliers. More on redirect URLs
  • Do use the ORCID knowledgebase article for assistance with filling in the fields.
  • Keep your credentials safe. They are specific to your application and ensure that only your application gains access based on your membership status and the permissions granted by researchers. Please do not share the client ID and secret, for example do not email them to the UK Jisc support desk

Updating the application information

If you need to update the application that uses the credentials in the future, for example change the redirect URLs or update the text displayed to your users such as the name of your application, use the same form and select Yes for Update existing credentials?

A note on using the Sandbox.

A separate blog post is planned, which will go into more detail regarding the ORCID Sandbox, how to access it, and differences from the production API. In a nutshell, the Sandbox provides a way to test API calls to the ORCID registry without affecting any actual live records (which are only found in the Production Registry). The sandbox only contains test data. If you have a test or development version of your vendor system, and you would like to do some testing using that system, then you should connect it to the ORCID sandbox for the purposes of testing.
You will need to request separate Sandbox credentials to set up your development system, using the form for registering a client application with the sandbox. You may also need to check with your vendor as you may need different redirect URLs.
Once you have done your testing with the development instance of your vendor system against the ORCID Sandbox, then you can move to using the live vendor system with the ORCID production registry by following the steps at the start of this blog post.

Letting ORCID know when you go live.

Institutions should advise ORCID when they officially launch the integration. ORCID can assist with publicity if required. ORCID will add the integration to their list of live integrations including information about your Collect & Connect status, and include it in their monthly member newsletter. They can also share news about your integration on Facebook and Twitter and would be happy to talk to you about other opportunities to publicize your integration.

Need help?

The first port of call for help for members of the UK Jisc consortium should be the Jisc UK ORCID support desk which can be contacted at help@jisc.ac.uk. The helpdesk will liaise with ORCID support for assistance that only ORCID can provide. Vendors are the best source of information on vendor-specific information.
Updated 22/05/2018 with new email address.

Further Information

https://members.orcid.org/api
https://members.orcid.org/api/introduction-orcid-member-api
http://orcid.org/organizations/integrators
http://orcid.org/organizations/integrators/API
http://orcid.org/about/membership
http://jisc.ac.uk/orcid