Setting Up Permissions in Faculty Search and Review, Promotion & Tenure via the API
Overview
This article explains how to use our API to manage permissions in Faculty Search and Review, Promotion & Tenure. Permissions are managed in the Core Framework API -- known as byc-api -- on a per-service basis. The Core Framework API supports the Faculty Search and RPT APIs by serving up common data elements such as user, unit, and permissions information. When interacting with any of those data elements in the API, you will need to do so through the lens of a given service where the valid values for "service" are "search" for Faculty Search, and "tenure" for RPT. Creating users and permissions for the "search" service will give users access to Faculty Search for your tenant with the role(s) that you assign them while creating users and permissions for the "tenure" service will give the users access to RPT for your tenant.
Prerequisites
You will need to have access to the given product at your tenant to be able to create users and assign them permissions in the given service.
Setting Up Permissions via the API
Assigning Roles
To assign a user a role within your tenant, you will first need a value for "pid", the identifier that Interfolio generates for a given user upon creation. The user must exist in byc-api within your tenant and the given service. This endpoint takes a query parameter "search" that allows you to search for a given user by "email", "first_name", or "last_name". This endpoint will return a result set that contains basic information, including "pid", about users that exist for your tenant and the given service and match any query parameters that were included.
To find the user to which you want to grant permissions, use the paginated users#search endpoint.
Note that the URL parameter "institution_id" is the same as your "tenant_id"; you will need to URL encode any symbols used in an email address.
Example:
GET => /byc/core/search/10668/institutions/10668/users/search?search=charlie.testuser%40interfolio.com&limit=1&page=1
GET => /byc/core/tenure/10668/institutions/10668/users/search?search=charlie.testuser%40interfolio.com&limit=1&page=1
200
{
"limit": 1,
"page": 1,
"total_count": 1,
"results": [
{
"id": 31337,
"pid": "20211103",
"first_name": "Charlie",
"last_name": "TestUser",
"email": "charlie.testuser@interfolio.com",
"external_user": false
}
]
}Next, you will need a valid value for "unit_id" to use to create the permission for the given user. This endpoint will return the unit objects, including the units' "id", for your tenant in their nested, hierarchical shape.
To look up the available units, use the units#hierarchy endpoint.
Note that units are shared between the "search" and "tenure" services -- meaning units are the same between the Faculty Search and RPT products -- so their IDs are the same regardless of the service value used to fetch them.
Example:
GET => /byc/core/search/10668/units/hierarchy
GET => /byc/core/tenure/10668/units/hierarchy
200
{
"id": 10668,
"name": "Interfolio University",
"units": [
{
"id": 10669,
"name": "College of API Development",
"units": [
{
"id": 10670,
"name": "Integrations Department",
"units": []
}
]
},
{
"id": 10671,
"name": "College of User Management",
"units": [
{
"id": 10672,
"name": "Identity Department",
"units": []
}
]
}
]
}Now that you have the "pid" for the user whyou want to manage and the "unit_id" to which you want to assign them a role, the last step is to create the permission. This endpoint takes a payload containing the "unit_id" and "role_id" parameters.
To do so, use the v2#permissions#create endpoint.
The available values for "role_id" for either the "search" or "tenure" service are as follows:
- "search" => 1 (admin), 2 (committee manager), 3 (EEO officer), or 4 (evaluator)
- "tenure" => 1 (admin), 4 (evaluator), 6 (case manager), or 7 (template administrator)
Example:
POST => /byc/core/v2/search/10668/users/20211103/permissions
BODY:
{
"unit_id": 10669,
"role_id": 1
}A few things to note about these roles:
- The default role is "4 - Evaluator." All users are created with this level of access. There is no difference between having this role and having no role as long as the given user exists at your tenant in the given service.
- A user with the role of "1 - Admin" that is assigned to the top-level unit (the "unit_id" value that is the same as "tenant_id" is considered an "institution administrator" and has the highest level of access possible in the system, including access to EEO data in Faculty Search.
- Users with a role of "1 - Admin" in the "search" service at a unit underneath the institution do not automatically have access to EEO data. There is an additional parameter attached to the permissions record that grants access to EEO data, "acts_as_eeo_officer" with a value of "true/false". You can include this parameter in the body of the permissions#create action to grant a given user the administrator role with access to EEO data.
- The "committee manager" role is not present in the "tenure" service. Those permissions are managed at the committee level by designating "manager = true" for a given committee_member record.
Removing Roles
If you wish to remove a given user's role, you will first need to verify the given user's permissions. This endpoint will return the user object for the given "pid", including the "permissions" node. This will be an array of the given user's assigned roles. Locate the role you wish to delete.
Use the v2#users#show endpoint to fetch the user.
Example:
GET => /byc/core/v2/search/10668/users/20211103
200
{
"user": {
"id": 1234567,
"first_name": "Charlie",
"last_name": "TestUser",
"email": "charlie.testuser@interfolio.com",
"pid": "20211103",
...
"permissions": [
{
"permission": {
"role_id": 1,
"unit_id": 10669,
"acts_as_eeo_officer": false,
"service_id": 1,
"title": {}
}
}
],
...
}
}Once you have identified the role you want to remove from the given user. This endpoint takes the "unit_id" and "role_id" parameters in the URL and removes the specified role from the given "pid".
Do so with the v2#permissions#destroy endpoint.
Example:
DELETE => /byc/core/v2/search/10668/users/20211103/units/10669/role/1
204 No Content