Welcome to ORCID Hub’s documentation!¶

|Build Status||Coverage Status|

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¶

Python Version¶

We recommend using the latest version of Python 3: Python3.6.

Dependencies¶

In order to enable authentication via ORCID you need to acquire ORCID API creadential:

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

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

Add http://127.0.0.1:5000/auth to redirect URLs and hit Save;

Copy CLIENT_ID and CLIENT_SECRET and set up environment varliables ORCID_CLIENT_ID and ORCID_CLIENT_SECRET with these values;

run :shell:`

TODO: acquire ORCID API creadentials, add the link

Sign up at ORCID with your email address.

Optional dependencies¶

For the integration with Shibboleth, the application should be deployed on Apache web server with … TODO: set up SENTRY account…

Minial Deployment¶

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'
orcidhub cradmin myadmin@mydomain.net --orcid YOUR-ORCID-ID -O YOUR-ORGANISATION-NAME
orcidhub run

By defaul the application will create a Sqlite3 database. 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

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+2.x+SP+on+RedHat+based+Linux. Primarily the documentation given under Federation Membership and Configuration sections.

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¶

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¶

run application containers: docker-compose up -d
find container IP address: docker inspect --format '{{.NetworkSettings.IPAddress}}' app
verify it’s running: http $(docker inspect --format '{{.NetworkSettings.IPAddress}}' app)

Environment Variables¶

The application image uses several environment variables which are easy to miss. These ariable should be set up for the specific runtime environment.

ENV¶

The runtime environment name (default: test)

SHIB_SP_DOMAINNAME¶

Your Service Provider domain name (default: *${ENV}.“*)

SHIB_IDP_DOMAINNAME¶

Your Idendtity Provider domain name, e.g., http://directory.tuakiri.ac.nz

SHIB_SSO_DS_URL¶

SSO discovery service URL (default: https://${SHIB_IDP_DOMAINNAME}/ds/DS)

SHIB_METADATA_PROVIDER_URI¶

Shibboleth SAML 2.0 meta data provider URI (more at: https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPMetadataProvider)

SHIB_METADATA_CERT_FILE¶

Meta data signig certificat

ORCID_CLIENT_ID and ORCID_CLIENT_SECRET¶

Orcid API client ID and secret

Steps to execute this application¶

If you are running this application for the first time then follow steps a to d:

From the project directory run pip3 install -r requirement.txt
install run install_package.sh to install postgress and required libraries
Create database and user in postgres

CREATE USER orcidhub WITH PASSWORD ‘***’;
CREATE DATABASE orcidhub;
GRANT ALL PRIVILEGES ON DATABASE orcidhub to orcidhub;

Run orcidhub initdb to create the tables in the application database.

Sendmail configuration¶

Enable access to the sendmail server from containers on the host. Find and edit /etc/mail/sendmail.mc accordingly to make it listen on the docker network and enable the relay:

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

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

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 costomized the configuration, copy your configuration files form the backup directory pgdata_
And finaly 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;