User Provisioning and Management in Faculty Activity Reporting via the API
Overview
Institutions want to ensure that appropriate faculty and staff will be easily added as users to Interfolio’s Faculty Activity Reporting (FAR, Faculty180.) Perhaps more importantly, it is necessary to make sure users that leave the institution have their access removed in a timely fashion and without manual intervention. Automating this type of integration via an API is particularly valuable in conjunction with campus Single Sign On (SSO). Beyond the efficiency of not having to manually create/update/remove users on an ongoing basis, this type of automated integration removes the bottleneck for faculty members or staff who want to access Interfolio tools while waiting on administrative personnel to manually create their account and provide them with their login information.
Prerequisites
For managing faculty the unique identifying “userid” (identified as the “Faculty Id” in the FAR software) that is, or will be, used for a given faculty member within FAR must be known. This id is generated by the institution and provided to FAR, along with the other required fields (the email address, primary unitid, employment status and faculty name) when a new account is instantiated. Also, for some resources, the Interfolio tenant_id and the faculty pid (personal identifier) is needed. -hese can be found via API endpoints using the institutionally assigned userid/faculty id. The unitid for the primary unit of a faculty member must also be known before a new user can be created via the API; this unitid is also valuable for searching and filtering users who might be assigned to a particular unit. The unitid can be found by using the “units” api endpoint.
It is also necessary to utilize the newer FAR HMAC API authentication for some of the resources described in this recipe.
User Provisioning and Management in FAR via the API
Provision and Manage Users
Managing user accounts via the FAR API consists of 3 main tasks:
- Creating/Provisioning user accounts
- Updating data in user accounts
- De-provisioning, i.e. removing login rights, from user accounts.
In order to complete these tasks effectively there are a number of data elements that should be fully understood. These fields are:
| Field | Description |
|---|---|
| userid (called the “Faculty Id” in the FAR software interface) | This is the primary Faculty identifier required and used throughout these API endpoints to identify faculty. It is an identifier which is assigned by the institution |
| PID (Personal Identification) | This is an Interfolio assigned identifier used across our entire Faculty Information System suite of software. It is needed for those few endpoints that assist in managing the linkages across the software suite. The PID for a faculty member is retrievable through the API using the /users/{userid} endpoint with the data=detailed parameter. |
| tenant_id | This is the Interfolio-assigned numerical identifier for your institutional database. This number is required for all endpoints that utilize the newer HMAC API authentication system. |
| employmentstatus | This is a fundamental Faculty Classification in FAR. Failing to provide a proper value to this parameter can result in confusion for administrators in the software trying to manage and report on faculty. The default values allowed are: “Full Time”, “Part Time”, “Staff”, “Inactive”. |
| primaryunit | This is a fundamental faculty attribute in FAR which specifies the unitid of the primary academic unit that a faculty is assigned to. Failing to provide a proper value to this parameter can result in confusion for administrators in the software trying to manage and report on faculty. The unitid of any given unit can be found via the /units API endpoint. |
| sendemail | This is an optional boolean parameter that controls whether a welcome email is sent to the faculty after their account is created. The default, if this parameter is not included/specified is to not send the faculty member an email upon account creation. If the boolean value of “true”, or 1, is sent a welcome email will be sent to the email address specified in the required “email” field (or that on file if a PID is specified for an existing account in another Interfolio software product.) |
The main user management tasks that are automated are account provisioning/creation and de-provisioning or removing access. There are three methods for provisioning an account in the FAR API:
- the “create a new user”
- “subscribe”
- and CSV bulk endpoints
Which endpoint is the preferred one to use depends upon whether the user has already been provisioned in another Interfolio software in the Faculty Information System (FIS) suite. If this is the first time a user is getting an Interfolio software account, the “create a new user” endpoint should be used. But, if the user already has an Interfolio FIS account then the “subscribe” endpoint should be used, to unambiguously associate the new FAR account with an existing Interfolio software account. If it is most convenient to add multiple users in bulk from data in a flat-file format, such as CSV, then there is a “subscribe multiple users via CSV” endpoint that can be used. De-provisioning users is a two-step process: remove the ability to log in, then set their “employment” status to the appropriate value to designate them as “inactive” faculty so their status is reflected properly within the software interface. To remove the ability of a faculty member to log in to FAR, they must be “unsubscribed” using the unsubscribe endpoint.
API Resources Available
| Resource | Description |
|---|---|
| Retrieve a listing of users with basic identifying information |
Action: GET => /users Required Parameters: None Optional Parameters: q, unitid, employmentstatus, data q: string This optional parameter allows for the inclusion of a query string that will search the three name fields (first, last and middle) of all user accounts and return any that have a match to the query string. The underlying query engine does partial substring matching, and a wild card, asterisk, character can be used in the query string. unitid: integer Providing a legitimate unitid specifies that the returned list of faculty should be only those assigned to the unit specified (or any of its sub-units). Unit IDs can be found using the units endpoint: “/units”. (Also, see the recipe on “Building and Managing Your Organizational Structure”.) It is acceptable to send a comma-separated list of unitids as the parameters value. employmentstatus: string The Employment Status is a fundamental Faculty Classification in FAR, and is often the first default filter that is used in sorting through a list of faculty. Using this parameter will limit the list of returned faculty to only those whose employment status is set to one of the proscribed values that is sent. The default values allowed are: “Full Time”, “Part Time”, “Staff”, “Inactive”. data: string A standard parameter found in all FAR GET endpoints which specifies the level of detail that should be returned. Valid values are: “count”, “summary”, and “detailed”. The default value, if none is specified, is “count”. If just the faculty userid is sought then “summary” is sufficient, but if the “PID” is required it is only returned in the “detailed” data. This endpoint is an important first step in managing existing users via the API. Calling it and finding the appropriate user in the returned list is the only way to know the “userid” and/or “PID” that is necessary for all later calls. |
| Create a new user |
Action: POST => /users Required Parameters: none Optional Parameter: none This is the primary mechanism for creating/provisioning user accounts via the FAR API. All basic profile data can be sent. The required fields are: userid, email, firstname, lastname, the unitid of the user’s assigned primaryunit, and the “employmentstatus”. The employment status is a default system faculty classification with pre-defined values. The default assignable values are: “Full Time”, “Part Time”, “Staff”, and “Inactive”. This endpoint adds a user to FAR, and will assign them a pid and link the newly established FAR account to other products in the Interfolio Faculty Information System suite of products through a consistent user’s email address. So the “subscribe” endpoint (see below), is not required if this is the first time a user is being created through all of the Interfolio Faculty Information System suite of products. There is a possible boolean data value of “sendemail” that can be sent with this request. If this is sent it does not affect the data in users new account but does trigger the user to receive an introductory welcome email (to the email address specified in the email field). |
| Subscribe a user to FAR |
Requires HMACs authentication Action: POST => /fars/{tenant_id}/users/{pid}/subscribe Required Parameters: tenant_id, PID in the path Optional Parameter: None If the faculty member being added to FAR is already a provisioned user in another software in the Interfolio Faculty Information System suite of products then this “subscribe” API endpoint can simultaneously add them as a new FAR user and link their account to the established account in another software. The data sent and parameters are very similar to the “create a new user” endpoint (including the “sendemail” option to send them a notification). The identifying “firstname”, “lastname” and “email” fields are not sent with this request because they are pulled using the PID provided. The remaining “required” fields of institutional “userid”, primary assigned unit unitid (primaryunit), and “employmentstatus” should be sent in order to properly create the user in FAR. |
| Update the details of an existing user |
Action: PUT => endpoint /users/{userid} Required Parameters: userid in the URL path Optional Parameter: none With the exception of the “userid” field, this endpoint accepts the same data fields as the Create User endpoint and is used to update these field values for an existing user. Any data values sent will overwrite existing values in the system. Note: Changing a user accounts “employmentstatus” to “Inactive” is not sufficient to “deprovision” their account and stop their login privileges. In order to stop a user account’s login privileges the “Unsubscribe a user” endpoint must be used. |
| Unsubscribe a user from FAR |
Requires HMACs authentication Action: PUT => /fars/{tenant_id}/users/{pid}/unsubscribe Required Parameters: tenant_id, PID in the path Optional Parameter: None Submitting to this endpoint will remove the ability of the user designated by the submitted pid from logging into FAR. This will not affect the data fields (such as employment status) in FAR. In order to update that data the “updates existing user” endpoint has to be used. |
| Subscribe and/or Update multiple users using a CSV file |
Requires HMACs authentication Action: POST => /fars/{tenant_id}/users/csv_create Action: POST => /fars/{tenant_id}/users/csv_update Required Parameters: tenant_id in the url path Optional Parameter: None With allowed data fields similar to Create, Subscribe and Update user endpoints this endpoint takes the same fields sent in bulk in CSV format. The CSV file must be uploaded as a part of the request. The CSV file must be formatted to have a header row indicating the correct names of the data fields sent and each row represents the data for a given user account. The required fields for each faculty record are the same as those for the Create a New User endpoint and the Update Existing User endpoints, as appropriate. The user identifier sent is the FAR userid. |
Check out the User management API documentation for more information