This Work Is Licensed Under a Creative Commons Attribution-Noncommercial-Sharealike 3.0

ANU ORCID Updater

System Customisation Manual

This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Australia License.

Contents

Overview 3

License 3

Components 3

Basic Customisation Overview 3

Feed In Data Source 4

User Interface 4

Permissions 6

Upgrading the Messaging Version 7

Overview

This document lists and explains the steps required to customise an instance of the ANU ORCID Updater software to your own institution. At the time of writing the ANU ORCID Updater software and associated documentation the current release version of the ORCID messaging protocol was 1.1. As such only the export of biographical and publication information has been developed. Version 1.2 adds support for the export of additional information such as grants and affiliations. Version 1.2 was in release candidate stage and as such still in flux.

The ANU ORCID Updater is currently a concept/demonstrator application. As such there will be errors and missing functionality.

License

Use of ANU ORCID Updater is governed by the GNU GPL3 license.

Components

The ANU ORCID Updater web application provides the means to for ANU to capture a user’s ORCID identifier, create a profile within ORCID if desired and to add publications for which the application knows about to the user’s ORCID profile. The system retrieves information from ANU Metadata Stores endpoints.

There are several modules to the orcid-update project. They are listed below with a brief explanation of each module.

1. auth – this module has the parts that authenticate and send data to orcid

2. data – this module holds the ORCID message components and the objects and parts to save to the database

3. metadatastores – this module is an ANU specific module that retrieves and shapes data to input into the ORCID Updater database

4. orcid – this module is the web application

5. process – this module contains the base classes with logic around retrieval of data

6. util – contains utility classes/methods

Basic Customisation Overview

The minimum amount of customisation required for your own organisation is as follows:

1. Set your own client id and client secret in orcid.properties (found in /orcid-update/auth/src/main/resources)

2. Make an equivalent of the metadata stores module and adjust the /orcid-updater/orcid/pom.xml accordingly. Specifically you will need to have your own equivalents for ObtainMSPersonInformation and ObtainMSPublicationInformation (i.e. extending ObtainPersonInformation and ObtainPublicationInformation with the fetch method) such that you can get the data from your own systems to save in the database. You will then need to update the personOI and pubOI with the appropriate class implementations.

3. Modify ldap.properties (found in /orcid/src/main/resources).

4. Modify the jsp files (found in /orcid/src/main/webapp/jsp). These will need to be skinned appropriately for your organisation. Accordingly remove the es-maven repository and anu-taglib dependency as these are ANU specific.

Feed In Data Source

Each institution that uses this will need to have their own adaption of feeding in data from an external system. The ANU ORCID Updater retrieves data from a system called ANU Metadata Stores which contains metadata retrieved from various other systems (e.g. it contains information about people, publications and grants). Documentation for the Metadata Stores system can be found at http://itservices.anu.edu.au/projects/completed/anu-data-commons/metadata-stores-documentation/.

The classes that transform and retrieve data from metadata stores can be found in the metadata module. There are two classes within this module that are of specific interest; ObtainMSPersonInformation and ObtainMSPublicationInformation. These classes extend ObtainPersonInformation and ObtainPublicationInformation respectively. Both of these classes implement a fetch method that retrieves data from Metadata Stores.

The data is retrieved from the Metadata Stores via a REST API that returns a JSON response. The response is then parsed into objects by the metadata module. While a connection to a REST API occurs for our system, it could potentially be any type of connection that is desired. For example, the information could be retrieved from a database or CSV file.

After the extended classes to retrieve the information from the data source have been created, adjustments to the applicationContext.xml are required (found in orcid-updater/orcid/src/main/resources). Specifically you will need to change the two beans with the id’s of personOI and pubOI to the appropriate classes.

User Interface

The ANU ORCID Updater is styled for the ANU purposes. It uses an ANU Specific JSTL tag library that aids in the rendering of web pages. As access to this tag library is limited to ANU users who have appropriate access permissions institutions will need to modify the styling of the User Interface to their institutions requirements.

The page structure of ANU web pages is as follows:

1. Explore bar

2. Site banner

3. Menu area

4. Content area

5. Site footer

6. ANU footer

For the ORCID Updater sections 1, 2, and 3 are rendered from the contents of header.jsp, section 4 is located in a specific JSP file (e.g. page.jsp, login.jsp, etc), and the contents of sections 5 and 6 are located in footer.jsp.

The following image is an example of what the application looks like with the ANU styling.

After the user logs in currently they will either be redirected to the url to import profile information, or to the home page. The import profile information will occur when the username begins with “u”. It is recommended that this is modified to suit your institutions requirements. The redirection is set in the class au.edu.anu.orcid.security.OrcidAuthenticationSuccessHandler in the onAuthenticationSuccess method.

Permissions

The ORCID Updater system is using the Spring Security framework for providing authentication and permissions. It has been set up so that only logged in users can view profile information, and the profile information that they can view is their own. The limitation of who can view this information is defined in the PermissionService interface with the @PreAuthorize annotation.

You could modify these permissions to limit actions to staff members for whome the institutional unique identifier is equal to the logged in user. At ANU we would add a role attribute to the contextMapper from the “affiliation” field in ldap. The contextMapper is found in the module orcid with the class au.edu.anu.orcid.security.SecurityConfig and the method configureGlobal.

LdapUserDetailsMapper contextMapper = new LdapUserDetailsMapper();

contextMapper.setRoleAttributes(new String[]{“affiliation”});

contextMapper.setPasswordAttributeName(“password”);

The @PreAuthorize annotation would then need to be adjusted to limit it to staff members.

@PreAuthorize(“hasRole(‘ROLE_STAFF’) and #person.uid == authentication.name”)

Other options may be to outline a set of privileged users in a database and perform appropriate adjustments within the code from there.

For the Spring Security documentation please see:

http://docs.spring.io/spring-security/site/docs/3.2.0.RELEASE/reference/htmlsingle/

Javadocs:

http://docs.spring.io/spring-security/site/docs/3.2.0.RELEASE/apidocs/

Upgrading the Messaging Version

As ORCID changes its schema there may be a need to update the schema. Download the latest version of the ORCID Messaging schema which can be found at https://github.com/ORCID/ORCID-Source/tree/master/orcid-model/src/main/resources .

After downloading the schema you will need to create JAXB classes based around the schema. The use of xjc to automatically generate the classes is recommended. You will need to then delete the files in the org.orcid.ns.orcid package found in the data module and add the new ones.

You will then need to update the message version in the UidObtainer and IdObtainer classes.

Depending on the updates within the schema there may need to be updates to other classes. This is likely to be updates to the return of the Orcid objects (e.g. the returns of OrcidBio and OrcidWork) in the Person and Publication objects in the data module. Otherwise there may need to be updates in the Obtainer classes (UidObtainer and IdObtainer).

Page 7 of 7