This document describes how to import user profile data into Elements using the Elements REST API, and discusses related issues.

The term ‘user’ is used to cover two different, overlapping concepts. These are:

1. A login user: this defines which people are able to login to Elements and associated authentication and authorisations. Typical properties include username, password, security grouping information, and name details. These details are usually maintained with a regular HR feed from existing systems. The API calls associated with these feeds are designed specifically for this purpose.

2. A person who may be involved or associated with publications, grants etc. This User is a first class object within the Elements data structure, and represents one of the basic data Categories within Elements (e.g. Publications, Grants, Professional Activities, Users etc). Maintenance of these User properties (typically those that we refer to as the User Profile) are maintained using the standard API calls used for all Elements data.

In practice there is usually a one to one mapping between these two user concepts, but each has a different purpose, and is maintained using a different set of API calls. This document will focus on User Profile data.

Organisations may wish to import User Profile data into Elements for several reasons. These may be to:

1. Avoid or minimise manual entry of data

2. Make data available within Elements

3. Make data available within the Elements CV

4. Make data available through the Elements REST API

5. Make data available through the Elements Reporting Database

6. Make data available for other downstream systems (e.g. VIVO, Profiles RNS etc)

Imports may be performed as a one-off exercise (e.g. if migrating data into Elements from a system that will no longer be used) or as part of a regular feed (e.g. from an authoritative institutional application).

When a regular feed of data is implemented, Elements administrators should take steps to ensure that fed data is not updated from within Elements. If changes are required to data these should be made in the authoritative upstream system and then fed into Elements. The System Admin, Users, Profile Feeds page allows administrators to control which fields can be edited from within Elements. It is recommended that any fields that are fed from an external system are ‘locked’.

User Profile data covers the following data:

• Overview

• Research interests

• Teaching summary

• Addresses

• Academic-appointments

• Institutional-appointments

• Non-academic-employments

• Degrees

• Certifications

• Phone-numbers

• Email-addresses

• Personal-websites

• Language-competencies

• Postgraduate-trainings

Elements provides a powerful and flexible REST API for accessing Elements data. A range of documentation on the API is available here.

Key documents you should read before writing any applications that use the Elements API include:

• API User Guide

• API Requests and Responses

• API Resources and Operations

Before developing a User Profile feed you should be familiar with Hello world code: Implementing a data import feed. This provides a basic guide to writing an Elements data feed, using Grants as an example. User profile feeds are similar, but have a few key differences which you should be aware of.

Records are updated by referencing the proprietary-id of the record (/{cat}/records/{data-source}/{proprietary-id}). Note that this is different from the proprietary-id of the User, which is set by the HR Feed.

In order to obtain the proprietary id for a user record, you will need to use the following approach:

1. GET the details of a user, either by reference to the Elements ID of the user or the proprietary id of the user:

   1. localhost:8091/elements-api/users/30 (Elements user id of 30)

   2. localhost:8091/elements-api/users/pid-dwhook (user proprietary id of dwhook)

2. Inspect the response from above, and obtain the id-at-source attribute value from the returned record. This is the proprietary id of the record.

<api: records>
<api: record format="native" source-id="1" source-name="Manual" id-at-source="6C767-922A-4929-234-234235K3453">

Each object in Elements (publication, grant, user etc) has one or more records that contain a definition of the object from a given data source. So a publication may have records from Web of Science, Scopus and PubMedCentral - these represent the data source for the record.

When importing user profile data you must specify a data source for the data you are importing. Users only have a single record, whose data source is always manual.

By default Elements does not usually allow the API to import data into the manual data source. You should contact Symplectic to ask them to enable the manual data source to be used for API imports.

For most data imports a data record is updated using the API PUT command. This replaces an entire record at once. When importing data into a user profile it is very unlikely that you are updating all the user profile information - typically you may just be updating one or two data fields, such as institutional appointments. This requires the use of the PATCH command which supports just updating specified fields. See How to use the PATCH record API operation.

User profile data types tend to be large and complex when compared with data types used for other categories. For instance the single institutional-appointments data type contains all the institutional appointments information for a user. This may represent 15 appointments over a 20 year period. When updating a field such as this, the entire field is replaced - so you will need to ensure that you have all the data you need.

It is recommended that any fields fed from an external system are ‘locked’ in the UI so that they can only be updated by the feed.

The data structures used for all data types by the API are all documented in the API schemas - see API Schemas. You should make use of the latest endpoint - v6.13. In order to gain familiarity with the data structures used within a user profile you may wish to manually populate a profile in a test Elements instance, and make API calls using a Web API test tool (DHC, Postmaster etc).