Welcome to ORCID Hub’s documentation!¶

The home of development for the New Zealand ORCID Hub.

Because New Zealand ORCID Hub is fun to use.

Table of Contents¶

ORCID Hub Installation¶

NB the Hub is intended to be, and the core code is, cross-platform; however it’s much simpler to get a fully functioning instance with *nix. Install instructions for an evaluation Hub instance on Windows will follow as the kinks are worked out.

There are three different routes to getting an ORCID Hub instance up and running:

managing the dependencies yourself

via the ORCID-Hub PyPI Python package

setting up from the GitHub source

via the orcidhub Docker Image

Reasons to choose between the route:

The Docker image, and to a lesser extent the PyPI package, gives a very quick to launch an instance of the Hub for evaluation. With the PyPI package you need to add sendmail and redis for typical functions; while running from source will also be prompted to set up the backend database. Running from the GitHub source will be a little slower to get going and involves more moving parts but provides the easiest way to allow you to customise the look and feel to suit your Consortium. NB all routes out of the box will launch an unmodified version of the NZ ORCID Hub including local references to New Zealand and the Royal Society Te Apārangi.

Managing the dependencies yourself¶

The Hub requires Python 3.x. We recommend both Python3.6, and running the Hub with a virtual environment, e.g. in your working directory:

virtualenv -p python3.6 venv
. ./venv/bin/activate

The Hub uses a database backend, with either SQLite or PostgreSQL supported. We currently recommend PostgreSQL 11. NB if no database url is given the Hub defaults to an embedded SQLite store.

Before you start you need to establish a means of authenticating the user¶

In order to enable login via ORCID you’ll need to acquire ORCID API credentials for your Hub. As this is only an ‘authenticate’ call, the public API is fine. If you’re new to the ORCID API, public API credentials for the ORCID sandbox can be obtained like so:

Create or login with an existing account at https://sandbox.orcid.org;

Navigate to “Developer Tools” (https://sandbox.orcid.org/developer-tools);

Add your instance (e.g. for a local install http://127.0.0.1:5000/auth) to the allowed redirect URL list and hit Save;

Copy the resulting CLIENT_ID and CLIENT_SECRET for the needed environment variables: ORCID_CLIENT_ID and ORCID_CLIENT_SECRET

To enable Identity Federation SSO, you’ll either need to configure your Hub instance as a Shibboleth Service Provider. As well as registering your instance SP, running Shibboleth also comes with its own dependency of Apache. See: Shibboleth installation and SP Creation.

As an alternative to setting up the instance as a SP, it is possible to run the application as a stand-alone Python Flask application and use another remote application for user authentication. For example, if the remote SP is being provided by https://dev.orcidhub.org.nz, all you need is to set up the EXTERNAL_SP environment variable, e.g.,

export EXTERNAL_SP=https://dev.orcidhub.org.nz/Tuakiri/SP

Optional dependencies¶

To enable the Hub to send email and act on task queues, you’ll need to install redis for your environment as well as configuring your environment’s sendmail service. More information on setting up sendmail can be found here: Sendmail Configuration.

The NZ ORCID Hub uses Sentry for error tracking and user feedback. We’ve found it a great service, but this is optional and likely unnecessary for any evaluation.

Setting environment variables¶

A Hub instance needs a range of environment variable to be set in order to function. These can be set manually or by script at each runtime or, for ease, managed via a settings.cfg file. The variables that must be set in your environment are: FLASK_APP, PYTHONPATH, and if you’re using them DATABASE_URL and EXTERNAL_SP, e.g.:

export FLASK_APP=orcid_hub
export FLASK_ENV=development
DIR='$( cd '$( dirname '${BASH_SOURCE[0]}' )' && pwd )'
export PYTHONPATH=$DIR
export LANG=en_US.UTF-8
export DATABASE_URL='postgresql://orcidhub:****@localhost:5432/orcidhub'
export EXTERNAL_SP='https://dev.orcidhub.org.nz/Tuakiri/SP'

For convenience you might want to script this initial setup.

The following variables can be provided by either settings.cfg placed in the /instance folder OR by directly exporting to the environment:

Variable	Description
ENV	The runtime environment name (default: dev)
DEFAULT_COUNTRY	The Country default for any ORCID writes (default: NZ)
NOTE_ORCID	Default note text for ORCID API requests (default: An NZ ORCID Hub integration for)
CRED_TYPE_PREMIUM	The default type of credentials requested (default: 2, i.e,. “Premium Member”)
APP_NAME	Default App name prefix for ORCID API requests (default: NZ ORCID HUB for)
APP_DESCRIPTION	Default App description prefix for ORCID API requests (default: This is an ORCID integration through the NZ ORCID HUB connecting)

Configuring authentication services, i.e., in the absence of EXTERNAL_SP, or if using ORCID only

Variable	Description
SHIB_IDP_DOMAINNAME	Your Identity Providers domain name (default: http://directory.tuakiri.ac.nz)
SHIB_METADATA_CERT_FILE	Meta data signing certificate location (default: conf/tuakiri-test-metadata-cert.pem)
SHIB_METADATA_PROVIDER_URI	Shibboleth SAML 2.0 meta data provider URI [NativeSPMetadataProvider](https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPMetadataProvider) (default: https://engine.surfconext.nl/authentication/idp/metadata)
SHIB_SP_DOMAINNAME	Your Service Providers domain name (default: ${ENV}.<container domainname>)
SHIB_SSO_DS_URL	SSO discovery service URL (default: https://${SHIB_IDP_DOMAINNAME}/ds/DS)
ORCID_CLIENT_ID	Orcid API client ID and secret, e.g., 0000-1234-2922-7589
ORCID_CLIENT_SECRET	Orcid API client ID and secret, e.g., b25ab710-89b1-49e8-65f4-8df4f038dce9

Configuring the attribute mapping for your SP. These should match the attributes exposed by your service provider (e.g. Shibboleth):

Variable Description ========================== ================== MAIL_SERVER Mail server’s name or IP (default: dev.orcidhub.org.nz) MAIL_PORT Port for sending mail (default: 25) MAIL_DEFAULT_SENDER Mail from Hub to be sent as (default no-reply@orcidhub.org.nz) MAIL_DKIM_DOMAIN Domain name to use for DKIM signed mail (default orcidhub.org.nz) MAIL_DKIM_SELECTOR Selector for DKIM signed mail (default default) MAIL_SUPPORT_ADDRESS Helpdesk email address, used in errors and as default Reply-To (default orcid@royalsociety.org.nz) RQ_REDIS_URL Redis server for rq (default redis://localhost:6379/0) ========================== ==================

Optional variables

Variable	Description
SECRET_KEY	To specify the Hub secret key for data encryption (optional)
SENTRY_DSN	Sentry project DSN (optional)
GA_TRACKING_ID	Google Analytics Tracking ID (optional)
CSRF_DOMAINS	Semicolon delimited whitelist of FQDNs, used to check Referer headers (default localhost;c9users.io)

Minimal deployment via PyPI¶

Assuming you have created and activated your Python 3.6 virtual environment and are in your working directory, a minimal ORCID Hub instance can be quickly set up with PyPI package and the following steps:

pip install -U 'orcid-hub'

By default the PyPI application creates an embedded Sqlite3 database. To use another backend, specify the engine and location via the DATABASE_URL environment variable from its default (sqlite:///data.db). Ensure the environment variables are set, settings.cfg is configured, and then create the first user as a Hub Administrator

orcidhub cradmin myadmin@mydomain.net --orcid YOUR-ORCID-ID -O YOUR-ORGANISATION-NAME

This command will create a Hub Admin user with email myadmin@mydomain.net, and if using ORCID authentication, i.e., you’ve set ORCID API credentials, YOUR-ORCID-ID, and at the same time registering the first organisation with YOUR-ORGANISATION-NAME.

Launch the Hub with:

orcidhub run

The result you can expect is for the terminal to start logging HTTP requests to the new development Hub instance that you are serving from your localhost. Navigate to this instance in any modern browser and you should be able to sign in with your chosen service.

NB: However until the rq worker and scheduler are running this instance will not be able to action batch tasks and so won’t send mail.

Minimal deployment via GitHub source¶

Running the Hub from source is very similar to setting up from the PyPI orcid-hub package. Ensure that git is installed and then from a terminal, clone the Hub source into a suitable location and if desired switch to the branch. NB: default master is Hub’s core development branch, origin/prod is the most current stable production release. The folder NZ-ORCID-Hub now becomes your working directory:

git clone https://github.com/Royal-Society-of-New-Zealand/NZ-ORCID-Hub.git
cd NZ-ORCID-Hub
git checkout origin/prod

Create the additional directories that a running Hub will require, enable the recommended python virtual environment, and install the Hub’s requirements:

mkdir -p data/redis pgdata
virtualenv -p python3.6 venv
. ./venv/bin/activate
sudo apt install python3.6-dev
pip install -U pip
pip install -U -r dev_requirements.txt

Set environment variables, and (optionally) create and configure instance/settings.cfg. NB by pulling source code the instance folder will have been created with a settings.sample.cfg that can be used as a guide.

Once the environment has been set up you create the Hub superuser and launch for the first time:

export FLASK_ENV=development
export FLASK_APP=orcid_hub
flask cradmin myadmin@mydomain.net --orcid YOUR-ORCID-ID -O YOUR-ORGANISATION-NAME
flask run

The terminal should show the Hub logging, and served from localhost. As with PyPI, additional processes are needed for this instance to start responding to tasks.

Launch queue worker and a scheduler¶

To enable the Hub to action tasks, redis must be installed and running, and two additional processes need to be active. The easiest way to launch these is opening another terminal, navigate to the project directory and enable your virtual python environment. Set up at least the PYTHONPATH, FLASK_APP and FLASK_ENV environment variables (and if non-default RQ_REDIS_URL). Once the environment established, launch these processes with either:

For a PyPI-based instance or

orcidhub rq scheduler & orcidhub rq worker --logging_level info

For a source-based instance.

./flask.sh rq scheduler & ./flask.sh rq worker --logging_level info

In either case this terminal should now report the birth of the worker process, and a fully functioning test Hub should now be being served.

Shibboleth installation and SP Creation¶

First install Shibboleth. For Ubuntu machine follow the below steps:

sudo apt-get install shibboleth-sp2-schemas libapache2-mod-shib2
sudo apt-get update
sudo a2enmod shib2
sudo service apache2 restart

Modify /etc/hosts file to allow url that you decided to go with, Basically add SP URL (your sp.example.org).
Follow documentation given at below link: https://tuakiri.ac.nz/confluence/display/Tuakiri/Installing+Shibboleth+SP+on+RedHat+based+Linux. Primarily the documentation given under Federation Membership and Configuration sections.

(We already have a SP registered for ORCIDHUB with name: https://test.orcidhub.org.nz at https://registry.test.tuakiri.ac.nz/federationregistry)

You also have to generate certificate to paste in New SP request, which can be done by below sample command:

sudo /usr/sbin/shib-keygen -f -u ubuntu -g ubuntu -h ubuntu.auckland.ac.nz -e http://ubuntu.auckland.ac.nz/shibboleth

Steps to enable https (if in case your require). Command for generating self-singed certificate:

openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout orcid.key -out orcid.crt

then copy both the generated certificates into /etc/apache2/sites-available (you can copy that those to anywhere). Just have to update file with name default-ssl.conf:
SSLCertificateFile /etc/apache2/sites-available/orcid.crt
SSLCertificateKeyFile /etc/apache2/sites-available/orcid.key

sudo a2enmod ssl
sudo service apache2 restart

Enable proxy mode’s in apache2 mod-enable folder so that apache can talk to your local server::
```
a2enmod proxy_http and a2enmod proxy
```

Download the metadata signing certificate for the federation metadata into /etc/shibboleth::

wget https://directory.test.tuakiri.ac.nz/metadata/tuakiri-test-metadata-cert.pem -O /etc/shibboleth/tuakiri-test-metadata-cert.pem

The Shibboleth SP installation needs to be configured to map attributes received from the IdP - in /etc/shibboleth/attribute-map.xml. Change the attribute mapping definition by either editing the file and uncommenting attributes to be accepted, or replace the file with the recommended Tuakiri attribute-map.xml file mapping all Tuakiri attributes (and optionally comment out those attributes not used by your SP).
Check if shibboleth 2.xml and apache 2.conf are configured correctly.

Customising your email messages¶

UI Changes Since V2¶

“Your organisation” has been replaced with “Settings”, and underneath the new “Settings” dropdown you can now find:

“Your organisation”
“Logo”, and
“Email template”

Any .jpg or .png can be uploaded by selecting “Logo” and using the options on the resulting page. If you’re prepared to put some effort into altering your email template then the options are very open, but for the simplest substitution please start with a picture that’s 127 pixels high as it’ll will drop right into the space occupied by the default Society logo.

Next from the “Email template” page you are given the option of toggling the “Email template enabled” option.

Once enabled, a blank document is opened where you can enter the html for the mail that the Hub sends on your behalf.

As that might be a little daunting, to start with (and perhaps doing all that you require) press the “Prefill” button to copy the default html for the Hub’s messages and edit from there.

There are three merged fields that may be of use:

{EMAIL}: Recipient email address
{LOGO}: Organisation logo
{MESSAGE}: Core message that will be sent to the recipient

The {MESSAGE} field is customised for each type of mail that the Hub sends, e.g., invitation, affiliation invite, funding invite, reminders and revoked permission repeat request. If you don’t include this in the template the Hub will send the same message in all instances.

When you think you’ve got something that works, pressing “Send” will email you a test message with the current template. If that’s what you want, press save and any subsequent messages will be style with your new template.

If you ever want to go back to the default Society-style, just toggle off “Email template enabled”.

Writing affiliation items¶

The task of writing affiliations is intended to be easy, i.e.,

a batch file containing information to be written to ORCID records, together with the email or ORCID iD of the researcher/contributors to be affected, is uploaded to the Hub.
the Hub then either sends the people identified email invitations and/or uses the access tokens it already has to write the information to their ORCID records.

As the structure of affiliations in the ORCID Message Schema is relatively simple, this information can be conveyed in csv or tsv formatted files with the Hub accepting either. The file should be constructed with the first row containing only headers, with the following headers recognized:

Required¶

Header	Description
Affiliation type	A value to indicate whether to write the affiliation to education or employment (“staff” or “student”).
Email	The institutional email for the individual, and where the invitation will be sent if they’re not already known in the Hub for your organisation.
First name	If the user does not have an ORCID iD, this field together with ‘Last name’ and email, will be used to pre-fill creation of an ORCID record.
Last name

Optional¶

Header	Description
Identifier	This can be any identifier used in your internal systems and is to allow you to match the resulting put-code from ORCID. To simplify making an update to the item in the future.
ORCID iD	Once it has been authenticated, an ORCID iD can be used instead of an email address; however, without an email address any invitation required cannot be sent.
Organisation	The organisation of the affiliation. NB you should only write affiliations for organisations that know to be true.
Department	Where appropriate, the name of the department in the the organisation.
City	The city of the department or organisation.
Region	Where appropriate, the region (e.g. state)
Course or Title	For an education item, the course of study or degree name; for an employment item, the name of the role or a job title.
Start date	The affiliation’s start date in ISO 8601 format to desired/known level of precision.
End date	The affiliation end date in ISO 8601 format, leave blank or omit for ongoing affiliations.
Country	Two-letter country code in ISO 3166-1 alpha-2 format and only necessary if different to your home campus’s country code.
Disambiguated ID	If different to your home campus’s ID, the identifier for the organisation as given by the accompanying Disambiguation Source.
Disambiguation Source	Required if a Disambiguated ID is provided, and must be one of: RINGGOLD; FUNDREF; or GRID.

Headers that aren’t controlled by you¶

Header	Description
Put-Code	This is an integer that ORCID creates to identify the item and its place in the ORCID record. It is returned to you in the Hub’s affiliation report.
Visibility	Ignored if included when writing the affiliation, but returned to you in the Hub’s affiliation report as is specified by the ORCID record holder.

With a put-code the Hub attempts to overwrite an item; while without one, a new item is created together with a new put-code that is unique within the ORCID record and section, i.e., it is possible for different ORCID records to have the same put-code for different items, and even, in rare cases, for items in differnt sections of the same ORCID record (e.g. employment and education) to have the same put-code.

Notes¶

Each record in the the affiliation file must contain either an email address or, if an individual has already gone through the Hub, an ORCID iD. Dates are preferred in ISO 8601 format, i.e., YYYY-MM-DD with partial dates accepted, e.g, “2017”, “2017-12”, and “2017-12-15” are all valid; however, the Hub will try to interpret any dates provided.

Where a field header or value is not provided, the value from your organisation will be used if it’s available, e.g., Organisation, City, Country, Disambiguation ID, and Disambiguation Source can be omitted where redundant. This is why the Hub can write affilations without you specifying the fields that ORCID requires for the message, i.e., organization, city and country.

NB as Excel’s csv format will silently corrupt any unicode (e.g., vowels with macrons), the tsv format is recommended for those creating their files out of Excel. The easiest way to get a unicode .tsv file from Excel is to “Save As” type “Unicode Text (*.txt)” and then rename the file’s suffix to “.tsv”.

Example files can be found here: Example affiliation task in csv and Example affiliation task in tsv.

Example affiliation task in csv¶

Identifier,First name,Last name,email address,affiliation type,ORCID iD,organisation,department,City,Region,Country,Course/Title,Start Date,End date,Put-Code
0001,Alice,Contributor 1,contributor1@mailinator.com,staff,,Home Organisation,Home Department,Ingoa Wāhi,,NZ,Professor,2018-06-01,,
0002,Alice,Contributor 1,contributor1@mailinator.com,student,,Different Organisation,Different Department,,Placename,NZ,Studying,2016,2017-12,
0003,Bob,Contributor 2,contributor2@mailinator.com,student,,Different Organisation,Different Department,,Placename,NZ,Studying,2016,2018,

You can download example_affiliations.csv here.

Example affiliation task in tsv¶

Identifier,First name,Last name,email address,affiliation type,ORCID iD,organisation,department,City,Region,Country,Course/Title,Start Date,End date,Put-Code
0001,Alice,Contributor 1,contributor1@mailinator.com,staff,,Home Organisation,Home Department,Ingoa Wāhi,,NZ,Professor,2018-06-01,,
0002,Alice,Contributor 1,contributor1@mailinator.com,student,,Different Organisation,Different Department,,Placename,NZ,Studying,2016,2017-12,
0003,Bob,Contributor 2,contributor2@mailinator.com,student,,Different Organisation,Different Department,,Placename,NZ,Studying,2016,2018,

You can download example_affiliations.tsv here.

Writing funding items¶

The task of writing funding is very similar to writing affiliations, i.e.,

a batch file containing information to be written to ORCID records, together with the email or ORCID iD of the researcher/contributors to be affected, is uploaded to the Hub.
the Hub then either sends the people identified email invitations and/or uses the access tokens it already has to write the information to their ORCID records.

The main difference in writing funding is that while affiliation files are simple and can thus be given as either csv or tsv format, funding items in ORCID are more complex requiring a structured file format such as the json or YAML formats to convey. The Hub accepts batches of funding items where each item contains an initial invitees block (detailing the names, email, and optionally ORCID iD and put-code for each individual to be affected) and following that invitee block, the data to be written to each invitee’s ORCID record. The funding data must comply with the structure of the ORCID V2.0/V2.1 funding schema, but omit put-code. If the task describes an update to existing information in a users ORCID record the put-code will not apply to all invitees; instead specify each put-code in the data of the relevant invitee:

[{"invitees":[{invitee1}, {invitee2}, ...], funding},{"invitees":[{invitee4}, {invitee5}, ...], funding2}, ...]

Example files can be found here: Example funding task in json and Example funding task in yaml, while any uploaded funding file will be validated against the funding_schema.yaml.

For more information and guidance on the structure expected of funding task files see here: Funding schema for ORCID API 2.0/2.1

Example funding task in json¶

[{
		"invitees": [
			{"identifier": "00001", "email": "contributor1@mailinator.com", "first-name": "Alice", "last-name": "Contributor 1", "ORCID-iD": "0000-0002-9207-4933", "put-code": null, "visibility": "PRIVATE"}, 
			{"identifier": "00002", "email": "contributor2@mailinator.com", "first-name": "Bob", "last-name": "Contributor 2", "ORCID-iD": null, "put-code": null, "visibility":null}, 
			{"identifier": "00003", "email": "contributor3@mailinator.com", "first-name": "Eve", "last-name": "Contributor 3", "ORCID-iD": null, "put-code": null, "visibility":null}
		],
		"amount": {"currency-code": "NZD", "value": "300000"},
		"organization-defined-type": {"value": "Fast-Start"},
		"organization": {
			"disambiguated-organization": {
				"disambiguated-organization-identifier": "http://dx.doi.org/10.13039/501100009193",
				"disambiguation-source": "FUNDREF"
			},
			"name": "Marsden Fund",
			"address": {"city": "Wellington", "country": "NZ"}
		},
		"contributors": {
			"contributor": [{
					"contributor-attributes": {"contributor-role": "lead"},
					"credit-name": {"value": "Associate Professor A Contributor 1"},
					"contributor-orcid": {
						"uri": "https://sandbox.orcid.org/0000-0002-9207-4933",
						"path": "0000-0002-9207-4933",
						"host": "sandbox.orcid.org"
					}
				}, {
					"contributor-attributes": {"contributor-role": "co_lead"},
					"credit-name": {"value": "Dr B Contributor 2"}
				}, {
					"contributor-attributes": {"contributor-role": ""},
					"credit-name": {"value": "Dr E Contributor 3"}
				}
			]
		},
		"title": {"title": {"value": "This is the project title"}},
		"short-description": "This is the project abstract",
		"end-date": {"year": {"value": "2021"}},
		"start-date": {"year": {"value": "2018"}},
		"type": "CONTRACT",
		"external-ids": {"external-id": [
      {"external-id-value": "XXX1701", "external-id-relationship": "SELF", "external-id-type": "grant_number"}
    ]}
}, 
 {
		"invitees": [
      {"identifier": "00004", "email": "contributor4@mailinator.com", "first-name": "Felix", "last-name": "Contributor 4", "ORCID-iD": null, "put-code": null, "visibility":null}
		],
		"amount": {"currency-code": "NZD", "value": "800000"},
		"organization-defined-type": {"value": "Standard"},
		"organization": {
			"disambiguated-organization": {
				"disambiguated-organization-identifier": "http://dx.doi.org/10.13039/501100009193",
				"disambiguation-source": "FUNDREF"
			},
			"name": "Marsden Fund",
			"address": {"city": "Wellington","country": "NZ"}},
		"contributors": {
			"contributor": [{
					"contributor-attributes": {"contributor-role": "lead"},
					"credit-name": {"value": "Associate Professor F Contributor 4"},
					"contributor-email": {"value": "contributor4@mailinator.com"}
				}
			]
		},
		"title": {"title": {"value": "This is another project title"}},
		"short-description": "This is another project abstract",
		"end-date": {"year": {"value": "2021"}},
		"start-date": {"year": {"value": "2018"}},
		"type": "CONTRACT",
		"external-ids": {
			"external-id": [
        {"external-id-value": "XXX1702", "external-id-relationship": "SELF", "external-id-type": "grant_number"}
			]
		}
	}
]

You can download example_fundings.json here.

Example funding task in yaml¶

---
- invitees:
  - identifier: '00001'
    email: contributor1@mailinator.com
    first-name: Alice
    last-name: Contributor 1
    ORCID-iD: 0000-0002-9207-4933
    put-code: null
    visibility: 'PUBLIC'
  - identifier: '00002'
    email: contributor2@mailinator.com
    first-name: Bob
    last-name: Contributor 2
    ORCID-iD: null
    put-code: null
    visibility: null
  - identifier: '00003'
    email: contributor3@mailinator.com
    first-name: Eve
    last-name: Contributor 3
    ORCID-iD: null
    put-code: null
    visibility: null
  amount:
    currency-code: NZD
    value: '300000'
  organization-defined-type:
    value: Fast-Start
  organization:
    disambiguated-organization:
      disambiguated-organization-identifier: http://dx.doi.org/10.13039/501100009193
      disambiguation-source: FUNDREF
    name: Marsden Fund
    address:
      city: Wellington
      country: NZ
  contributors:
    contributor:
    - contributor-attributes:
        contributor-role: lead
      credit-name:
        value: Associate Professor A Contributor 1
      contributor-orcid:
        uri: https://sandbox.orcid.org/0000-0002-9207-4933
        path: 0000-0002-9207-4933
        host: sandbox.orcid.org
    - contributor-attributes:
        contributor-role: co_lead
      credit-name:
        value: Dr B Contributor 2
    - contributor-attributes:
        contributor-role: ''
      credit-name:
        value: Dr E Contributor 3
  title:
    title:
      value: This is the project title
  short-description: This is the project abstract
  end-date:
    year:
      value: '2021'
  start-date:
    year:
      value: '2018'
  type: CONTRACT
  external-ids:
    external-id:
    - external-id-value: XXX1701
      external-id-relationship: SELF
      external-id-type: grant_number
- invitees:
  - identifier: '00004'
    email: contributor4@mailinator.com
    first-name: Felix
    last-name: Contributor 4
    ORCID-iD: null
    put-code: null
    visibility: null
  amount:
    currency-code: NZD
    value: '800000'
  organization-defined-type:
    value: Standard
  organization:
    disambiguated-organization:
      disambiguated-organization-identifier: http://dx.doi.org/10.13039/501100009193
      disambiguation-source: FUNDREF
    name: Marsden Fund
    address:
      city: Wellington
      country: NZ
  contributors:
    contributor:
    - contributor-attributes:
        contributor-role: lead
      credit-name:
        value: Associate Professor F Contributor 4
  title:
    title:
      value: This is another project title
  short-description: This is another project abstract
  end-date:
    year:
      value: '2021'
  start-date:
    year:
      value: '2018'
  type: CONTRACT
  external-ids:
    external-id:
    - external-id-value: XXX1702
      external-id-relationship: SELF
      external-id-type: grant_number

You can download example_fundings.yaml here.

funding_schema.yaml¶

Any funding task file that is uploaded is first validated against the funding_schema.yaml

You can download funding_schema.yaml here.

Batch funding schema in the NZ ORCID Hub for ORCID Message Schema v2.0/v2.1¶

Batch funding files to be passed through the Hub must be presented in either of the json or YAML formats, with the files following the convention for complex Hub objects, i.e.:

a list of items
- with each item comprised of:
  - a list of invitees (i.e., the individuals whose ORCID records are to be affected); and,
  - the ORCID Message data that is to be asserted to each invitee’s ORCID record

Examples can be found here: **fundings.json** and **fundings.yaml**

The Hub will consume any json or YAML file complying to the following schema. NB additional validation will be performed when the data is sent to ORCID, and any errors in the message will be reported in the item’s status field in the Hub’s UI or task report.

Fundings¶

Properties¶

Type	Description	Notes
list[funding]	Container for the funding item(s) to be written	[required]

Funding¶

Minimum one - maximum unbounded

Properties¶

Name	Type	Description	Notes
invitees	list[invitee]	Container for individuals to be affected	[required]
created-date	CreatedDate	Container for work item’s creation date	[optional, ignored]
last-modified-date	LastModifiedDate	Container for work item’s last modification date	[optional, ignored]
source	Source	Container for when/how the item was asserted	[optional, ignored]
organization	Organization	Container for elements describing the organization which awarded the funding	[required]
title	FundingTitle	Container for the title(s) of the award/project	[required]
short-description	str	An element for a few sentences describing the award/project, e.g., an abstract.	[optional]
amount	Amount	Container for the value and currentcy of the award/project	[optional]
type	str	The type of funding	“AWARD”, “CONTRACT”, “GRANT” or “SALARY-AWARD” [required]
organization_defined_type	FundingSubType	Container for the organisation’s category of funding	[optional]
start-date	StartDate	The date the funding began, given to any level of specificity	[optional]
end-date	EndDate	The date the funding ended or will end, given to any level of specificity	[optional]
external-ids	list[external-id]	A non-repeatable container for identifiers of the funding	[optional]
url	Url	A link to the funding or funding output (appears in the user interface under “Alternate URL”)	[optional]
contributors	FundingContributors	Container for information about the recipients of the funding	[optional]

**back to Fundings**

Invitee¶

Minimum one - maximum unbounded

Properties¶

Name	Type	Description	Notes
identifier	str	Internal identifier from your system for the funding-person relationship	[optional]
first-name	str	First name to assist ORCID iD registration	[required]
last-name	str	Last name to assist ORCID iD registration	[required]
email	str	The email address any permissions request will be sent to	[required unless Hub-known ORCID-iD present]
ORCID-iD	str	ORCID path (16-character identifier) of the ORCID iD	[optional unless no email]
put-code	int	If present the Hub will attempt to update an existing item	[optional]
visibility	str	The privacy level chosen by record holder for this item	“PUBLIC”, “LIMITED” or “PRIVATE” [optional, ignored]

**back to Funding**

CreatedDate and LastModifiedDate¶

NB: Captured automatically by the ORCID Registry

Properties¶

Name	Type	Description	Notes
value	datetime	Milliseconds of the event that have elapsed since midnight 1970-01-01	[optional]

**back to Funding**

Source¶

NB: Captured automatically by the ORCID Registry

Properties¶

Name	Type	Description	Notes
source-orcid	SourceOrcid	For legacy client applications, the ORCID iD that created the item	[optional]
source-client-id	SourceClientId	The client id of the application that created the item	[optional]
source-name	SourceName	Container for the human-readable name of the client application	[optional]

**back to Funding**

SourceOrcid and SourceClientId¶

Properties¶

Name	Type	Description	Notes
uri	str	Source iD in URI form, i.e., URL + path	[optional]
path	str	Application’s 16-character client id or legacy ORCID iD	[optional]
host	str	URL for the environment of the Source iD, i.e., https://sandbox.orcid.org or https://orcid.org	[optional]

**back to Source**

SourceName¶

Properties¶

Name	Type	Description	Notes
value	str	The human-readable name of the client application	[optional]

**back to Source**

Organization¶

Properties¶

Name	Type	Description	Notes
name	str	The human-readable name of the funding organisation	[optional]
address	Address	Container for organization location information	[optional]
disambiguated-organization	DisambiguatedOrganization	A reference to a disambiguated version the funding organisation	[optional]

**back to Funding**

Address¶

Properties¶

Name	Type	Description	Notes
city	str	The city center of the funding organization	[required]
region	str	Region within the country	[optional]
country	str	The country code of the national center of the funding organization	ISO 3166-1 alpha-2 [required]

**back to Organization**

DisambiguatedOrganization¶

Properties¶

Name	Type	Description	Notes
disambiguated-organization-identifier	str	The disambiguated organization identifier	[required]
disambiguation-source	str	The source providing the disambiguated organization ID	“ISNI”, “RINGGOLD”, “FUNDREF” or “GRID” [required]

**back to Organization**

FundingTitle¶

Properties¶

Name	Type	Description	Notes
title	Title	Container for the main name or title of the award/project	[required]
translated-title	TranslatedTitle	Container for any translations of the award’s/project’s title	[optional]

**back to Funding**

Title and Subtitle¶

Properties¶

Name	Type	Description	Notes
value	str	The main name/title or subtitle of the work	[optional]

**back to FundingTitle**

TranslatedTitle¶

Properties¶

Name	Type	Description	Notes
value	str	The main title of the work or funding translated into another language	[optional]
language-code	str	Two-Four letter language code to identify the language of the translation	[required]

**back to FundingTitle**

Amount¶

Properties¶

Name	Type	Description	Notes
value	str	A numerical value for the amount of funding for the award/project	[optional]
currency-code	str	Three letter currency code to identify the currency the amount is denominated in	[required]

FundingSubType¶

Properties¶

Name	Type	Description	Notes
value	str	The organization’s type for an external identifier	[optional]

**back to Funding**

StartDate and EndDate¶

Properties¶

Name	Type	Description	Notes
year	Year	Container for year value	[required]
month	Month	Container for month value	[optional]
day	Day	Container for day value	[optional]

**back to Funding**

Year, Month and Day¶

Properties¶

Name	Type	Description	Notes
value	str	Date values; Year in YYYY, Month in MM, Day in DD	[optional]

**back to StartDate and EndDate**

ExternalIDs¶

Properties¶

Name	Type	Description	Notes
external-id	list[ExternalID]	Container for external identifiers to the award/project	[optional]

**back to Funding**

ExternalID¶

Properties¶

Name	Type	Description	Notes
external-id-type	str	The type of the given external identifier	see here for supported identifier types [required]
external-id-value	str	A reference to an external identifier to the award/project	[required]
external-id-url	Url	A container for the url value	[optional]
external-id-relationship	str	The relationship of this identifier to the award/project	“SELF” or “PART-OF” [optional]

**back to Funding**

Url¶

Properties¶

Name	Type	Description	Notes
value	str	An external url for the award/project or as specified by an external identifier	[optional]

**back to Funding**

FundingContributors¶

Properties¶

Name	Type	Description	Notes
contributor	list[Contributor]	A container for the award’s/project’s contributors	[optional]

**back to Funding**

Contributor¶

Minimum none - maximum unbounded

Properties¶

Name	Type	Description	Notes
contributor-orcid	ContributorOrcid	A container for the contributor’s ORCID iD	[optional]
credit-name	CreditName	A container for the contributor’s name	[optional]
contributor-email	ContributorEmail	A container for the contributor’s email	[deprecated]
contributor-attributes	ContributorAttributes	A container for the contributor’s role and order	[optional]

**back to FundingContributors**

ContributorOrcid¶

Properties¶

Name	Type	Description	Notes
uri	str	ORCID iD in URI form, i.e., URL + path	[preferred, at least one of uri or path must be given]
path	str	16-character ORCID iD	[optional]
host	str	URL for the environment of the ORCID iD, i.e., https://sandbox.orcid.org or https://orcid.org	[optional]

**back to Contributor**

Credit-Name¶

Properties¶

Name	Type	Description	Notes
value	str	The name to use for the researcher or contributor when credited or cited	[optional]

**back to Contributor**

Contributor-Email¶

Properties¶

Name	Type	Description	Notes
value	str	Email of the collaborator or other contributor	[Always private; deprecated do not use]

**back to Contributor**

ContributorAttributes¶

Properties¶

Name	Type	Description	Notes
contributor-role	str	The role performed by this contributor	“LEAD”, “CO-LEAD”, “SUPPORTED-BY” or “OTHER-CONTRIBUTION” [optional]

**back to Contributor**

See the ORCID V2.1 message schema for funding for further explanation of what funding attributes and values ORCID accepts, and what they’re intended to convey

Writing works items¶

The task of writing works is very similar to writing affiliations, i.e.,

a batch file containing information to be written to ORCID records, together with the email or ORCID iD of the researcher/contributors to be affected, is uploaded to the Hub.
the Hub then either sends the people identified email invitations and/or uses the access tokens it already has to write the information to their ORCID records.

The main difference in writing works is that while affiliation files are simple and can thus be given as either csv or tsv format, works in ORCID are more complex requiring a structured file format such as the json or YAML formats to convey. The Hub accepts batches of works items where each item contains an initial invitees block (detailing the names, email, and optionally ORCID iD and put-code for each individual to be affected) and following that invitee block, the data to be written to each invitee’s ORCID record. The work data must comply with the structure of the ORCID V2.0/V2.1 works schema, but omit put-code. If the task describes an update to existing information in a users ORCID record the put-code will not apply to all invitees; instead specify each put-code in the data of the relevant invitee:

[{"invitees":[{invitee1}, {invitee2}, ...], work},{"invitees":[{invitee4}, {invitee5}, ...], work2}, ...]

Example files can be found here: Example works task in json and Example works task in yaml, while any uploaded works file will be validated against the work_schema.yaml.

For more information and guidance on the structure expected of works task files see here: Works schema for ORCID API 2.0/2.1

Example works task in json¶

[
	{
		"invitees": [
			{"identifier": "00001", "email": "contributor1@mailinator.com", "first-name": "Alice", "last-name": "Contributor 1", "ORCID-iD": "0000-0002-9207-4933", "put-code": null, "visibility": null},
			{"identifier": "00002", "email": "contributor2@mailinator.com", "first-name": "Bob", "last-name": "Contributor 2", "ORCID-iD": null, "put-code": null, "visibility": null}
		],
		"path": null,
		"title": {
			"title": {"value": "This is a title"},
			"subtitle": null,
			"translated-title": {"value": "हिंदी","language-code": "hi"}
		},
		"journal-title": {"value": "This is a journal title"},
		"short-description": "xyz this is short description",
		"citation": {"citation-type": "FORMATTED_UNSPECIFIED", "citation-value": "This is citation value"},
		"type": "BOOK_CHAPTER",
		"publication-date": {
			"year": {"value": "2001"},
			"month": {"value": "1"},
			"day": {"value": "12"},
			"media-type": null
		},
		"external-ids": {
			"external-id": [{
					"external-id-type": "bibcode",
					"external-id-value": "sdsds",
					"external-id-url": {"value": "http://url.edu/abs/ghjghghj"},
					"external-id-relationship": "SELF"
				}
			]
		},
		"url": null,
		"contributors": {
			"contributor": [
				{"contributor-attributes": {"contributor-sequence": "FIRST", "contributor-role": "AUTHOR"},
					"credit-name": {"value": "Associate Professor Alice"},
					"contributor-orcid": {
						"uri": "https://sandbox.orcid.org/0000-0002-9207-4933",
						"path": "0000-0002-9207-4933",
						"host": "sandbox.orcid.org"
					}
				},
				{"contributor-attributes": {"contributor-sequence": "ADDITIONAL", "contributor-role": "AUTHOR"},
					"credit-name": {"value": "Dr Bob"}
				}
			]
		},
		"language-code": "en",
		"country": {"value": "NZ"}
	}
]

You can download example_works.json here.

Example works task in yaml¶

---
- invitees:
  - identifier: '00001'
    email: contributor1@mailinator.com
    first-name: Alice
    last-name: Contributor 1
    ORCID-iD: null
    put-code: null
    visibility: null
  - identifier: '00002'
    email: contributor2@mailinator.com
    first-name: Bob
    last-name: Contributor 2
    ORCID-iD: null
    put-code: null
    visibility: null
  title:
    title:
      value: This is a title
    subtitle: 
    translated-title:
      value: हिंदी
      language-code: hi
  journal-title:
    value: This is a journal title
  short-description: xyz this is short description
  citation:
    citation-type: FORMATTED_UNSPECIFIED
    citation-value: This is citation value
  type: BOOK_CHAPTER
  publication-date:
    year:
      value: '2001'
    month:
      value: '1'
    day:
      value: '12'
    media-type: 
  external-ids:
    external-id:
    - external-id-type: bibcode
      external-id-value: sdsds
      external-id-url:
        value: http://url.edu/abs/ghjghghj
      external-id-relationship: SELF
  url: 
  contributors:
    contributor:
    - contributor-attributes:
        contributor-sequence: 'FIRST'
        contributor-role: AUTHOR
      credit-name:
        value: Associate Professor Alice
      contributor-email:
        value: alice.333456@mailinator.com
      contributor-orcid:
        uri: https://sandbox.orcid.org/0000-0002-9207-4933
        path: 0000-0002-9207-4933
        host: sandbox.orcid.org
    - contributor-attributes:
        contributor-sequence: 'ADDITIONAL'
        contributor-role: AUTHOR
      credit-name:
        value: Dr Bob
  language-code: en
  country:
    value: NZ

You can download example_works.yaml here.

work_schema.yaml¶

Any works task file that is uploaded is first validated against the work_schema.yaml

You can download work_schema.yaml here.

Batch works schema in the NZ ORCID Hub for ORCID Message Schema v2.0/v2.1¶

Batch works files to be passed through the Hub must be presented in either of the json or YAML formats, with the files following the convention for complex Hub objects, i.e.:

a list of items
- with each item comprised of:
  - a list of invitees (i.e., the individuals whose ORCID records are to be affected); and,
  - the ORCID Message data that is to be asserted to each invitee’s ORCID record

Examples can be found here: **works.json** and **works.yaml**

The Hub will consume any json or YAML file complying to the following schema. NB additional validation will be performed when the data is sent to ORCID, and any errors in the message will be reported in the item’s status field in the Hub’s UI or task report.

Works¶

Properties¶

Type	Description	Notes
list[work]	Container for the works to be written	[required]

Work¶

Minimum one - maximum unbounded

Properties¶

Name	Type	Description	Notes
invitees	list[invitee]	Container for individuals to be affected	[required]
created-date	CreatedDate	Container for work item’s creation date	[optional, ignored]
last-modified-date	LastModifiedDate	Container for work item’s last modification date	[optional, ignored]
source	Source	Container for when/how the item was asserted	[optional, ignored]
title	WorkTitle	Container for the title(s) of the work	[required]
journal-title	JournalTitle	Container for the title of the publication or group under which the work was published/presented	[optional]
short-description	str	An element for a few sentences describing the work, e.g., an abstract.	[optional]
citation	Citation	Container for a work citation	[optional]
type	str	The work’s type, see here for the 38 allowed types	[required]
publication-date	PublicationDate	Container for the date(s) the work was available to the public	[optional]
external-ids	list[external-id]	Container for the unique IDs of the work	[optional]
url	Url	A container for the url representation of the work	[optional]
contributors	WorkContributors	Container for the contributors of the work	[optional]
language-code	str	Two-Four letter language code to identify the language used in work fields	[optional]
country	Country	Container to identify the work’s original country of publication/presentation	[optional]

**back to Works**

Invitee¶

Minimum one - maximum unbounded

Properties¶

Name	Type	Description	Notes
identifier	str	Internal identifier from your system for the work-person relationship	[optional]
first-name	str	First name to assist ORCID iD registration	[required]
last-name	str	Last name to assist ORCID iD registration	[required]
email	str	The email address any permissions request will be sent to	[required unless Hub-known ORCID-iD present]
ORCID-iD	str	ORCID path (16-character identifier) of the ORCID iD	[optional unless no email]
put-code	int	If present the Hub will attempt to update an existing item	[optional]
visibility	str	The privacy level chosen by record holder for this item	“PUBLIC”, “LIMITED” or “PRIVATE” [optional, ignored]

**back to Work**

CreatedDate and LastModifiedDate¶

NB: Captured automatically by the ORCID Registry

Properties¶

Name	Type	Description	Notes
value	datetime	Milliseconds of the event that have elapsed since midnight 1970-01-01; Created automatically by the ORCID Registry	[optional]

**back to Work**

Source¶

NB: Captured automatically by the ORCID Registry

Properties¶

Name	Type	Description	Notes
source-orcid	SourceOrcid	For legacy client applications, the ORCID iD that created the item	[optional]
source-client-id	SourceClientId	The client id of the application that created the item	[optional]
source-name	SourceName	Container for the human-readable name of the client application	[optional]

**back to Work**

SourceOrcid and SourceClientId¶

Properties¶

Name	Type	Description	Notes
uri	str	Source iD in URI form, i.e., URL + path	[optional]
path	str	Application’s 16-character client id or legacy ORCID iD	[optional]
host	str	URL for the environment of the Source iD, i.e., https://sandbox.orcid.org or https://orcid.org	[optional]

**back to Source**

SourceName¶

Properties¶

Name	Type	Description	Notes
value	str	The human-readable name of the client application	[optional]

**back to Source**

WorkTitle¶

Properties¶

Name	Type	Description	Notes
title	Title	Container for the main name or title of the work	[required]
subtitle	Subtitle	Container for any subtitle to the work	[optional]
translated-title	TranslatedTitle	Container for any translations of the work’s title	[optional]

**back to Work**

Title and Subtitle¶

Properties¶

Name	Type	Description	Notes
value	str	The main name/title or subtitle of the work	[optional]

**back to WorkTitle**

TranslatedTitle¶

Properties¶

Name	Type	Description	Notes
value	str	The main title of the work or funding translated into another language	[optional]
language-code	str	Two-Four letter language code to identify the language of the translation	[optional]

**back to WorkTitle**

JournalTitle¶

Properties¶

Name	Type	Description	Notes
value	str	The title/conference name of the publication, event or group under which the work appeared	[optional]

**back to Work**

Citation¶

Properties¶

Name	Type	Description	Notes
citation-type	str	The type (format) of the citation.	“BIBTEX”, “FORMATTED-APA”, “FORMATTED-CHICAGO”, “FORMATTED-HARVARD”, “FORMATTED-IEEE”, “FORMATTED-MLA”, “FORMATTED-UNSPECIFIED”, “FORMATTED-VANCOUVER” OR “RIS” [required, “BIBTEX” preferred]
citation-value	str	The citation formatted in the given citation type	[required]

PublicationDate¶

Properties¶

Name	Type	Description	Notes
year	Year	Container for year value	[required]
month	Month	Container for month value	[optional]
day	Day	Container for day value	[optional]
media-type	str	to indicate which version of the publication the date refers to	[optional]

**back to Work**

Year, Month and Day¶

Properties¶

Name	Type	Description	Notes
value	str	Date values; Year in YYYY, Month in MM, Day in DD	[optional]

**back to PublicationDate**

ExternalID¶

Properties¶

Name	Type	Description	Notes
external-id-type	str	The type of the given external identifier	see here for supported identifier types [required]
external-id-value	str	A reference to an external identifier to the work	[required]
external-id-url	Url	A container for the url value	[optional]
external-id-relationship	str	The relationship of this identifier to the work	“SELF” or “PART-OF” [optional]

**back to Work**

Url¶

Properties¶

Name	Type	Description	Notes
value	str	An external url for the work or as specified by an external identifier	[optional]

**back to Work**

WorkContributors¶

Properties¶

Name	Type	Description	Notes
contributor	list[Contributor]	A container for the work’s contributors	[optional]

**back to Work**

Contributor¶

Minimum none - maximum unbounded

Properties¶

Name	Type	Description	Notes
contributor-orcid	ContributorOrcid	A container for the contributor’s ORCID iD	[optional]
credit-name	CreditName	A container for the contributor’s name	[optional]
contributor-email	ContributorEmail	A container for the contributor’s email	[deprecated]
contributor-attributes	ContributorAttributes	A container for the contributor’s role and order	[optional]

**back to WorkContributors**

ContributorOrcid¶

Properties¶

Name	Type	Description	Notes
uri	str	ORCID iD in URI form, i.e., URL + path	[preferred, at least one of uri or path must be given]
path	str	16-character ORCID iD	[optional]
host	str	URL for the environment of the ORCID iD, i.e., https://sandbox.orcid.org or https://orcid.org	[optional]

**back to Contributor**

Credit-Name¶

Properties¶

Name	Type	Description	Notes
value	str	The name to use for the researcher or contributor when credited or cited	[optional]

**back to Contributor**

Contributor-Email¶

Properties¶

Name	Type	Description	Notes
value	str	Email of the collaborator or other contributor	[Always private; deprecated do not use]

**back to Contributor**

ContributorAttributes¶

Properties¶

Name	Type	Description	Notes
contributor-sequence	str	Indication of where in the contributor list this contributor appears	“FIRST” or “ADDITIONAL” [optional]
contributor-role	str	The role performed by this contributor	“ASSIGNEE”, “AUTHOR”, “CHAIR-OR-TRANSLATOR”, “CO-INVENTOR”, “CO-INVESTIGATOR”, “EDITOR”, “GRADUATE-STUDENT”, “OTHER-INVENTOR”, “POSTDOCTORAL-RESEARCHER”, “PRINCIPAL-INVESTIGATOR”, or “SUPPORT-STAFF” [optional]

**back to Contributor**

Country¶

Properties¶

Name	Type	Description	Notes
value	str	ISO 3166-1 alpha-2 code for the work’s original country of publication/presentation	[optional]

**back to Work**

See the ORCID V2.1 message schema for works for further explanation of what works attributes and values ORCID accepts, and what they’re intended to convey

Writing peer review items¶

The task of writing peer review is very similar to writing works and funding, i.e.,

a batch file containing information to be written to ORCID records, together with the email or ORCID iD of the researcher/contributors to be affected, is uploaded to the Hub.
the Hub then either sends the people identified email invitations and/or uses the access tokens it already has to write the information to their ORCID records.

As with all complex objects passed through the Hub, peer review requires a structured file format such as the json or YAML formats to convey.

The main difference between peer review and other complex ORCID objects is that to assert peer review requires the pre-registration of a peer review group for the peer review to belong to. As a best practice, you should use existing group IDs (so peer review activity can be grouped on the user’s ORCID record as expected) before creating a new one. To search for the existence of a peer review group requires the use of the ORCID API. Until we’ve built the search feature of the Hub, let us know the group’s name and we’ll () run the search for you.

If you do need to create a new peer review group this can be accomplished from the ‘/Settings/GroupId Record’ page available to Organisation Administrators. Select ‘Create’, and you’ll be able to specify:

Name: The name of the group. This can be the name of a journal (Journal of Criminal Justice), a publisher (Society of Criminal Justice), or non-specific description (Legal Journal) as required. Group ID: The group’s identifier, formatted as type:identifier, e.g. issn:12345678. This can be as specific (e.g. the journal’s ISSN) or vague as required. Valid types include: issn, ringgold, orcid-generated, fundref, publons (contact ORCID if you require a different group ID type) Description: A brief textual description of the group. This can be as specific or vague as required. Type: One of the specified types: publisher; institution; journal; conference; newspaper; newsletter; magazine; peer-review service (contact ORCID if you require a different peer review type)

Once saved, from the ‘/Settings/GroupId Record’ page, select the group you’ve just created and the click ‘With selected’ > ‘Insert or Update record’. As soon as the record shows a put code, the group’s “Group Id” can be referred to in a peer-review file.

NB: you only need to do this once for each peer review group.

The Hub accepts batches of peer review items where each item contains an initial invitees block (detailing the names, email, and optionally ORCID iD and put-code for each individual to be affected) and following that invitee block, the data to be written to each invitee’s ORCID record. The peer review data must comply with the structure of the ORCID V2.0/V2.1 peer review schema, but omit put-code. If the task describes an update to existing information in a users ORCID record the put-code will not apply to all invitees; instead specify each put-code in the data of the relevant invitee:

[{"invitees":[{invitee1}, {invitee2}, ...], peer review},{"invitees":[{invitee4}, {invitee5}, ...], peer review2}, ...]

Example files can be found here: Example peer review task in json and Example peer review task in yaml, while any uploaded peer review file will be validated against the peer_review_schema.yaml.

For more information and guidance on the structure expected of peer review task files see here: Peer review schema for ORCID API 2.0/2.1 For an overview of peer review in ORCID see here: Workflow: Peer Review

Example peer review task in json¶

[{
	"invitees": [
			{"identifier":"00001", "email": "contributor1@mailinator.com", "first-name": "Alice", "last-name": "Contributor 1", "ORCID-iD": "0000-0002-9207-4933", "put-code": null, "visibility": null},
			{"identifier":"00002", "email": "contributor2@mailinator.com", "first-name": "Bob", "last-name": "Contributor 2", "ORCID-iD": null, "put-code": null, "visibility": null}],
	"reviewer-role": "REVIEWER",
	"review-identifiers": {
		"external-id": [{
			"external-id-type": "source-work-id",
			"external-id-value": "1212221",
			"external-id-url": {
				"value": "https://localsystem.org/1234"
			},
			"external-id-relationship": "SELF"
		}]
	},
	"review-url": {
		"value": "https://alt-url.com"
	},
	"review-type": "REVIEW",
	"review-completion-date": {
		"year": {
			"value": "2012"
		},
		"month": {
			"value": "08"
		},
		"day": {
			"value": "01"
		}
	},
	"review-group-id": "issn:12131",
	"subject-external-identifier": {
		"external-id-type": "doi",
		"external-id-value": "10.1087/20120404",
		"external-id-url": {
			"value": "https://doi.org/10.1087/20120404"
		},
		"external-id-relationship": "SELF"
	},
	"subject-container-name": {
		"value": "Journal title"
	},
	"subject-type": "JOURNAL_ARTICLE",
	"subject-name": {
		"title": {
			"value": "Name of the paper reviewed"
		},
		"subtitle": {
			"value": "Subtitle of the paper reviewed"
		},
		"translated-title": {
			"language-code": "en",
			"value": "Translated title"
		}
	},
	"subject-url": {
		"value": "https://subject-alt-url.com"
	},
	"convening-organization": {
		"name": "The University of Auckland",
		"address": {
			"city": "Auckland",
			"region": "Auckland",
			"country": "NZ"
		},
		"disambiguated-organization": {
			"disambiguated-organization-identifier": "385488",
			"disambiguation-source": "RINGGOLD"
		}
	}
}]

You can download example_peer_reviews.json here.

Example peer review task in yaml¶

---
- invitees:
  - identifier: '00001'
    email: contributor1@mailinator.com
    first-name: Alice
    last-name: Contributor 1
    ORCID-iD: 0000-0002-9207-4933
    put-code: null
    visibility: null
  - identifier: '00002'
    email: contributor2@mailinator.com
    first-name: Bob
    last-name: Contributor 2
    ORCID-iD: null
    put-code: null
    visibility: null
  reviewer-role: REVIEWER
  review-identifiers:
    external-id:
    - external-id-type: source-work-id
      external-id-value: '1212221'
      external-id-url:
        value: https://localsystem.org/1234
      external-id-relationship: SELF
  review-url:
    value: https://alt-url.com
  review-type: REVIEW
  review-completion-date:
    year:
      value: '2012'
    month:
      value: '08'
    day:
      value: '01'
  review-group-id: ringgold:9999999999
  subject-container-name:
    value: Journal title
  subject-external-identifier:
    external-id-type: doi
    external-id-value: 10.1087/20120404
    external-id-url:
      value: https://doi.org/10.1087/20120404
    external-id-relationship: SELF
  subject-type: JOURNAL_ARTICLE
  subject-name:
    title:
      value: Name of the paper reviewed
    subtitle: 
      value: Subtitle of the paper reviewed
    translated-title: 
      language-code: en
      value: Translated title
  subject-url: 
    value: https://subject-alt-url.com
  convening-organization:
    name: The University of Auckland
    address:
      city: Auckland
      country: NZ
    disambiguated-organization:
      disambiguated-organization-identifier: '385488'
      disambiguation-source: RINGGOLD

You can download example_peer_reviews.yaml here.

peer_review_schema.yaml¶

Any peer review task file that is uploaded is first validates against the current peer_review_schema.yaml:

You can download peer_review_schema.yaml here.

Batch peer review schema in the NZ ORCID Hub for ORCID Message Schema v2.0/v2.1¶

Batch peer review files to be passed through the Hub must be presented in either of the json or YAML formats, with the files following the convention for complex Hub objects, i.e.:

a list of items
- with each item comprised of:
  - a list of invitees (i.e., the individuals whose ORCID records are to be affected); and,
  - the ORCID Message data that is to be asserted to each invitee’s ORCID record

Examples can be found here: **peer_reviews.json** and **peer_reviews.yaml**

A guide to peer review assertion in V2.1 of the ORCID API can be found here ORCID API v2.1 Peer Review Guide

The Hub will consume any json or YAML file complying to the following schema. NB additional validation will be performed when the data is sent to ORCID, and any errors in the message will be reported in the item’s status field in the Hub’s UI or task report.

Peer Reviews¶

Properties¶

Type	Description	Notes
list[peer_review]	Container for the peer review item(s) to be written	[required]

Peer Review¶

Minimum one - maximum unbounded

Properties¶

Name	Type	Description	Notes
invitees	list[invitee]	Container for individuals to be affected	[required]
created-date	CreatedDate	Container for work item’s creation date	[optional, ignored]
last-modified-date	LastModifiedDate	Container for work item’s last modification date	[optional, ignored]
source	Source	Container for when/how the item was asserted	[optional, ignored]
reviewer-role	str	The role played by a person in their contribution to a review	“CHAIR”, “EDITOR”, “MEMBER”, “ORGANIZER” or “REVIEWER” [required]
review-identifiers	list[external-id]	Container for identifiers for the review	Used to group reviews [required]
review-url	Url	Container for a url representation of the review	[optional]
review-type	str	The kind of review applied to the subject type reviewed	“REVIEW” or “EVALUATION” [required]
review-completion-date	ReviewCompletionDate	The date on which the review was completed, given to any level of specificity	[optional]
review-group-id	str	Identifier for the group that this review should be a part of for aggregation purposes.	This review-group-id must be pre-registered [required]
subject-external-identifier	list[external-id]	Container for the unique IDs of the object that was reviewed	[optional]
subject-container-name	SubjectContainerName	Container for the name of the journal, conference, grant review panel, or other applicable object of which the review subject was a part	[optional]
subject-type	str	The object type of the review subject	See here for the 38 allowed types [optional]
subject-name	SubjectName	Container for the name(s) of the object that was reviewed	[optional]
subject-url	Url	Container for a url representation of the object reviewed	[optional]
convening-organization	ConveningOrganization	Container for information about the organization convening the review	[required]

**back to Peer Reviews**

Invitee¶

Minimum one - maximum unbounded

Properties¶

Name	Type	Description	Notes
identifier	str	Internal identifier from your system for the funding-person relationship	[optional]
first-name	str	First name to assist ORCID iD registration	[required]
last-name	str	Last name to assist ORCID iD registration	[required]
email	str	The email address any permissions request will be sent to	[required unless Hub-known ORCID-iD present]
ORCID-iD	str	ORCID path (16-character identifier) of the ORCID iD	[optional unless no email]
put-code	int	If present the Hub will attempt to update an existing item	[optional]
visibility	str	The privacy level chosen by record holder for this item	“PUBLIC”, “LIMITED” or “PRIVATE” [optional, ignored]

**back to Peer Review**

CreatedDate and LastModifiedDate¶

NB: Captured automatically by the ORCID Registry

Properties¶

Name	Type	Description	Notes
value	datetime	Milliseconds of the event that have elapsed since midnight 1970-01-01	[optional]

**back to Peer Review**

Source¶

NB: Captured automatically by the ORCID Registry

Properties¶

Name	Type	Description	Notes
source-orcid	SourceOrcid	For legacy client applications, the ORCID iD that created the item	[optional]
source-client-id	SourceClientId	The client id of the application that created the item	[optional]
source-name	SourceName	Container for the human-readable name of the client application	[optional]

**back to Peer Review**

SourceOrcid and SourceClientId¶

Properties¶

Name	Type	Description	Notes
uri	str	Source iD in URI form, i.e., URL + path	[optional]
path	str	Application’s 16-character client id or legacy ORCID iD	[optional]
host	str	URL for the environment of the Source iD, i.e., https://sandbox.orcid.org or https://orcid.org	[optional]

**back to Source**

SourceName¶

Properties¶

Name	Type	Description	Notes
value	str	The human-readable name of the client application	[optional]

**back to Source**

External ID¶

Properties¶

Name	Type	Description	Notes
external-id-type	str	The type of the given external identifier	see here for supported identifier types [required]
external-id-value	str	A reference to an external identifier to the review/subject	[required]
external-id-url	Url	A container for the url value	[optional]
external-id-relationship	str	The relationship of this identifier to the review/subject	“SELF” or “PART-OF” [optional]

**back to Peer Review**

Url¶

Properties¶

Name	Type	Description	Notes
value	str	An external url for the review/subject or as specified by an external identifier	[optional]

**back to Peer Review**

ReviewCompletionDate¶

Properties¶

Name	Type	Description	Notes
year	Year	Container for year value	[required]
month	Month	Container for month value	[optional]
day	Day	Container for day value	[optional]

**back to Peer Review**

Year, Month and Day¶

Properties¶

Name	Type	Description	Notes
value	str	Date values; Year in YYYY, Month in MM, Day in DD	[optional]

**back to ReviewCompletionDate**

SubjectContainerName¶

Properties¶

Name	Type	Description	Notes
value	str	The title/conference name of the publication, event or group under which the work appeared	[optional]

**back to Peer Review**

SubjectName¶

Properties¶

Name	Type	Description	Notes
title	Title	Container for the main name or title review’s subject	[required]
subtitle	Subtitle	Container for any subtitle to the subject	[optional]
translated-title	TranslatedTitle	Container for any translations of the subject’s title	[optional]

**back to Peer Review**

Title and Subtitle¶

Properties¶

Name	Type	Description	Notes
value	str	The main name/title or subtitle of the subject	[optional]

**back to SubjectName**

TranslatedTitle¶

Properties¶

Name	Type	Description	Notes
value	str	The main title of the subject translated into another language	[optional]
language-code	str	Two-Four letter language code to identify the language of the translation	[required]

**back to SubjectName**

ConveningOrganization¶

Properties¶

Name	Type	Description	Notes
name	str	The human-readable name of the organisation convening the review	[optional]
address	Address	Container for organization location information	[optional]
disambiguated-organization	DisambiguatedOrganization	A reference to a disambiguated version the convening organisation	[optional]

**back to Peer Review**

Address¶

Properties¶

Name	Type	Description	Notes
city	str	The city center of the organization	[required]
region	str	Region within the country	[optional]
country	str	The country code of the national center of the convening organization	ISO 3166-1 alpha-2 [required]

**back to ConveningOrganization**

DisambiguatedOrganization¶

Properties¶

Name	Type	Description	Notes
disambiguated-organization-identifier	str	The disambiguated organization identifier	[required]
disambiguation-source	str	The source providing the disambiguated organization ID	“ISNI”, “RINGGOLD”, “FUNDREF” or “GRID” [required]

**back to ConveningOrganization**

See the ORCID V2.1 message schema for peer review for further explanation of what peer-review attributes and values ORCID accepts, and what they’re intended to convey

swagger_client¶

No description provided (generated by Swagger Codegen https://github.com/swagger-api/swagger-codegen)

This Python package is automatically generated by the Swagger Codegen project:

API version: Latest
Package version: 1.0.0
Build package: io.swagger.codegen.languages.PythonClientCodegen

Requirements.¶

Python 2.7 and 3.4+

Installation & Usage¶

pip install¶

If the python package is hosted on Github, you can install directly from Github

pip install git+https://github.com/GIT_USER_ID/GIT_REPO_ID.git

(you may need to run pip with root permission: sudo pip install git+https://github.com/GIT_USER_ID/GIT_REPO_ID.git)

Then import the package:

import swagger_client

Setuptools¶

Install via Setuptools.

python setup.py install --user

(or sudo python setup.py install to install the package for all users)

Then import the package:

import swagger_client

Getting Started¶

Please follow the installation procedure and then run the following:

from __future__ import print_function
import time
import swagger_client
from swagger_client.rest import ApiException
from pprint import pprint

# Configure OAuth2 access token for authorization: orcid_two_legs
swagger_client.configuration.access_token = 'YOUR_ACCESS_TOKEN'
# create an instance of the API class
api_instance = swagger_client.MemberAPIV20Api()
orcid = 'orcid_example' # str |
body = swagger_client.NotificationPermission() # NotificationPermission |  (optional)

try:
    # Add a notification
    api_response = api_instance.add_permission_notification(orcid, body=body)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling MemberAPIV20Api->add_permission_notification: %s\n" % e)

Documentation for API Endpoints¶

All URIs are relative to https://api.orcid.org

Class	Method	HTTP request	Description
MemberAPIV20Api	add_permission_notification	POST /v2.0/{orcid}/notification-permission	Add a notification
MemberAPIV20Api	create_address	POST /v2.0/{orcid}/address	Add an address
MemberAPIV20Api	create_education	POST /v2.0/{orcid}/education	Create an Education
MemberAPIV20Api	create_employment	POST /v2.0/{orcid}/employment	Create an Employment
MemberAPIV20Api	create_external_identifier	POST /v2.0/{orcid}/external-identifiers	Add external identifier
MemberAPIV20Api	create_funding	POST /v2.0/{orcid}/funding	Create a Funding
MemberAPIV20Api	create_group_id_record	POST /v2.0/group-id-record	Create a Group
MemberAPIV20Api	create_keyword	POST /v2.0/{orcid}/keywords	Add keyword
MemberAPIV20Api	create_other_name	POST /v2.0/{orcid}/other-names	Add other name
MemberAPIV20Api	create_peer_review	POST /v2.0/{orcid}/peer-review	Create a Peer Review
MemberAPIV20Api	create_researcher_url	POST /v2.0/{orcid}/researcher-urls	Add a new researcher url for an ORCID ID
MemberAPIV20Api	create_work	POST /v2.0/{orcid}/work	Create a Work
MemberAPIV20Api	create_works	POST /v2.0/{orcid}/works	Create a listo of Work
MemberAPIV20Api	delete_address	DELETE /v2.0/{orcid}/address/{putCode}	Delete an address
MemberAPIV20Api	delete_education	DELETE /v2.0/{orcid}/education/{putCode}	Delete an Education
MemberAPIV20Api	delete_employment	DELETE /v2.0/{orcid}/employment/{putCode}	Delete an Employment
MemberAPIV20Api	delete_external_identifier	DELETE /v2.0/{orcid}/external-identifiers/{putCode}	Delete external identifier
MemberAPIV20Api	delete_funding	DELETE /v2.0/{orcid}/funding/{putCode}	Delete a Funding
MemberAPIV20Api	delete_group_id_record	DELETE /v2.0/group-id-record/{putCode}	Delete a Group
MemberAPIV20Api	delete_keyword	DELETE /v2.0/{orcid}/keywords/{putCode}	Delete keyword
MemberAPIV20Api	delete_other_name	DELETE /v2.0/{orcid}/other-names/{putCode}	Delete other name
MemberAPIV20Api	delete_peer_review	DELETE /v2.0/{orcid}/peer-review/{putCode}	Delete a Peer Review
MemberAPIV20Api	delete_researcher_url	DELETE /v2.0/{orcid}/researcher-urls/{putCode}	Delete one researcher url from an ORCID ID
MemberAPIV20Api	delete_work	DELETE /v2.0/{orcid}/work/{putCode}	Delete a Work
MemberAPIV20Api	edit_address	PUT /v2.0/{orcid}/address/{putCode}	Edit an address
MemberAPIV20Api	edit_external_identifier	PUT /v2.0/{orcid}/external-identifiers/{putCode}	Edit external identifier
MemberAPIV20Api	edit_keyword	PUT /v2.0/{orcid}/keywords/{putCode}	Edit keyword
MemberAPIV20Api	edit_other_name	PUT /v2.0/{orcid}/other-names/{putCode}	Edit other name
MemberAPIV20Api	edit_researcher_url	PUT /v2.0/{orcid}/researcher-urls/{putCode}	Edits researcher url for an ORCID ID
MemberAPIV20Api	flag_as_archived_permission_notification	DELETE /v2.0/{orcid}/notification-permission/{id}	Archive a notification
MemberAPIV20Api	search_by_query_xml	GET /v2.0/search	Search records
MemberAPIV20Api	update_education	PUT /v2.0/{orcid}/education/{putCode}	Update an Education
MemberAPIV20Api	update_employment	PUT /v2.0/{orcid}/employment/{putCode}	Update an Employment
MemberAPIV20Api	update_funding	PUT /v2.0/{orcid}/funding/{putCode}	Update a Funding
MemberAPIV20Api	update_group_id_record	PUT /v2.0/group-id-record/{putCode}	Update a Group
MemberAPIV20Api	update_peer_review	PUT /v2.0/{orcid}/peer-review/{putCode}	Update a Peer Review
MemberAPIV20Api	update_work	PUT /v2.0/{orcid}/work/{putCode}	Update a Work
MemberAPIV20Api	view_activities	GET /v2.0/{orcid}/activities	Fetch all activities
MemberAPIV20Api	view_address	GET /v2.0/{orcid}/address/{putCode}	Fetch an address
MemberAPIV20Api	view_addresses	GET /v2.0/{orcid}/address	Fetch all addresses of a profile
MemberAPIV20Api	view_biography	GET /v2.0/{orcid}/biography	Get biography details
MemberAPIV20Api	view_client	GET /v2.0/client/{client_id}	Fetch client details
MemberAPIV20Api	view_education	GET /v2.0/{orcid}/education/{putCode}	Fetch an Education
MemberAPIV20Api	view_education_summary	GET /v2.0/{orcid}/education/summary/{putCode}	Fetch an Education summary
MemberAPIV20Api	view_educations	GET /v2.0/{orcid}/educations	Fetch all educations
MemberAPIV20Api	view_emails	GET /v2.0/{orcid}/email	Fetch all emails for an ORCID ID
MemberAPIV20Api	view_employment	GET /v2.0/{orcid}/employment/{putCode}	Fetch an Employment
MemberAPIV20Api	view_employment_summary	GET /v2.0/{orcid}/employment/summary/{putCode}	Fetch an Employment Summary
MemberAPIV20Api	view_employments	GET /v2.0/{orcid}/employments	Fetch all employments
MemberAPIV20Api	view_external_identifier	GET /v2.0/{orcid}/external-identifiers/{putCode}	Fetch external identifier
MemberAPIV20Api	view_external_identifiers	GET /v2.0/{orcid}/external-identifiers	Fetch external identifiers
MemberAPIV20Api	view_funding	GET /v2.0/{orcid}/funding/{putCode}	Fetch a Funding
MemberAPIV20Api	view_funding_summary	GET /v2.0/{orcid}/funding/summary/{putCode}	Fetch a Funding Summary
MemberAPIV20Api	view_fundings	GET /v2.0/{orcid}/fundings	Fetch all fundings
MemberAPIV20Api	view_group_id_record	GET /v2.0/group-id-record/{putCode}	Fetch a Group
MemberAPIV20Api	view_group_id_records	GET /v2.0/group-id-record	Fetch Groups
MemberAPIV20Api	view_keyword	GET /v2.0/{orcid}/keywords/{putCode}	Fetch keyword
MemberAPIV20Api	view_keywords	GET /v2.0/{orcid}/keywords	Fetch keywords
MemberAPIV20Api	view_other_name	GET /v2.0/{orcid}/other-names/{putCode}	Fetch Other name
MemberAPIV20Api	view_other_names	GET /v2.0/{orcid}/other-names	Fetch Other names
MemberAPIV20Api	view_peer_review	GET /v2.0/{orcid}/peer-review/{putCode}	Fetch a Peer Review
MemberAPIV20Api	view_peer_review_summary	GET /v2.0/{orcid}/peer-review/summary/{putCode}	Fetch a Peer Review Summary
MemberAPIV20Api	view_peer_reviews	GET /v2.0/{orcid}/peer-reviews	Fetch all peer reviews
MemberAPIV20Api	view_permission_notification	GET /v2.0/{orcid}/notification-permission/{id}	Fetch a notification by id
MemberAPIV20Api	view_person	GET /v2.0/{orcid}/person	Fetch person details
MemberAPIV20Api	view_personal_details	GET /v2.0/{orcid}/personal-details	Fetch personal details for an ORCID ID
MemberAPIV20Api	view_record	GET /v2.0/{orcid}{ignore}	Fetch record details
MemberAPIV20Api	view_researcher_url	GET /v2.0/{orcid}/researcher-urls/{putCode}	Fetch one researcher url for an ORCID ID
MemberAPIV20Api	view_researcher_urls	GET /v2.0/{orcid}/researcher-urls	Fetch all researcher urls for an ORCID ID
MemberAPIV20Api	view_specified_works	GET /v2.0/{orcid}/works/{putCodes}	Fetch specified works
MemberAPIV20Api	view_work	GET /v2.0/{orcid}/work/{putCode}	Fetch a Work
MemberAPIV20Api	view_work_summary	GET /v2.0/{orcid}/work/summary/{putCode}	Fetch a Work Summary
MemberAPIV20Api	view_works	GET /v2.0/{orcid}/works	Fetch all works
MemberAPIV21Api	add_permission_notification	POST /v2.1/{orcid}/notification-permission	Add a notification
MemberAPIV21Api	create_address	POST /v2.1/{orcid}/address	Add an address
MemberAPIV21Api	create_education	POST /v2.1/{orcid}/education	Create an Education
MemberAPIV21Api	create_employment	POST /v2.1/{orcid}/employment	Create an Employment
MemberAPIV21Api	create_external_identifier	POST /v2.1/{orcid}/external-identifiers	Add external identifier
MemberAPIV21Api	create_funding	POST /v2.1/{orcid}/funding	Create a Funding
MemberAPIV21Api	create_group_id_record	POST /v2.1/group-id-record	Create a Group
MemberAPIV21Api	create_keyword	POST /v2.1/{orcid}/keywords	Add keyword
MemberAPIV21Api	create_other_name	POST /v2.1/{orcid}/other-names	Add other name
MemberAPIV21Api	create_peer_review	POST /v2.1/{orcid}/peer-review	Create a Peer Review
MemberAPIV21Api	create_researcher_url	POST /v2.1/{orcid}/researcher-urls	Add a new researcher url for an ORCID ID
MemberAPIV21Api	create_work	POST /v2.1/{orcid}/work	Create a Work
MemberAPIV21Api	create_works	POST /v2.1/{orcid}/works	Create a listo of Work
MemberAPIV21Api	delete_address	DELETE /v2.1/{orcid}/address/{putCode}	Delete an address
MemberAPIV21Api	delete_education	DELETE /v2.1/{orcid}/education/{putCode}	Delete an Education
MemberAPIV21Api	delete_employment	DELETE /v2.1/{orcid}/employment/{putCode}	Delete an Employment
MemberAPIV21Api	delete_external_identifier	DELETE /v2.1/{orcid}/external-identifiers/{putCode}	Delete external identifier
MemberAPIV21Api	delete_funding	DELETE /v2.1/{orcid}/funding/{putCode}	Delete a Funding
MemberAPIV21Api	delete_group_id_record	DELETE /v2.1/group-id-record/{putCode}	Delete a Group
MemberAPIV21Api	delete_keyword	DELETE /v2.1/{orcid}/keywords/{putCode}	Delete keyword
MemberAPIV21Api	delete_other_name	DELETE /v2.1/{orcid}/other-names/{putCode}	Delete other name
MemberAPIV21Api	delete_peer_review	DELETE /v2.1/{orcid}/peer-review/{putCode}	Delete a Peer Review
MemberAPIV21Api	delete_researcher_url	DELETE /v2.1/{orcid}/researcher-urls/{putCode}	Delete one researcher url from an ORCID ID
MemberAPIV21Api	delete_work	DELETE /v2.1/{orcid}/work/{putCode}	Delete a Work
MemberAPIV21Api	edit_address	PUT /v2.1/{orcid}/address/{putCode}	Edit an address
MemberAPIV21Api	edit_external_identifier	PUT /v2.1/{orcid}/external-identifiers/{putCode}	Edit external identifier
MemberAPIV21Api	edit_keyword	PUT /v2.1/{orcid}/keywords/{putCode}	Edit keyword
MemberAPIV21Api	edit_other_name	PUT /v2.1/{orcid}/other-names/{putCode}	Edit other name
MemberAPIV21Api	edit_researcher_url	PUT /v2.1/{orcid}/researcher-urls/{putCode}	Edits researcher url for an ORCID ID
MemberAPIV21Api	flag_as_archived_permission_notification	DELETE /v2.1/{orcid}/notification-permission/{id}	Archive a notification
MemberAPIV21Api	search_by_query_xml	GET /v2.1/search	Search records
MemberAPIV21Api	update_education	PUT /v2.1/{orcid}/education/{putCode}	Update an Education
MemberAPIV21Api	update_employment	PUT /v2.1/{orcid}/employment/{putCode}	Update an Employment
MemberAPIV21Api	update_funding	PUT /v2.1/{orcid}/funding/{putCode}	Update a Funding
MemberAPIV21Api	update_group_id_record	PUT /v2.1/group-id-record/{putCode}	Update a Group
MemberAPIV21Api	update_peer_review	PUT /v2.1/{orcid}/peer-review/{putCode}	Update a Peer Review
MemberAPIV21Api	update_work	PUT /v2.1/{orcid}/work/{putCode}	Update a Work
MemberAPIV21Api	view_activities	GET /v2.1/{orcid}/activities	Fetch all activities
MemberAPIV21Api	view_address	GET /v2.1/{orcid}/address/{putCode}	Fetch an address
MemberAPIV21Api	view_addresses	GET /v2.1/{orcid}/address	Fetch all addresses of a profile
MemberAPIV21Api	view_biography	GET /v2.1/{orcid}/biography	Get biography details
MemberAPIV21Api	view_client	GET /v2.1/client/{client_id}	Fetch client details
MemberAPIV21Api	view_education	GET /v2.1/{orcid}/education/{putCode}	Fetch an Education
MemberAPIV21Api	view_education_summary	GET /v2.1/{orcid}/education/summary/{putCode}	Fetch an Education summary
MemberAPIV21Api	view_educations	GET /v2.1/{orcid}/educations	Fetch all educations
MemberAPIV21Api	view_emails	GET /v2.1/{orcid}/email	Fetch all emails for an ORCID ID
MemberAPIV21Api	view_employment	GET /v2.1/{orcid}/employment/{putCode}	Fetch an Employment
MemberAPIV21Api	view_employment_summary	GET /v2.1/{orcid}/employment/summary/{putCode}	Fetch an Employment Summary
MemberAPIV21Api	view_employments	GET /v2.1/{orcid}/employments	Fetch all employments
MemberAPIV21Api	view_external_identifier	GET /v2.1/{orcid}/external-identifiers/{putCode}	Fetch external identifier
MemberAPIV21Api	view_external_identifiers	GET /v2.1/{orcid}/external-identifiers	Fetch external identifiers
MemberAPIV21Api	view_funding	GET /v2.1/{orcid}/funding/{putCode}	Fetch a Funding
MemberAPIV21Api	view_funding_summary	GET /v2.1/{orcid}/funding/summary/{putCode}	Fetch a Funding Summary
MemberAPIV21Api	view_fundings	GET /v2.1/{orcid}/fundings	Fetch all fundings
MemberAPIV21Api	view_group_id_record	GET /v2.1/group-id-record/{putCode}	Fetch a Group
MemberAPIV21Api	view_group_id_records	GET /v2.1/group-id-record	Fetch Groups
MemberAPIV21Api	view_keyword	GET /v2.1/{orcid}/keywords/{putCode}	Fetch keyword
MemberAPIV21Api	view_keywords	GET /v2.1/{orcid}/keywords	Fetch keywords
MemberAPIV21Api	view_other_name	GET /v2.1/{orcid}/other-names/{putCode}	Fetch Other name
MemberAPIV21Api	view_other_names	GET /v2.1/{orcid}/other-names	Fetch Other names
MemberAPIV21Api	view_peer_review	GET /v2.1/{orcid}/peer-review/{putCode}	Fetch a Peer Review
MemberAPIV21Api	view_peer_review_summary	GET /v2.1/{orcid}/peer-review/summary/{putCode}	Fetch a Peer Review Summary
MemberAPIV21Api	view_peer_reviews	GET /v2.1/{orcid}/peer-reviews	Fetch all peer reviews
MemberAPIV21Api	view_permission_notification	GET /v2.1/{orcid}/notification-permission/{id}	Fetch a notification by id
MemberAPIV21Api	view_person	GET /v2.1/{orcid}/person	Fetch person details
MemberAPIV21Api	view_personal_details	GET /v2.1/{orcid}/personal-details	Fetch personal details for an ORCID ID
MemberAPIV21Api	view_record	GET /v2.1/{orcid}{ignore}	Fetch record details
MemberAPIV21Api	view_researcher_url	GET /v2.1/{orcid}/researcher-urls/{putCode}	Fetch one researcher url for an ORCID ID
MemberAPIV21Api	view_researcher_urls	GET /v2.1/{orcid}/researcher-urls	Fetch all researcher urls for an ORCID ID
MemberAPIV21Api	view_specified_works	GET /v2.1/{orcid}/works/{putCodes}	Fetch specified works
MemberAPIV21Api	view_work	GET /v2.1/{orcid}/work/{putCode}	Fetch a Work
MemberAPIV21Api	view_work_summary	GET /v2.1/{orcid}/work/summary/{putCode}	Fetch a Work Summary
MemberAPIV21Api	view_works	GET /v2.1/{orcid}/works	Fetch all works

Documentation For Models¶

Documentation For Authorization¶

orcid_auth¶

Type: OAuth
Flow: accessCode
Authorization URL: https://orcid.org/oauth/authorize
Scopes:
- /read-limited: Read Limited record
- /activities/update: Update activities
- /person/update: Update person

orcid_two_legs¶

Type: OAuth
Flow: application
Authorization URL:
Scopes:
- /group-id-record/update: Update groups
- /premium-notification: Notifications
- /group-id-record/read: Read groups
- /read-public: Read Public record

Author¶

ORCID Hub API Appliction Registration¶

In order to use ORCID Hub API first you need to register your application navigating to Settings → Hub API Registration:

When you register your application the Hub generates application credentials, a pair of keys: CLIENT_ID and CLIENT_SECRET:

You have to make sure that CLIENT_SECRET doesn’t get compromised. Make sure you never make your client secret hard-coded in the source of your application. If you have even a slightest suspicion about having leaked the client secret immediately reset your application credentials using the same form:

ORCID API Proxy¶

An API proxy is an interface that provides controlled access to other system backend services. Rather than having them being consumed directly, those services can be accessed indirectly via the Edge API proxy. ORCID API Proxy provides value-added features such as:

Security

Rate limiting

Transformations

Fault handling

THE NZ ORCID Hub provides direct access to user access tokens. Using these access tokens, you can directly access ORCID’s API. First, you need to obtain a client credential access token and use the NZ ORCID Hub to do the 3-legged authentication dance to obtain access tokens for users, which are then stored at ORCID Hub database. These tokens are used to access users’ ORCID records:

However, an easier way is to use the NZ ORCID Hub’s API Proxy. To access the ORCID API Proxy, you need to use API access tokens. Unlike the previous method, you need only aquire a client credential token, which you can use to access all user profiles, for users who are affiliated with your organisation.

For testing purpose you can use `cURL<https://en.wikipedia.org/wiki/CURL>`_, for example,

curl -X POST -d "client_id=CLIENT_ID&client_secret=CLIENT_SECRET&grant_type=client_credentials" https://test.orcidhub.org.nz/oauth/token

You will get a JSON document with an access token, which you can use to make calls to ORCID Hub API including ORCID API Proxy:

{
    "access_token": "Qy4OCN3Ab6674JjzbFVR473j3oKVgn",
    "expires_in": 86400,
    "token_type": "Bearer",
    "scope": ""
}

For example, to retrieve a user profile:

curl -X GET "https://test.orcidhub.org.nz/orcid/api/v2.1/0000-0001-8228-7153" -H "accept: application/vnd.orcid+xml; qs=5" -H "authorization: Bearer jxDJWSna7wG73FoMSjOMRlq5pF1TZ4"

You can explore ORCID Hub API at https://test.orcidhub.org.nz/api-docs or https://orcidhub.org.nz/api-docs, and ORCID API at https://api.orcid.org/v2.1/#/Member_API_v2.1.

Webhooks¶

What is an ORCID webhook?¶

A webhook, according to Wikipedia is “a method of augmenting or altering the behaviour of a web page, or web application, with custom callbacks. These callbacks may be maintained, modified, and managed by third-party users and developers who may not necessarily be affiliated with the originating website or application.”.

In simple terms, a webhook allows your application to receive notifications from another application. In the ORCID context, the ORCID webhooks provide a mechanism for receiving user profile update notifications, enabling applications to be informed when data within an ORCID record changes.

What is an ORCID Hub webhook?¶

The ORCID Hub (hereafter preferred to as “the Hub”) provides efficient ways of managing webhooks for all organisation users, so that you do not need to register a webhook for each and every user yourself.

For those organisations that do not have their own integration solutions, the Hub offers an email notification handler which sends an email notification upon receiving a user record update event from ORCID Hub.

Here is how the organisation webhooks work:

When a user profile gets updated, the ORCID Hub triggers the Hub webhook update event handler.
The Hub handler, in turn, invokes the registered organisation webhook. If there are multiple organisations the user is affiliated with, all webhooks will be triggered.

Webhook Registration¶

In order to register an organisation webhook, you need to provide either a handler URL or enable email notifications. The Hub, on your behalf, will take care of registering the ORCID Webhooks for each and every one of your organisation users. After registering an organisation webhook, the Hub will take care to add a webhook for any new user who affiliates their profile with your organisation.

First, navigate via Settings → Set Webhooks and fill out the Organisation Webhook form. The Webhook URL should be your organisation applications Webhook handler URL. If you do not have an integration solution and wish to receive the notifications by email, leave this field empty, and, instead, check the Email Notifications Enabled checkbox and click on Save. By default, email notifications will be sent to the organisation technical contact email address. If you wish to have them sent to a different email address, fill in the field Notification Email Address.

After saving the form the Hub will go through all the user records affiliated with your organisation and register for each user an ORCID Webhook:

Development Environment¶

Minimal runnig ORCID Hub (assuming you have created and activated Python 3.6 virtual environment):

virtualenv -p python3.6 venv
. ./venv/bin/activate
pip install -U 'orcid-hub[dev]'
orcidhub initdb
orcidhub cradmin myadmin@mydomain.net  # use a valid email
orcidhub run

You can customize the backend specifying DATABASE_URL (defaul: sqlite:///orcidhub.db), for example:

export DATABASE_URL=postgresql://test.orcidhub.org.nz:5432/orcidhub
# OR
export DATABASE_URL=sqlite:///data.db

It is possible to run the application as stand-alone Python Flask application using another remote application instance for Tuakiri user authentication. For example, if the remote (another application instance) url is https://dev.orcidhub.org.nz, all you need is to set up environment varliable export EXTERNAL_SP=https://dev.orcidhub.org.nz/Tuakiri/SP.

export EXTERNAL_SP=https://dev.orcidhub.org.nz/Tuakiri/SP
export DATABASE_URL=sqlite:///data.db
export FLASK_ENV=development
orcidhub run

To connect to the PostgreSQL node (if you are using the doker image):

export PGHOST=$(docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' $(docker-compose ps -q db))
export DATABASE_URL=postgresql://orcidhub:p455w0rd@${PGHOST}:5432/orcidhub

Application Docker Image¶

Application Docker Image (orcidhub/app) is packaged with:

CentOS 7

Apache 2.4

Python 3.6

mod_wsgi (Pythgon/WSGI Apache module)

psycopg2 (native PostgreSQL Python DB-API 2.0 driver)

PyPI packages necessary for the application

Usage¶

Install docker following the instruction at https://docs.docker.com/install/linux/docker-ce/ubuntu/
Install git and docker-compose: sudo apt install -y git docker-compose
Add your user to the docker user group: https://docs.docker.com/install/linux/linux-postinstall/#manage-docker-as-a-non-root-user
And configure Docker to start on boot: https://docs.docker.com/install/linux/linux-postinstall/#configure-docker-to-start-on-boot
Clone the project repository: git clone https://github.com/Royal-Society-of-New-Zealand/NZ-ORCID-Hub.git
Change the current directory: cd NZ-ORCID-Hub
Create the environment configuration file .env from .env.sample
Set up environment variables UID and GID: export GID=$(id -g) UID
Generate SSL the server key and a self signed certificata in .keys directory, e.g., cd .keys; ../gen-keys/genkey.sh dev.orcidhub.org.nz; cd -
Create PostgreSQL and redis instance folders: mkdir -p pgdata data/redis
Run application containers: docker-compose up -d
Register a Hub administrator, e.g., docker-compose exec app ./flask.sh cradmin -V rad42@mailinator.com (more options available: docker-compose exec app ./flask.sh cradmin –help)
Enable sendmail, see Sendmail configuration
Open the Hub Application in a browser using http://localhost.

If successful, you will have five containers running: nzorcidhub_worker_1, nzorcidhub_scheduler_1, nzorcidhub_app_1, nzorcidhub_redis_1, and nzorcidhub_db_1. App is the core Hub code, and the process to connect to for users. Redis, worker, and scheduler are the processes that managing the Hub’s task queue.

Every subsequent restart can be achieved with:

export GID=$(id -g) UID
docker-compose up -d

from within the source directory. If/when you wish to stop the Hub simply:

docker-compose down

Environment Variables¶

The application image uses several environment variables which are easy to miss. These variables should be set up for the specific runtime environment with the configuration specified in the .env file:

Variable	Description
ENV	The runtime environment name (default: test)
SHIB_IDP_DOMAINNAME	Your Identity Provider domain name (default: http://directory.tuakiri.ac.nz)
SHIB_METADATA_CERT_FILE	Meta data signing certificate (default: conf/tuakiri-test-metadata-cert.pem)
SHIB_METADATA_PROVIDER_URI	Shibboleth SAML 2.0 meta data provider URI [NativeSPMetadataProvider](https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPMetadataProvider) (default: https://engine.surfconext.nl/authentication/idp/metadata)
SHIB_SP_DOMAINNAME	Your Service Provider domain name (default: ${ENV}.<container domainname>)
SHIB_SSO_DS_URL	SSO discovery service URL (default: https://${SHIB_IDP_DOMAINNAME}/ds/DS)
ORCID_CLIENT_ID	Orcid API client ID and secret, e.g., 0000-1234-2922-7589
ORCID_CLIENT_SECRET	Orcid API client ID and secret, e.g., b25ab710-89b1-49e8-65f4-8df4f038dce9
PGPASSWORD	PostgreSQL password
PGPORT	The port on which PostgreSQL should be mapped to (should be unique) (default: 5432)
SECRET_KEY	Hub secret key for data encryption
SENTRY_DSN	Sentry DSN (optional)
SUBNET	2 first octets (it should be unique for each environment run on the same machine), (default: 172.33)

Common problems¶

Error at SSL creation in setup¶

If you get the error “unable to write random state” at SSL certificate creation, you need to get ownership of ~/.rnd (which is likely owned by root). The easiest way to fix is to delete this file:

sudo rm ~/.rnd

and retry this step.

Can only docker/docker-compose with sudo¶

If docker-compose up fails the most likely cause is that you need to add the current user to the docker group.

sudo usermod -aG docker {your-user}

Once done, log out/in or restart to have this change take effect.

NB this is likely unsuitable for any production instance as the user will now be able to run containers to obtain root privileges. See: https://docs.docker.com/engine/security/security/#docker-daemon-attack-surface

Services report error(s) during docker-compose up¶

If docker-compose up fails at nzorcidhub_app_1, e.g., with “ERROR: for nzorcidhub_app_1 cannot start service app…Bind for 0.0.0.0:443 failed: port is already allocated” because you have other services using these ports, alternative ports for the Hub instance can be set in .env.

Variable	Description
HTTP_PORT	alternative http port (default: 80)
HTTPS_PORT	alternative https port (default: 443)

If it’s just a remnant of an earlier docker-compose pull or similar, a restart or killing the docker-proxy process will clear this isssue, e.g.,

sudo lsof -i:433 | grep LISTEN
sudo kill {PID identified above}

If docker-compose up fails at nzorcidhub_db_1, you’ve likely forgotten to precede this command with the necessary export GID=$(id -g) UID.

Need more help¶

For more guidance on troubleshooting docker see Troubleshooting

VirtualBox Set-up¶

Download Ubutnu Server ISO: https://www.ubuntu.com/download/server
Create VM with a NAT (Adapter 1) and a Host-only Adapter (Adapter 2) networking settings;
(Optional) if you want to provide access to your VM form the “outside world”, you need to add a “Bridge Adatpter” and ensure that you firewall allows connections to you host machine (port 80 and 443).
Mount the CD media (Ubuntu Server ISO), start up VM and install the server system;
Loging and install the extension pack and VM exensions on your server following https://www.mobilefish.com/developer/virtualbox/virtualbox_quickguide_install_virtualbox_guest_editions_ubuntu.html
Shut down the server and restarts it “headless”: VBoxManage startvm <YOUR SERVER> --type headless (use VBoxManage list vms to find out the name of your server);
Find out the IP address to connect from your host: VBoxManage guestcontrol <YOUR SERVER> run --exe "/sbin/ifconfig" --username <USERNAME> --password '<PASSWORD>' | grep 'inet ' (by default it starts with 192…)
Connect to your server: ssh <USERNAME>@<IP ADDRESS>

Sendmail configuration¶

The hub instance uses the OS mail functions in order to send email. For *nix that’s likely to be sendmail either on the Host or a dedicated mail server.

WARNING: Take care; testing the Hub with mail sent out under an illegal name, e.g., myuser@myhost-virtualbox is a great way to get your IP blacklisted, so ensure you’ve sendmail configured correctly.

Sendmail configuration for source or PyPI¶

On the basis that your environment is able to send email with an address (and from an IP) that is allowed by your domain, your hub instance email is enabled by setting the following variables: MAIL_SERVER; MAIL_PORT; MAIL_DEFAULT_SENDER; and MAIL_DEFAULT_SENDER.

NB: To ensure delivery and avoid appearing spammy, we have both SPF and DKIM enabled for our dev, UAT, and production environments.

Sendmail configuration for Docker¶

To send email from the Docker-based instance, you’ll need to edit /etc/mail/sendmail.mc accordingly to make it listen on the docker network and enable the relay.

Find the IP that your container is being served from:

docker inspect nzorcidhub_app_1 | grep IPAddress

With that IP, enable access to the sendmail server from the containers on the host, e.g., for the default container IP (172.33.0.1) add the following to sendmail.mc:

DAEMON_OPTIONS(`Port=smtp,Addr=172.33.0.1, Name=MTA')dnl
FEATURE(`relay_based_on_MX')dnl

For proper configuration of DMARC:

::: LOCAL_DOMAIN(`orcidhub.org.nz’)dnl FEATURE(masquerade_entire_domain)dnl MASQUERADE_DOMAIN(orcidhub.org.nz)dnl

And setup the DMARC report recievers in /etc/aliases fiile (and rebuild it with newaliases), for example:

::: dmarc: someone@something.something.edu,someoneelse

Grant relay access from the docker container network editing /etc/mail/access, e.g.:

Connect:localhost.localdomain           RELAY
Connect:localhost                       RELAY
Connect:127.0.0.1                       RELAY
Connect:172                             RELAY

And don’t forget to rebuild the configuration and restart sendmail, i.e.,:

sudo m4 /etc/mail/sendmail.mc > /etc/mail/sendmail.cf
sudo chmod 644 /etc/mail/sendmail.cf
sudo /etc/init.d/sendmail restart

Troubleshooting¶

Places to look up, if there is any issues:

docker logs, e.g., docker-compose logs app or docker-compose logs db
application logs, e.g., docker-compose exec app tail /var/log/httpd/test.orcidhub.org.nz-error.log
Shibboleth logs in the container: /var/log/shibboleth/ and /var/log/shibboleth-www/

Orcid Hub DB Recovery From Backup¶

Full DB Recovery¶

Stop the DB server, if it’s running: docker-compose stop db;
Remove all existing files and subdirectories under the cluster data directory and under the root directories of any tablespaces you are using.
Restore DB “cluster” data directory using the latest DB file backup YYYY-MM-DDTHHMMSS.tar.bz2 located in ~/archive into ~/pgdata directroy;
Create a recovery command file recovery.conf in the cluster data directory. You might also want to temporarily modify pg_hba.conf to prevent users from connecting until you are sure the recovery was successful:
```
restore_command = 'test -f /archive/%f.bz2 && bzip2 -c -d /archive/%f.bz2 >%p'
```
Start the server: docker-compose start db. The server will go into recovery mode and proceed to read through the archived WAL files it needs. Should the recovery be terminated because of an external error, the server can simply be restarted and it will continue recovery. Upon completion of the recovery process, the server will rename recovery.conf to recovery.done (to prevent accidentally re-entering recovery mode later) and then commence normal database operations.

Verify that the recovery was successful using the DB container logs: docker-compose logs db. The log should look like as follows:

db_1         | 2018-06-05 01:01:29.011 UTC [1] LOG:  listening on IPv4 address "0.0.0.0", port 5432
db_1         | 2018-06-05 01:01:29.011 UTC [1] LOG:  listening on IPv6 address "::", port 5432
db_1         | 2018-06-05 01:01:29.029 UTC [1] LOG:  listening on Unix socket "/var/run/postgresql/.s.PGSQL.5432"
db_1         | 2018-06-05 01:01:29.047 UTC [10] LOG:  database system was interrupted; last known up at 2018-06-04 14:00:13 UTC
db_1         | 2018-06-05 01:01:29.060 UTC [10] LOG:  starting archive recovery
db_1         | 2018-06-05 01:01:29.130 UTC [10] LOG:  restored log file "000000010000000000000077" from archive
db_1         | 2018-06-05 01:01:29.177 UTC [10] LOG:  redo starts at 0/77000028
db_1         | 2018-06-05 01:01:29.179 UTC [10] LOG:  consistent recovery state reached at 0/77000130
db_1         | 2018-06-05 01:01:29.180 UTC [1] LOG:  database system is ready to accept read only connections
db_1         | 2018-06-05 01:01:29.259 UTC [10] LOG:  restored log file "000000010000000000000078" from archive
db_1         | 2018-06-05 01:01:29.449 UTC [10] LOG:  restored log file "000000010000000000000079" from archive
db_1         | 2018-06-05 01:01:29.571 UTC [10] LOG:  restored log file "00000001000000000000007A" from archive
db_1         | 2018-06-05 01:01:29.691 UTC [10] LOG:  restored log file "00000001000000000000007B" from archive
db_1         | 2018-06-05 01:01:29.803 UTC [10] LOG:  restored log file "00000001000000000000007C" from archive
db_1         | 2018-06-05 01:01:29.844 UTC [10] LOG:  redo done at 0/7B03A158
db_1         | 2018-06-05 01:01:29.844 UTC [10] LOG:  last completed transaction was at log time 2018-06-05 00:59:41.700382+00
db_1         | 2018-06-05 01:01:29.930 UTC [10] LOG:  restored log file "00000001000000000000007B" from archive
db_1         | 2018-06-05 01:01:29.982 UTC [10] LOG:  selected new timeline ID: 2
db_1         | 2018-06-05 01:01:30.247 UTC [10] LOG:  archive recovery complete
db_1         | 2018-06-05 01:01:30.356 UTC [1] LOG:  database system is ready to accept connections

Point-in-Time Recovery (PITR)¶

By default, recovery will recover to the end of the WAL log. In order to perform PITR the following parameters can be used to specify an earlier stopping point. At most one of recovery_target, recovery_target_lsn, recovery_target_name, recovery_target_time, or recovery_target_xid can be used; if more than one of these is specified in the configuration file, the last entry will be used. Also you would need to add recovery_target_action = promote to recovery.conf. Alernatively, you can exeucute: SELECT pg_xlog_replay_resume();

For example, in order to recoer DB untill the state at, let’s say, Tue Jun 4 01:33:53 UTC 2018 you would need to add to recovery.conf:

recovery_target_time = '2018-06-04 01:33:53 UTC'
recovery_target_action = promote

Setting Up Hot Stand-up DB¶

In order to setup a hot stand-by DB. The recovery.conf should have following settings:

# rename this file to recovery.conf and change master DB server IP address:
standby_mode = 'on'
restore_command = 'test -f /archive/%f.bz2 && bzip2 -c -d /archive/%f.bz2 >%p'
primary_conninfo = 'host=MASTER_SERVER_IP port=5432 user=postgres'
trigger_file = '/var/lib/postgresql/data/pg_failover_trigger.00'

Where MASTER_SERVER_IP should be your master DB private or public IP address. Make sure the master DB server can be accessed from the stand-by server.

PostgreSQL Upgrade From Version 9.6 to 10.x, 11.x¶

Please follow the steps bellow:

Modify DB schema executing script bellow.
Dump DB using the current PostgreSQL version pg_dump: pg_dump --disable-triggers -d orcidhub -U orcidhub > full.sql
Stop and drop existing containers and remove /var/lib/docker.

Upgrade docker and docker-compose (1.23.0) following https://docs.docker.com/install/linux/docker-ce/centos/#os-requirements

sudo curl -L https://github.com/docker/compose/releases/download/1.23.0/docker-compose-$(uname -s)-$(uname -m) -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

Move pgdata directory and recreate it: mv pgdata pgdata_; mkdir pgdata
Recreate solution: docker-compose up -d
Restored DB: psql -d orcidhub -U postgres -f full.sql &>log.log
If you had customized the configuration, copy your configuration files form the backup directory pgdata_
And finally restart the solution.

Database upgrade script:

ALTER TABLE client ALTER COLUMN created_at SET DEFAULT (now() AT TIME ZONE 'UTC');
ALTER TABLE orcidtoken ALTER COLUMN created_at SET DEFAULT (now() AT TIME ZONE 'UTC');
ALTER TABLE org_invitation ALTER COLUMN created_at SET DEFAULT (now() AT TIME ZONE 'UTC');
ALTER TABLE organisation ALTER COLUMN created_at SET DEFAULT (now() AT TIME ZONE 'UTC');
ALTER TABLE task ALTER COLUMN created_at SET DEFAULT (now() AT TIME ZONE 'UTC');
ALTER TABLE url ALTER COLUMN created_at SET DEFAULT (now() AT TIME ZONE 'UTC');
ALTER TABLE "user" ALTER COLUMN created_at SET DEFAULT (now() AT TIME ZONE 'UTC');
ALTER TABLE user_invitation ALTER COLUMN created_at SET DEFAULT (now() AT TIME ZONE 'UTC');
ALTER TABLE user_org ALTER COLUMN created_at SET DEFAULT (now() AT TIME ZONE 'UTC');
ALTER TABLE user_organisation_affiliation ALTER COLUMN created_at SET DEFAULT (now() AT TIME ZONE 'UTC');

ALTER TABLE client ALTER COLUMN client_id SET NOT NULL;

ALTER TABLE orcidtoken DROP COLUMN IF EXISTS created_by_id;
ALTER TABLE orcidtoken DROP COLUMN IF EXISTS updated_by_id;
ALTER TABLE user_organisation_affiliation DROP COLUMN IF EXISTS created_by_id;
ALTER TABLE user_organisation_affiliation DROP COLUMN IF EXISTS updated_by_id;
ALTER TABLE funding_contributor DROP COLUMN IF EXISTS status;
ALTER TABLE "user" DROP COLUMN IF EXISTS edu_person_shared_token;
ALTER TABLE task DROP COLUMN IF EXISTS is_task_expiry_email_sent;
ALTER TABLE funding_contributor DROP COLUMN IF EXISTS put_code;
ALTER TABLE funding_contributor DROP COLUMN IF EXISTS processed_at;

ALTER TABLE audit.orcidtoken DROP COLUMN IF EXISTS created_by_id;
ALTER TABLE audit.orcidtoken DROP COLUMN IF EXISTS updated_by_id;
ALTER TABLE audit.user_organisation_affiliation DROP COLUMN IF EXISTS created_by_id;
ALTER TABLE audit.user_organisation_affiliation DROP COLUMN IF EXISTS updated_by_id;
ALTER TABLE audit."user" DROP COLUMN IF EXISTS edu_person_shared_token;

DROP TABLE IF EXISTS ttt;
DROP TABLE IF EXISTS ttt2;
DROP TABLE IF EXISTS testtable;
DROP TABLE IF EXISTS testtablewithbooleanfield;

UPDATE affiliation_record SET country = LEFT(country,2) WHERE length(country) > 2;
UPDATE audit.affiliation_record SET country = LEFT(country,2) WHERE length(country) > 2;

ALTER TABLE funding_invitees ALTER COLUMN orcid TYPE character(19);
ALTER TABLE peer_review_invitee ALTER COLUMN orcid TYPE character(19);
ALTER TABLE work_contributor ALTER COLUMN orcid TYPE character(19);
ALTER TABLE work_invitees ALTER COLUMN orcid TYPE character(19);

ALTER TABLE orcidtoken ALTER COLUMN expires_in TYPE integer;
ALTER TABLE audit.orcidtoken ALTER COLUMN expires_in TYPE integer;