Technical - Loading Person Data for Standalone COI or Protocols Implementation

Overview

Kuali Identify Services is the component of Kuali software that manages information used by other system modules. Kuali Protocols relies on Kuali Identify Services for two key types of data: Users and Groups.

• Kuali provides APIs that allow customer schools to load User data directly into Kuali Users. Detailed technical documentation is available at: https://developers.kuali.co.
• Groups data is loaded in by Kuali based on information provided by the customer school.  

Users

Users represent persons who will either need to access Kuali COI/Protocols directly by logging into the system and taking action, or whose data will need to be included in COI/Protocols. The following are examples of Users:

• A researcher from your institution who will need to log into Kuali to prepare a protocol.
• A student who will be named on a Kuali protocol that is prepared by someone else.
• A researcher from another institution who needs to prepare and submit a protocol for review by your institution’s human research review committee.
• A member of the human research review committee.
• An administrator in the human research ethics compliance office.

You will need to load the following data elements into Kuali to support Protocols functionality:

Data Element	Description/Usage	Required?	Valid Format
approved	Indicates whether the user is approved to log into Kuali Protocols	Y	true false
email	Email address of the user	Y	string
firstName	First (given) name of the user	Y	string
lastName	Last (family) name of the user	Y	string
name	first and last name of the user	Y	string
phone	telephone number of the user	N	string
role	determines what role the user should have in Kuali Users	Y	user admin external
schoolId	employee number	Y	string
username	Employee user name (used to log into SSO)	Y	string
primary group	The group ID  with which the user is primarily associated	N	string

• Schools can decide if all users coming into the system via the API will be automatically approved, or if users need to be manually approved to log into the system
• Example logic for maintaining users via API:
• GET all users from Kuali Users
• determine the differences between users currently in Kuali Users and users in the data from the source system
• For users currently in Kuali Users for which all data elements match, take no action.
• For users currently in Kuali Users for which there's a difference in data elements, use the PUT endpoint to update those users.
• For users not in Kuali Users, user the POST endpoint to add the new users

Here is some sample JSON:

{
"name": "Terrence Durkin",
"displayName": "Terrence Durkin",
"username": "tdurkin2",
"email": "[e-mail]",
"firstName": "Jane",
"lastName": "Smith",
"phone": "801-322-3323",
"schoolId": "theschoolid",
"approved": true,
"active": true,
"groupId":"58d2ef91834e0c0d78e6ace7"
}

Display Name in COI/Protocols

The value “Display Name,” which displays on screen in Protocols, is derived based on other data in the system according to the following logic:

• If the value  `name` exists, that will be used as Display Name.
• If that value doesn’t exist, "`firstname` `lastname`" will be used as Display Name.
• If that value doesn’t exist, `username` will be used as Display Name
• If that value doesn’t exist, email address will be used as Display Name.

Groups

Groups are only needed for Kuali Protocols.  They do not need to be loaded for a research lite supported implementation of COI.

Groups represent the organizational structure of a customer school, and are usually structured hierarchically.  A Group  is department, office, or other division of organization within an institution. Customer schools can  define a group at the institution with a name and number, and also associate it with a parent unit. Kuali will load your groups data for you as part of the implementation process, based on data you send us in a CSV file.

Data Element	Description/Usage	Required?	Valid Format
Group ID	Unique identifier for the unit/department	Y	string
Group Name	Name of the unit/department	Y	string
Parent Group ID	Unique identifier for the unit/department that is the parent of a given unit	Y	string

• The top level, typically represented as 000001, is the University
• Every unit other than the top level of the hierarchy must have a parent
• Group IDs listed here must be consistent with the primary group ID used in the user data

For example, given a structure like this:

The data needed by Kuali could be formatted like this:

Group ID	Group Name	Parent Group ID
000001	Portland State University
A&S	Dean Arts and Sciences	VPA
BIO	Dept of Biology	A&S
CS	Dept of Computer Science	A&S
ECON	Dept of Economics	A&S
ED	Dean Education	VPA
ELED	Dept of Elementary Education	ED
OGCA	Office of Grant & Contract Accounting	VPF
OSP	Office of Sponsored Programs	VPA
PO	Presidents Office	000001
RC	Research Centers	000001
SECED	Dept of Secondary Education	ED
SED	Dept of Special Education	ED
VPA	Vice President of Academic Affairs	000001
VPF	Vice President of Financial Affairs	000001