VIVO Documentation
Page History
Table of Contents |
---|
...
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.
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 name | orcid.clientId |
---|---|
Description | The Client ID from your ORCID credentialsWhen 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 value | NONE |
Example value | 0000-0012-0661-9330 |
Property name | orcid.clientPassword |
---|---|
Description | The Client Secret from your ORCID credentialsWhen your application for credentials is accepted, you will receive a Client Secred 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 value | NONE |
Example value | 103de999-1a37-400c-309f-2094ba72c988 |
Property name | orcid.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 |
Default value | NONE |
Example value | http://vivo.mydomain.edu
|
Property name | orcid.messageVersion |
---|---|
Description | The version of ORCIDs API protocol that VIVO will expect.The integration code requires a value of |
Default value | NONE |
Example value | 1.0.23 |
Property name | orcid.externalIdCommonName |
---|---|
Description | The label used to describe a VIVO profile pageIf 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 value | NONE |
Example value | VIVO profile page at Great Western University |
Property name | orcid.publicApiBaseUrl |
---|---|
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 value | NONE |
Example value | http://pub.sandbox.orcid.org/v1.1 http://pub.orcid.org/v1.1 |
Property name | orcid.authorizedApiBaseUrl |
---|---|
Description | The entry point for ORCID's private API.This changes, depending on whether you are using the sandbox API or the production API. |
Default value | NONE |
Example value | http://api.sandbox.orcid.org/v1.1 http://api.orcid.org/v1.1 |
Property name | orcid.oauthAuthorizeUrl |
---|---|
Description | The entry point for ORCID's OAuth implementationThis changes, depending on whether you are using the sandbox API or the production API. |
Default value | NONE |
Example value | http://sandbox.orcid.org/oauth/authorize http://orcid.org/oauth/authorize |
Property name | orcid.oauthTokenUrl |
---|---|
Description | A callback URL within ORCID's OAuth implementationThis changes, depending on whether you are using the sandbox API or the production API. |
Default value | NONE |
Example value | http://api.sandbox.orcid.org/oauth/token http://api.orcid.org/oauth/token |
...