sharing information between systems: the orcid api (alainna wrigley)

orcid.org

The ORCID API

Alainna Therese�ORCID Community Engagement & Support �

[email protected] | orcid.org/0000-0002-6036-0903

a: 10411 Motor City Drive, Suite 750, Bethesda, MD 20817 USA

Sharing information between systems

Connecting info by names is complicated

orcid.org

Of the more than 6 million authors in a major journal citations and abstracts database,+2/3 share last name and single initial with another author. An ambiguous name in the same database refers on average to 8 people.

http://ands.org.au/newsletters/share_issue18.pdfPHOTO: Stairway to somewhere © Jonathan Fenton https://flic.kr/p/7Guxgu

ORCID provides

orcid.orgPHOTO: Stairway to somewhere © Jonathan Fenton https://flic.kr/p/7Guxgu

Persistent digital identifiers to distinguish researchers from each other

Member-built integrations that connect researchers and their activities/affiliations

A hub for synchronizing machine-readable connections between identifiers for people, organizations, and research activities

✔ Plumbing for research information ✔ Tools to build trust in digital information

Registration is simple

orcid.org

Register Directly via the ORCID website https://orcid.org/register

Or referred by an integration from another site

PHOTO: Stairway to somewhere © Jonathan Fenton https://flic.kr/p/7Guxgu

Registration is simple

orcid.org

Welcome to the ORCID Registry!

•  Unique and pers

istent

identifier

•  16-digit number

•  Expressed as H

TTP URI

•  Compatible with ISO

standard

•  Verify your email address

•  Here’s your ORCID iD:


The ORCID record

orcid.org

Biographical data è

ç Education data

ç Employment data

ç Works data

ç Funding data


The ORCID record

orcid.org

Education & employment data

Organization list from è Ringgold (an ISNI Registrar)


The ORCID record

orcid.org

Funding data

Funding agency ç list consistent

with FundRef

Search & link wizard ê


The ORCID record

orcid.org

Works data

Structured citations in BibTeX

Classifications & metadata fields consistent w/CASRAI

Translated titles & language support

Search & Link Wizards: •  Crossref Metadata Search •  Scopus •  Europe PubMed Central •  ResearcherID •  Modern Language

Association •  DataCite Metadata Store •  Redalyc •  Ariti •  ANDS Registry

BibTeX import PHOTO: Stairway to somewhere © Jonathan Fenton https://flic.kr/p/7Guxgu

The ORCID record

Works data When the same work is added by multiple sources, the different versions are grouped together based on work identifier

Source information is captured for all items added to the record


The ORCID record Peer review data Only posted via API by clients

approved for peer review

Live: F1000, AGU/eJournalpress, Publons In progress: Aries Systems, eLIFE, Hindawi, Politics & Religion Journal, Peerage of Science


Information in an ORCID Record has a privacy setting, which only the account owner can set – API cannot override.

Account information (settings, permissions) is accessible by the account owner.

User privacy

Public view Account owner Account owner, Trusted orgs & individuals

Accessible by :


ORCID enables Organizations use the ORCID API to authenticate, collect, display, and connect persistent identifiers for people, places, and things in research workflows

7 October 2016 orcid.org 14

API Features Member API ORCID member organizations(Sandbox test environment freely available to anyone)

•  Authenticate: Get a user’s authenticated ORCID iD

•  Read: Search/retrieve public and limited access data

•  Add/Update: Post new items to a record or edit/delete items you previously added

•  Create: Facilitate creation of new ORCID records (via on-demand process)

Premium Member API Premium ORCID member organizations

•  Webhooks: Receive notifications of updates

•  Customised monthly reports

•  Access to monthly public data file

ORCID API

Connecting to the ORCID registry

orcid.org

Two models:

1.  Connect via a vendor system•  Manuscript submission/publication•  Document/data repositories•  Profile systems•  CRIS systems

2.  Develop a custom connection


Custom integrations

orcid.org

Via the ORCID API

•  Fine-tuned control and permissions•  Customized buttons, user flows, & user feedback

Current integration list: �http://members.orcid.org/current-integrations


Selected vendor system connections

orcid.org

Publishing•  eJournal Press•  Editorial Manager•  ScholarOne

Document / data repositories•  DSpace•  ePrints•  Hydra/Fedora

CRIS Systems•  Converis•  Elements•  IRMA•  Pivot•  PlumX•  Pure•  Vivo

http://members.orcid.org/orcid-enabled-systems


7 October 2016 orcid.org 18

DISPLAY•  In metadata•  On sites•  In publications

CONNECT •  Affiliations (employers)•  Works (publishers)•  Awards (funders)

Collect COLLECT validated ORCID iDs for individuals •  Explain what ORCID is•  Explain why you’re collecting iDs•  Consistent user experience•  Authenticated connections

orcid.org

Ensure individuals are correctly connected with your institution

Many vendor systems use the OAuth process

orcid.org

Get permission, use permission

ORCID Record

Yes!

Do you have permission to do what you want to do?

Get the permission; store iD and “token”

Read the record or update the record

No

OAuth

PHOTO: electronic circuit board www.flickr.com/photos/creative_stock/5227842611

Get permission

orcid.org

ORCID registry depends on user-based permissions: �Can I...•  have your iD (/authenticate)

•  read limited-access data on your record�(/read-limited)

•  interact with the activities on your record�(/activities/update)

•  interact with your biographical information �(/orcid-bio/update)

PHOTO: Job Meeting www.flickr.com/photos/jobmeeting/14375164286

Involving the user

orcid.org

Key benefits:•  You know the user controls the iD•  User knows what’s going on/ user choice•  Privacy/ data control trends•  Position/ strengthen your system as a service

How?•  Just a “fancy” URL•  Prior iD not needed•  Hard things: promotion, finding touch points

PHOTO: Job Meeting www.flickr.com/photos/jobmeeting/14375164286

Get permission: touch points

orcid.org

Look for natural fits:•  Your sign in – why not link your iD?•  Your account settings/user profile•  Submission (of any type)•  Form fills: pre-fill from your Record!•  Registration: for conference or meeting•  Reporting: Link your iD to get started


Step 1: fancy URL

orcid.org

https://sandbox.orcid.org/oauth/authorize? \client_id=APP-XT8FBKJRO3MR8WDR& \response_type=code& \scope=/read-limited%20/activities/update& \redirect_uri=https://my.URL.org& \ family_names=Researcher&given_names=Bob&[email protected]&orcid=0000-0001-6356-0580

The base URL, displays ORCID sign in screen

who’s asking? what permissions? where the user goes next

Personalise the experience

The OAuth call: part I


What the user sees

orcid.org

already signed in sign in form (already registered)

registration form

[email protected]


Step 2: Auth code & user feedback

orcid.org

ORCID sends the user to your redirect, with a codehttps://my.URL.org?htA3yE

•  Save the code – you need it for the next step•  Display something useful to the user

•  Authorize: thanks for your permission!

•  Deny: are you sure you don’t want to give �

permission?

The auth code


Step 3a: Transform the code into a token

orcid.org

Use the code to gain access using the ORCID APIhttps://sandbox.api.orcid.org/oauth/token

HEADER: accept:application/jsonDATA: client_id=APP-XT8FBKJRO3MR8WDR client_secret=e285575c-4794-464b-a807-6f1c06b63grant_type=authorization_codecode=htA3yEredirect_uri=https%3A%2F%2Fmy.URL.org

our API calls always looks like URLs (RESTful) what format?

The auth code confirming that you are the right one to get this information


Step 3b: Store the result

orcid.org

the result of the call"access_token” :"6710dfee-6aab-445b-a266-205dd9085273","token_type" : "bearer","expires_in" : 631138518,"scope" : "/read-limited /activities/update","orcid" : "0000-0001-6356-0580","name" : "Bob Researcher"

store the access token and iD

when permission expires (in seconds)

your permission – executed contract

iD & name for the person who gave permission

What you can do

✔ iD Collected!

Display

orcid.org

DISPLAY iDs on your website, platform, systems •  iDs shown as a link•  iDs in metadata•  Use the ORCID Member logo•  Explain why iDs are collected

Signal to your researchers and the wider community that your systems are plumbed to support ORCID iDs

http://orcid.org/trademark-and-id-display-guidelines

You have the iD, now display it! iDs in print

Royal Society, Biology Letters

iDs electronically

Nature, Genetics

orcid.orgPHOTO: Job Meeting www.flickr.com/photos/jobmeeting/14375164286

Display: iDs in profiles

orcid.org

You have the iD, now display it! ORCID iD in DOI metadata:<person_name>

<given_name>Karl</given_name><surname>Ward</surname><ORCID authenticated=“true”>

http://orcid.org/0000-0002-4121-9960</ORCID>

</person_name>

•  iD available in search

orcid.orgPHOTO: Job Meeting www.flickr.com/photos/jobmeeting/14375164286

Connect

orcid.org

CONNECT your data to ORCID records •  Request permission to write to records•  Store long-lived tokens•  Add data that you uniquely can (authoritative)•  Explain the connection

Enable researchers to provide validated data to other systems they use

https://orcid.org/blog/2015/10/26/auto-update-has-arrived-orcid-records-move-next-level

Verb: POST BASE URL: https://sandbox.api.orcid.org/v1.2/0000-0001-6356-0580/affiliations HEADERS: Content-type:application/json Authorization: Bearer 6710dfee-6aab-445b-a266-205dd9085273 DATA (if adding or updating): the file [email protected]

Relevant area:

/orcid-bio /funding

/orcid-works /peer-review

data format

Access token from before

Type of action, also: READ; PUT

1. Your client sends data 2. Researcher’s record updated

Connect via API to send data

Read & update through a “message”

orcid.org

Synchronize

orcid.org

SYNCHRONIZE with your systems •  Update information when it changes•  Auto-add new information•  Search & link wizards•  Sync data from others

Saved time, better reporting, improved information flow

https://members.orcid.org/api/tutorial-webhookshttps://orcid.org/blog/2015/10/26/auto-update-has-arrived-orcid-records-move-next-level


Enabling synchronization

orcid.org

ORCID API features & tips: •  Update notifications (webhooks)

•  Your system registers iDs you’re watching•  ORCID notifies when changes happen

•  Internal triggers•  Employment status change•  Publication acceptance•  Publication correction•  Funding award

API in action: Create on demand

http://orcid-create-on-demand.herokuapp.com

Resources


Bootcamp: ORCID API (Searches, OAuth, Create on Demand)http://is.gd/VALA2016ORCID

ORCID Create on Demand Demohttp://orcid-createondemand.herokuapp.com

Collect & Connect @ Member Support Centrehttps://members.orcid.org

API documentationhttps://members.orcid.org/api

ORCID API User Listservhttp://groups.google.com/group/orcid-api-users

ORCID API Source (Github)https://github.com/ORCID/ORCID-Source/blob/master/orcid-model/src/main/resources/README.md

•  •  •  •  •  • 