1.2 Tutorial: Update activities (archive)

This guide is an archived document related to the 1.2 version of the ORCID Message Schema, which is no longer supported by ORCID. The current supported version is 2.0 documentation. Go to the document for the 2.0 Message Schema.

Introduction

This tutorial will walk you through updating affiliations, works, or funding items that you have previously added to an ORCID record using the PUT command in curl. You will only be able to update activities which your client has added. The update will completely replace all data which your client has previously added to the relevant section. Therefore you must include all items which your client has added in the file when updating -- any items which have been removed or are absent from the file will be deleted from the ORCID record. To add new affiliations, works, or funding items to a record see Tutorial: Add activities. To update the biographical section of an ORCID record see Tutorial: Update bio.

Note: This guide is based on version 1.2 of the ORCID Schema. Refer to the latest version of the schema for the most current information.

The text in bold in each example should be replaced with your own credentials, the relevant ORCID iD, and system responses. The access tokens from this process allow you to add multiple items at once, and multiple scopes can be requested at one time.

 

Scopes and Requests

Scope Request Description XML
/activities/update /orcid-works Update works on the ORCID record XML for works
/activities/update /affiliations Update education or employment items on the ORCID record XML for affiliations
/activities/update /funding Update funding items to the ORCID record XML for funding

 

Authorization

Updating information to a record follows the OAuth Dance as described in Tokens Through 3-legged OAuth Authorization. The access tokens returned can be short lived (expiring one hour after issue) or long lived (expiring 20 years after issue) -- long-lived tokens are the default. Both can be used multiple times before it expires.

 

Putting an item

An exampling call to get an authorization code to update a works is below. The URL to ask for permission can be pasted directly into a web-browser (with your own client-id and redirect-uri) and the scope can be changed to match the item type you wish to add. It will take you through the authorization steps in the User Interface where you can log-in to an existing ORCID account (in this case on the sandbox) and it returns you to the redirect-uri with a 6-character authorization code appearing at the end of that URL.

https://sandbox.orcid.org/oauth/authorize?client_id=APP-NPXKK6HFN6TJ4YYI&response_type=code&scope=/activities/update&redirect_uri=https://developers.google.com/oauthplayground

With this example, the final URL with the authorization code looks like

https://developers.google.com/oauthplayground/?code=Mo0WOt

You should then immediately exchange the authorization code for an access token. (This exchange should occur within 10 minutes at least. The auth code will expire within 24 hours.) An example cURL statement and response is below

curl -i -L -H "Accept: application/json" --data "client_id=APP-NPXKK6HFN6TJ4YYI&client_secret=060c36f2-cce2-4f74-bde0-a17d8bb30a97&grant_type=authorization_code&code=Mo0WOt&redirect_uri=https://developers.google.com/oauthplayground" "https://sandbox.orcid.org/oauth/token"

Response

HTTP/1.1 200 OK
...
{"access_token":"aa2c8730-07af-4ac6-bfec-fb22c0987348","token_type":"bearer","expires_in":631138518,"scope":"/activities/update","orcid":"0000-0002-2389-8429","name":"Sofia Hernandez"}

Use the access token to read the record, this will return all information in the section specified including information that is marked as private which you are the source of.

curl -H "Content-Type: application/orcid+xml" -H "Authorization: Bearer aa2c8730-07af-4ac6-bfec-fb22c0987348" "https://api.sandbox.orcid.org/v1.2/0000-0002-2389-8429/orcid-works"

Responses

HTTP/1.1 200 OK
...
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>...

Update the returned XML with the new information. If you wish to remove an item, leave it off the updated filed. Any items that you do not wish to change should be included in file without any changes. The final call will update the items using a PUT method.

curl -H "Content-Type: application/orcid+xml" -H "Authorization: Bearer aa2c8730-07af-4ac6-bfec-fb22c0987348" -d "@/Documents/updated_work.xml" -X PUT "https://api.sandbox.orcid.org/v1.2/0000-0002-2389-8429/orcid-works"

If the item posted correctly the update record will be returned.  If you receive a different message back you should check the list of API Error codes.

 

Example to add an affiliation

curl -H "Content-Type: application/orcid+xml" -H "Authorization: Bearer aa2c8730-07af-4ac6-bfec-fb22c0987348" -d "@/Documents/updated_affiliation.xml" -X PUT "https://api.sandbox.orcid.org/v1.2/0000-0002-2389-8429/affiliations"

 

Example to add a funding item

curl -H "Content-Type: application/orcid+xml" -H "Authorization: Bearer aa2c8730-07af-4ac6-bfec-fb22c0987348" -d "@/Documents/updated_grant.xml" -X PUT "https://api.sandbox.orcid.org/v1.2/0000-0002-2389-8429/funding"