Workflow: eTheses & Dissertations submission systems

This workflow sets out a process in which a typical eTheses or dissertation (ETD) submission system may integrate with the ORCID API. It gives a walkthrough of the process of receiving authenticated ORCID iDs from authors and reviewers, retrieving data from ORCID records, adding works to ORCID records, and updating works which you have previously added to ORCID records. It is based on version 2.0 of the ORCID message schema.

Introduction

Using ORCID in your eTheses or dissertation submission process is good for your institution and your students alike. It enables you to create validated connections between your students, their EDTs, and their affiliation with your institution, which makes them and their ETDs more discoverable in turn.

Common integration points for ETD systems:

  1. Before you start: system setup
  2. Collect students’ iDs as part of the ETD submission process
  3. Display students’ iDs in publication metadata and in your repository
  4. Connect ETD information to your students’ ORCID records
  5. Synchronize your system with ORCID records to keep ETD information up to date
  6. Take your system one step further

Before you start: System setup

Please be sure to check that your system meets the requirements below. Additional setup requirements for more advanced integrations can be found in the relevant section(s).

  • Your system must be able to accept and store ORCID iDs together with the researcher’s information.
  • Your system must be able to capture a six-digit authorization code and exchange it for an access token immediately.
  • Your system must also be able to accept and store persistent access tokens together with the researcher’s information. We strongly recommend that you store all of the token response, including refresh tokens, scopes, and token expiry, as these can be useful if access tokens are lost, or if you upgrade your system to support new scopes.
  • Customized interaction messages: We recommend creating at least three messages, which can be on pages pages:
    • Start message: Where researchers initiate the connection process
    • Connection-success message: This message should display on the page the researcher is redirected to after successfully authorizing the connection with your system. It should display their ORCID iD and can also display a thank you or acknowledgement message.
    • Connection-failure message: This message should display on the page the researcher is redirected to after denying authorization to your system. It should give the reasons you requested permission from the researcher and again offer the opportunity to grant permission.
  • Log interactions: Your system should record both calls made to the ORCID API and responses received; this is necessary so our team can help if a problem develops later.

Collect iDs from students submitting ETDs

As a research institution, you can integrate ORCID into your ETD systems, embedding the ORCID iDs of students and, where relevant, advisors or reviewing committee members into your ETD metadata to enable the iDs to be used throughout the ETD publishing workflow. You can also use data from the ORCID record to populate their profiles in your ETD system. And you can enable students and reviewers to sign into your ETD system using their ORCID iDs.

It is critical that you collect ORCID iDs and obtain permission to update your students’ ORCID records, either immediately or in the future, by requiring users to sign into ORCID from within your system and then retrieving their data from the ORCID Registry using the ORCID API. It is also essential to provide information on your site about why you are collecting ORCID iDs and why this is beneficial to your students.

The steps to complete the Collect process are:

Provide a hyperlinked ORCID-branded button for collecting authenticated ORCID iDs: This can be at sign in, within the student’s or advisor's personal profile, on the review page, or on the submission form itself. Using the ORCID button consistently helps ensure that students associate it with being asked to securely provide their iD, which in turn builds trust in ORCID as a reliable identifier.


Example button graphics and code

Customize the user experience! You can specify a display language, pre-fill the researcher’s name, and include a state parameter which will be returned with the user to your system.

Configure the button’s link to request permissions to access the student’s ORCID record via the API: You'll be getting the ORCID iD by obtaining an access token through three-legged OAuth authorization, and this starts with a link customized with your API credentials and scopes that represent the access permissions you're requesting. If you are only planning to collect and display ORCID iDs within your ETD system and the ETD itself, then you need /read-limited access to an ORCID record. (If you are using the public API, replace this with /authenticate>.)

If you are planning to add students’ ETDs to their ORCID records, then you should request both /read-limited and /activities/update access.

This example requests permission to read limited access data on the ORCID record and update the activities section on the sandbox server. Replace the bracketed data with your client information and paste directly into your web browser to generate an access token for testing (be sure to remove the brackets!).

https://sandbox.orcid.org/oauth/authorize?client_id=[Your client ID]&response_type=code&scope=/read-limited%20/activities/update&redirect_uri=[Your landing page]

Get an access token to get the researcher’s ORCID iD: The researcher signs into their ORCID account and simultaneously authorizes the connection. They are sent back to your landing page -- the Redirect URI specified in the OAuth link. Appended to the end of that link will be a 6-digit authorization code and any state parameter you specified:

https://[Your landing page]?code=gtYn37

At this point, your system’s user interface should display a helpful message to the researcher, e.g. “Thanks for connecting your ORCID iD!” or simply display their iD in full—see the Display section below.

In the system backend, immediately exchange the authorization code. The authorization code expires upon use.

  URL=https://sandbox.orcid.org/oauth/token
  HEADER: Accept: application/json
  DATA: 
    client_id=[Your client ID]
    client_secret=[Your client secret]
    grant_type=authorization_code
    code=[Six-digit code]
    redirect_uri=[Your landing page]

     Example call: 3-legged OAuth 

ORCID will then return the authenticated ORCID iD along with an access token:

{"access_token":"c47026d9-90bf-4480-a259-a953bc103495","token_type":"bearer",
"refresh_token":"2d76d8d0-6fd6-426b-a017-61e0ceda0ad2","expires_in":631138517,
"scope":"/read-limited /activities/update","orcid":"0000-0001-2345-6789","name":"Sofia Garcia"}

If the user denies your system access: ORCID returns the researcher to the specified redirect URI and appends an error message:

https://[your landing page]?error=access_denied&error_description=User%20denied%20access 

Your system should read this and automatically direct the researcher to the connection-denied landing page. We strongly recommend that you use this opportunity to explain more fully to the researcher why you are collecting ORCID iDs and requesting permission to access their record, and to prompt them again to sign in and authorize the connection to your system.

Store the token exchange result (ORCID iD, access token, refresh token, scope, and expiry) together with the student's data in your ETD system in a safe and secure manner. The ORCID iD and access token will be required to perform any action to their ORCID record: read, write, update. If you are only requesting /authorize access, access tokens can be stored to indicate that the iD has been authenticated, and can be used to read public data.

Use the student’s iD and access token to read their record and populate their profile in your ETD system: Save students time by allowing them to quickly and easily transfer data from their ORCID records to your ETD system by making a call to their record:

  Method: GET
  Accept: application/vnd.orcid+xml or application/vnd.orcid+json
  Authorization type: Bearer
  Access Token: [Token from previous step]
  URL:  https://api.sandbox.orcid.org/v2.0/[ORCID iD]/record
  Example call: GitHub 

Once you have obtained the record data, you can use it to update your system. Our recommended process is by searching the external identifiers for the relevant item, e.g. works, and then querying the identifier source to obtain robust metadata for each item. Alternatively, you can use the put code to read all of the data that was added to the ORCID record for that specific item. See Read data on an ORCID record for more information on reading the ORCID record, and Read ORCID XML 2.0 for more information on interpreting the ORCID message schema.


Display iDs in your ETD system and metadata

Research institutions can use ORCID to clearly link students and, if wished, their advisors—and all their name variants—with their ETDs by embedding ORCID iDs into the metadata and displaying iDs in the final version of the ETD.

Including ORCID iDs in metadata and submitted ETDs requires that you have collected validated ORCID iDs from researchers as described above in Collect.

The steps to complete the Display process are:

Displaying iDs within your ETD system: Once a student has connected their ORCID iD to your system, clearly display their iD within their profile and/or on their submission so that they know that they have successfully connected and asserted their identity. Format the iD as a hyperlinked URI and include the green iD icon, per our iD Display Guidelines.

ORCID iD iconorcid.org/0000-0001-2345-6789

Displaying iDs in publications: Embed ORCID iDs in metadata. Doing this means that your students’ ORCID iDs will be searchable in databases which support this, such as your institution’s repository. The below example is for Crossref metadata -- see ORCID iD Throughput in Publishing Workflows for additional examples. 

<person_name>
  <given_name>Sofia</given_name>
  <surname>Garcia</surname>
  <ORCID authenticated="true">
    https://orcid.org/0000-0001-2345-6789
  </ORCID>
</person_name>

Connect information about the final ETD to students’ ORCID records

You can help make life easier for your students by connecting validated information about their successfully defended ETD to their ORCID records -- and you will also be helping to build trust in scholarly communications.

Adding an ETD to ORCID records requires that you have collected both ORCID iDs and update permission as described in Collect above.

System setup:

  • Your system must be able to save a put code, a unique identifier for items within the ORCID Registry, for each work item added to the ORCID Registry. Every item that is added to the activities section of the ORCID record is returned a put code—even if you add multiple items at once. If you ever need to read, edit, or delete the item you added, you will use the put code.
  • Your system must be able to send data in XML or JSON formatted in the ORCID Message Schema.

The steps to complete the Connect process are listed below.

Adding an ETD to an ORCID record

Format the ETD in ORCID message schema: The ETD is a type of research work in the ORCID Registry and it must be created in XML or JSON in the ORCID message schema.  Sample XML for for creating works can be found in our GitHub repository

At the minimum, the ETD work item must include the following elements:  

  • Title
  • Work type: This will generally be “dissertation” or “supervised-student-publication”
  • Unique work identifier: Add as many of these as your system is aware, as it aids in grouping on ORCID records, so researchers don’t have to group works manually
    • Work identifier type
    • Value of the identifier
    • Identifier URL (optional)
    • Relationship: self/part-of
      This is to indicate the relationship of the work to the identifier. For example, if the work is a book chapter, and the identifier is the ISBN for the book, then the relationship would be “partof”; if the identifier is the DOI for the book chapter itself, then the relationship would be “self”.

We also suggest that you include all other known metadata available for an ETD work item, in particular:

  • Publication date, which aids display sorting
  • Citation (we recommend BibTeX), which can be used to record any additional metadata not captured by the schema, e.g. co-authors, page numbers

Add the ETD to the student’s ORCID record: Use the ORCID iD and access token you have stored for the student to add the ETD using an HTTP POST call to the member API. Note, it is very unlikely that you will be adding multiple ETDs for each student; if you are, please refer to our GitHub repository for further endpoints and example XML.

  Method: POST
  Content-type: application/vnd.orcid+xml or application/vnd.orcid+json
  Authorization type: Bearer
  Access Token: [Stored access token]
  Data: [Link to file or text of single ETD item to add]
  URL: https://api.sandbox.orcid.org/v2.0/[ORCID iD]/work
  Example call: GitHub

Save the returned put code in your system in association with the ETD. In a typical scenario – adding a single ETD – the API will return a 201 Created message to indicate that the item posted correctly. For multiple works, if applicable, the API will return a 200 OK message to indicate that the items posted correctly. Check our troubleshooting page if a different message is sent.

  HTTP/1.1 201 Created [...]
  Location: https://api.sandbox.orcid.org/v2.0/0000-0001-2345-6789/work/739286

Synchronize your system’s data with researchers’ ORCID records

Updating your students’ profiles within your system, to reflect any changes made to their ETD or affiliation, helps reduce the reporting burden for your authors and reviewers and improves data quality.

Synchronize data between your system and ORCID by automatically updating ORCID records and querying the researcher’s ORCID records for any new changes. This requires persistent (long-term) update tokens. (Premium members can register webhooks to receive pings from ORCID when monitored records are updated.)

Be sure to check the last modified date to find the latest information.

  <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  <record:record  [...]>
  <history:history>
    <common:last-modified-date>2016-11-29T11:29:23.584Z
    </common:last-modified-date>
  </history:history>
  [...]
  Example XML: GitHub

Updating an ETD on an ORCID record

An ETD added by your system may need to be amended or deleted from researchers’ records, for example in the event that poorly formatted or incorrect data were relayed, or that an ETD has been revoked by the institution. ETDs should be updated as a best practice, rather than deleted and reposted, but there are some cases where deletion is preferable:

Update

Delete

Correcting data, e.g. typos, formatting errors

ETD attributed to the wrong ORCID iD

Adding new data, e.g. identifiers

ETD review incorrectly recorded as work

Send a call to the API to update using the ORCID iD, access token, the updated ETD, and the work’s put code. Only ETD work can be updated at a time.

Format the updated ETD in ORCID message schema with the changed information and include the stored put code.

<?xml  version="1.0" encoding="UTF-8"?>
  <work:work put-code="[put code]" [...]  >
  [...] 
  </work:work>
  Example XML: GitHub

Add the updated ETD to the ORCID record: The final end point must be the put code of the ETD work item to be updated.

  Method: PUT
  Content-type: application/vnd.orcid+xml or application/vnd.orcid+json
  Authorization type:  Bearer
  Access token: [Stored access token]
  Data: [Link to file or text of work to update]
  URL: https://api.sandbox.orcid.org/v2.0/[ORCID iD]/work/[put code]
  Example call: GitHub 

The API will return a 200 OK message to indicate that the ETD item updated correctly. Check our troubleshooting page if a different message is returned.

Deleting an ETD on an ORCID record

Use the ORCID iD, access token, and the work’s put code to delete the work. Only one publication can be deleted at a time.

  Method: DELETE
  Authorization type: Bearer
  Access token: [Stored access token]
  URL: https://api.sandbox.orcid.org/v2.0/[ORCID iD]/work/[put code]
  Example call: GitHub 

The API will return a 204 NO CONTENT message to indicate that the item updated correctly. Check our troubleshooting page if a different message is returned.


Take your ETD system one step further

Besides collecting students’ iDs and linking them with their ETDs, your system can also:

  • Use ORCID sign-in: Collect students' and advisors' iDs from the outset by allowing them to sign into your ETD system using their ORCID accounts -- see more at ORCID as a sign-in option.
  • Identify the ETD advisors: Collect advisors’ iDs and display them within your system when you request their affirmation that they have reviewed the ETD. You can also connect information about their participation in the ETD.
  • Identify the ETD reviewers: Collect the iDs of the review committee and display them internally to acknowledge their work on the dissertation committee. You can also connect information about reviewers’ activities to their ORCID record with as much or as little detail as appropriate -- see more at the peer review workflow.
  • Assert your students’ affiliation with your institution: Add an educational affiliation with your institution to the student’s ORCID record. When the student successfully defends their dissertation and is awarded a degree, update the entry with the end date of their degree -- see more on adding affiliations at the research information and profile systems workflow. 
  • Add a link to the student’s profile or webpage on your system: Add a link to a personal profile or website under the websites section of the student’s ORCID record. See more on adding personal information such as websites at the research information and profile systems workflow.