orcid collect & connect: understanding integrations and the api (m. buys)

ORCID Collect & Connect:UNDERSTANDING INTEGRATIONS

ORCID ABU DHABI WORKSHOP | NOVEMBER 14, 2016

MATTHEW BUYS

orcid.org/0000-0001-7234-3684REGIONAL DIRECTOR

OUR VISION

ORCID’s vision is a world where all who participate in research, scholarship, and innovation are

uniquely identified and connected to their contributions and affiliations

across time, disciplines, and borders.

Persistent digital identifiers to distinguish researchers from each otherMember-built integrations for automated links between researchers and their activities/affiliationsA hub for machine-readable connections between identifiers for organizations, funding, outputs, and people

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

ORCID PROVIDES

INTEGRATIONS BY REGION

INTEGRATIONS BY SECTOR

COLLECT & CONNECT GOALS

• Clarify how plumbing works• Standardize experience• Standard connection installation guidelines• Increase predictability and trust in the “utility”• Community approach to reliable connections

COLLECT & CONNECT

Collect

Display Connect

Synch

Authenticate!

API - If your software gives my software one of these instructions I’ve defined, it will perform this action, or return this information.

OAuth2 - A standard set of rules which resource owners (commonly users) to grant access to APIs SECURELY.

RESTful Service - A web API that implements a popular and simple set of instructions in the same way as a whole bunch of other web APIs do.

Persistent Identifier - An identifier that exists for a long long long time and points at data. web APIs do.

Unique Identifier - Being the only one of its kind, a set of letters and numbers that identifies one thing and only that thing.

SOME PHRASES

• permissions / scopes – your contract with the user

• the ORCID messages – format of the data exchanged

• OAuth calls – the permission protocol – how you “execute the contract”

• ORCID-specific calls – providing & receiving information with the registry

the ORCID API in a nutshell

PHOTO: 3/2 nuts © M.G. Kafkashttps://flic.kr/p/4XytpS

DISPLAY• In

metadata• On sites• In

publications

CONNECT• Affiliations

(employers)• Works

(publishers)• Awards (funders)

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 boardwww.flickr.com/photos/creative_stock/5227842611

Get permission: API-edition

orcid.org

ORCID registry depends on user-based permissions: Can I...• have your iD (/authenticate)• interact with the activities on your record

• read (/activities/read)• update (/activities/update)

• interact with your biographical information• read (/person/read)• update (/person/update)

PHOTO: Job Meetingwww.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 Meetingwww.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

PHOTO: electronic circuit boardwww.flickr.com/photos/creative_stock/5227842611

what the user sees

orcid.org

Collect

COLLECT validated ORCID iDs for individuals

• Explain what ORCID is• Explain why you’re collecting iDs• Consistent user experience• Authenticated connections

Ensure individuals are correctly connected with your institution

Converis, Pure, Symplectic Elements, VIVO use the OAuth process

PHOTO: electronic circuit boardwww.flickr.com/photos/creative_stock/5227842611

the OAuth calls – the result

orcid.org

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

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

Display 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 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

Hindawi, Geometry

iDs in profiles

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

You have the iD, now display it!

Connect 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 others

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

PHOTO: electronic circuit boardwww.flickr.com/photos/creative_stock/5227842611

Use permission: API-edition

• Read data: GET • Add data: POST• Update data: PUTBASE URL: https://api.orcid.org/v2.0/0000-0000-0000-0000HEADERS: accept:application/json (reading) content-type:application/json (adding /updating)Authorization: Bearer 6710dfee-6aab-445b-a266-205dd9085273DATA (if adding or updating): the file location=@file_location_name

Modifiers: /works/update

data format

Access token from before

Read & update through a “message”

PHOTO: electronic circuit boardwww.flickr.com/photos/creative_stock/5227842611

Examples• Add a work:

POST https://api.orcid.org/v2.0/0000-0000-0000-0000/work• Update employment info

PUT https://api.orcid.org/v2.0/0000-0000-0000-0000/employment

• Read updated award data from another organizationGET https://api.orcid.org/v2.0/0000-0000-0000-0000/funding/19328

include: • Access token• Data file location & type

Unique referenceto the award

SynchronizeSYNCHRONIZE 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

PHOTO: electronic circuit boardwww.flickr.com/photos/creative_stock/5227842611

Enabling synchronizationORCID 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

People, places, and things

Integration Process

Technically, integrating ORCID involves adding <person ID> and <source> fields to data models, mapping to ORCID API, and implementing OAuth and RESTful calls.

Socially, it is critical that researchers are engaged in the process.

Live example

Google playgroundhttp://tinyurl.com/zrmbxqbScope: /orcid-works/create

Header name: accept / Header value: application/vnd.orcid+xmlHeader name: Content-type / Header value: application/vnd.orcid+xml

Community resources

• Best practices and use cases• Updated info on members.orcid.org• Resources and collateral for

researchers• ORCID engagement & awareness

campaign

Best practices and use cases

• Sample text for describing ORCID and your engagement• Graphics, videos, use cases• Collect & Connect program badges • Code samples, workflows, and API tutorials

http://members.orcid.org

Researcher resources

• Researcher workflow infographics• Relevant blog posts • Researcher use cases, testimonials• Membership and integration lists• Mini-videos of how ORCID works

Engagement campaign

• Series of blog posts• Social media campaign• Speaking engagements• Ambassador outreach

• Find out more at http://orcid.org

• Register at http://orcid.org/register

• Twitter @ORCID_Org / @mjbuys

THANK YOU!

Matthew BuysRegional Director, ORCID

m.buys@orcid.orghttp://orcid.org/0000-0001-7234-3684

API Demo

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