ORCID Record Action

ORCID API Configurations

1. Register your personal public API client

Log in your ORCID account and visit the developer tools page, create your personal public API client. Detailed steps please refer the offical document. You can fill in application information and redirect URIs as you like, it has no effect on the subsequent steps.

Please remember your Client ID and Client secret.

2. Get your access token

In command line, use your Client ID and Client secret to get your access token. It should have a very long expiration time (about 20 years):

curl -H "Accept: application/json" -H "Content-Type: application/x-www-form-urlencoded" --data-urlencode
 "client_id=CLIENT_ID" --data-urlencode "client_secret=CLIENT_SECRET" --data-urlencode
 "scope=/read-public" --data-urlencode "grant_type=client_credentials" https://orcid.org/oauth/token

Then you may get a response in JSON format:

{"access_token":"xxx","token_type":"bearer","refresh_token":"xxx","expires_in":631138518,"scope":"/read-public","orcid":null}

Please remember the access_token.

Inputs

orcid-id

Required The ORCID ID of researcher.

access-token

Required The ORCID access token obtained above.

record-file

Optional The record json file to write. If this input was given, the output record will not be generated.

Outputs

record

The record string in JSON format. This output only exists when the record-file input is not given.

Example usage

1. (Optional) Save your access token and other variables in GitHub

Create a new repository secret in https://github.com/USERNAME/REPOSITORY/settings/secrets/actions, create a new repository secret to store your access_token obtained above. Here we name it ORCID_ACCESS_TOKEN.

Further, in this page, switch to the Variables tab, create follow variables for your workflow:

Name	Description	Example
ORCID_ID	Your ORCID id.	XXXX-XXXX-XXXX-XXXX
ORCID_ACCESS_TOKEN	The ORCID public api access token.	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
RECORD_FILE	The related path of the works file in your repository.	assets/record.json

2. Create an action to auto update your ORCID record.

The workflow's code is as follows:

name: Update Record

on:
  # Create a scheduled task, in this example we run it at the first day of every month.
  schedule:
    - cron: "0 0 1 * *"
  # Enable manually executing.
  workflow_dispatch:

permissions:
  contents: write
  
jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v4
    
    # Fetch record with orcid id and access token
    - name: Get record with token
      uses: sxlllslgh/orcid-record-action@v1
      id: record
      with:
        orcid-id: ${{ vars.ORCID_ID }}
        access-token: ${{ secrets.ORCID_ACCESS_TOKEN }}
        record-file: ${{ vars.RECORD_FILE }}
      
    - name: Make sure the record file is tracked
      run: git add ${{ vars.RECORD_FILE }}

    # If record file changed, return exit code 1, otherwise 0.
    - name: Judge if file changed
      id: changed
      continue-on-error: true
      run: git diff --exit-code ${{ vars.RECORD_FILE }}

    - name: Judge if staged file changed
      id: cached
      continue-on-error: true
      run: git diff --exit-code --cached ${{ vars.RECORD_FILE }}

    - name: Update record
      if: ${{ steps.changed.outcome == 'failure' || steps.cached.outcome == 'failure' }}
      run: |
          git config --global user.name '${{ vars.GIT_USERNAME }}'
          git config --global user.email '${{ vars.GIT_EMAIL }}'
          git commit -am "Automatically update record."
          git push