Overview

VIVO contains code that will converse with the ORCID registry through its API. When this conversation is enabled, a VIVO user can authoritatively confirm his ORCID iD in VIVO, and cite his VIVO page in his ORCID record as an external identifier.

In order to activate the VIVO-ORCID integration, your organization must have a membership in ORCID. You may then register your VIVO installation as a client application, and obtain the credentials needed for that connection.

Once you have the credentials, you can enter them in the runtime.properties file and restart VIVO.

You may want to start by obtaining credentials for ORCID's sandbox API. This will let you see how the integration appears. If you have made local modifications to VIVO, you will want to ensure that they do not interfere with the integration before going into production.

Once you are satisfied that the integration is working as expected, you can apply for credentials on ORCID's production registry.

Video tutorial


When applying for credentials

Informing the users

The user must grant authorization before VIVO can read or write to their ORCID record. Some of the text they see will come from your credentials. Notice this section of the application:

The name of your client application will be displayed to the user as they use the integration screens. Here is an example, where the name of the client application is "Cornell VIVO-ORCID Integration".

If the user clicks on the question mark, they will see the short description of your client application. In this example, the short description is "Connect your VIVO identity with your ORCID identity."

Connecting to your application

Once the user logs in to their ORCID account, and grants authorization to your application, the ORCID pages will transfer control of the session back to VIVO. In order to do that, it needs to know where your application is located. Notice this section of the application:

You may provide just the domain of your application, such as http://vivo.mydomain.edu.

Configuring VIVO

To converse with ORCID, VIVO requires these values in the runtime.properties file.

Property nameorcid.clientId
Description
The Client ID from your ORCID credentials

When your application for credentials is accepted, you will receive a Client ID to be used in communications with the API. If you apply for sandbox credentials first, and then production credentials, you will likely receive two different Client IDs.

Default valueNONE
Example value
0000-0012-0661-9330


Property nameorcid.clientPassword
Description
The Client Secret from your ORCID credentials

When your application for credentials is accepted, you will receive a Client Secret to be used in communications with the API. If you apply for sandbox credentials first, and then production credentials, you will likely receive two different Client Secrets.

Default valueNONE
Example value
103de999-1a37-400c-309f-2094ba72c988


Property nameorcid.webappBaseUrl
Description
The base URL for your VIVO application, as seen from outside.

VIVO will use this to construct a callback URL that the ORCID API can use to return control to VIVO. The actual callback URL will be the string you provide here with the suffix of /orcid/callback added at the end.

Default valueNONE
Example value
http://vivo.mydomain.edu

http://some.domain.edu/vivo/


Property nameorcid.apiVersion
Description
The version of ORCIDs API protocol that VIVO will expect.

Versions 1.0.23, 1.2, or 2.0

Default valueNONE
Example value
2.0


Property nameorcid.externalIdCommonName
Description
The label used to describe a VIVO profile page

If the user authorizes the addition of their VIVO profile page to their ORCID record, it will appear as an "external ID", with this label

Default valueNONE
Example value
VIVO profile page at Great Western University


Property nameorcid.api
Description
The entry point for ORCID's public API.

This changes, depending on whether you are using the sandbox API or the production API.

Default valueNONE
Example value
sandbox
release