Build and Manage Your Organizational Structure in FS and RPT via the API
Overview
An institution’s organizational structure is the hierarchical set of organizational units that represent the institution and all of its various academic and operational entities. Each unit is defined by a number of attributes, for example: unit name, unit id, and parent unit. Unit structure is very important because workflows, business logic behavior, and user permissions can be defined and modified at the unit level. The institution’s organizational structure and units can be built (i.e. provisioned, and managed) via the API. Use of the API for this work, when tied to output from an institution’s system of record for their organizational structure (for example, your ERP system), allows automation of common changes to units, such as renaming.
Prerequisites
An institution’s hierarchy starts with the institution, referred to as the “institutional unit”. While the institutional unit is a unit like all the rest, it is unique and exists above all other units, at the top of the unit hierarchy. It cannot have a parent unit assigned to it. There are two unique attributes that reference it specifically: “tenant_id” and “institution_id”. Both attributes are aliases of the underlying “unit_id,” but are used in specific ways throughout our APIs. The “tenant_id” should be used when exercising API routes. The “institution_id” should be used in various endpoints and actions via the API. The institutional unit can only be created by a staff member at Interfolio when the application is configured. Other than these distinctions, institutional units behave as and possess the same attributes as normal units when accessed through the API. Each unit in the hierarchy is defined by its own unique ID (noted as “unit_id”), its “name”, and its parent unit (noted as “parent_unit”; set as “parent_unit_id” or “unit_id”). A number of attributes can be set on the creation and even more on updates to define its settings and manage permissions and actions for users and objects underneath it. On creation, a unit inherits the settings of its parent unit.
Build and Manage Your Organizational Structure in FS and RPT via the API
About
In order to set your structure in an arrangement that represents your university or institution, you will start at the top level and work your way down. The first unit, your institution, will be provisioned for you by Interfolio. From there, you will create units for academic and operational units, e.g. college, school, and department, at your institution. Begin by viewing any existing unit hierarchy via the simple hierarchy view. This can help you identify what parent unit_ids you may need to identify to create your next unit. Before creating a new unit, it is critical to:
- Have the new unit’s parent unit already built in the system
- Find the parent unit’s assigned unit_id as discussed above
Next, start creating units with the “create unit” action described above. When you create the first unit in your hierarchy, you will pass the institution’s ID as the “unit_id”. This will create the unit at the second level, underneath the institution. This level most often represents colleges or schools at your university. You can then create units in sequence from the college or school level down to the department level. As an alternative method, you can create all colleges or schools first, followed by the departments underneath. You can check your progress as you go by viewing your hierarchy via the simple hierarchy view. You can also make changes to your hierarchy, such as assigning a unit to another parent unit, by using the update unit action described above.
API Resources Available
In the API endpoints discussed in this section, the path element shown as {service} refers to whichever Interfolio application you are referencing for your data. The allowable values for this path field are:
- “search” for the Faculty Search product, and
- “tenure” for the Review, Promotion, and Tenure product
| Resource | Description |
|---|---|
| Create a unit |
When creating a unit, you are required to define the unit’s “name” and the unit’s parent “unit_id”. This action will create a new unit object as a child unit of the passed parent “unit_id”. The parent unit can be any other existing unit in the hierarchy above the level at which you are creating the new unit. The unit name can be up to 255 characters in length. The API response will contain the base unit object that you created, including the newly created unit’s new, unique “unit_id”. Action: POST => /byc/core/{service}/{tenant_id}/units Required parameters: “unit[name]”, “unit_id” |
| Retrieve a unit |
You can view the details of an existing unit by running the retrieve action. The API response will contain the unit object for the given “unit_id” and that unit’s attributes for the given product API -- i.e. “service”. Action: GET => /byc/core/{service}/{tenant_id}/units/{unit_id} Required parameters: “unit_id” (path) |
| Update a unit |
When updating a unit, you can modify any setting or attribute about the unit relevant to the “service” parameter passed in the API route. Some attributes and settings are only relevant to the Faculty Search product (service: “search”), and some are only relevant to the Review, Promotion, and Tenure product (service: “tenure”). Action: PUT => /byc/core/{service}/{tenant_id}/units/{unit_id} Required parameters: “unit_id” (path) |
| Remove a unit |
You can remove a unit from your hierarchy by running the delete action. You can only delete a unit if the unit is not in use, meaning it has no Faculty Search positions or Review, Promotion, and Tenure packets associated with it. Action: DELETE => /byc/core/{service}/{tenant_id}/units/{unit_id} Required parameters: “unit_id” (path) |
| View the hierarchy |
This action will return a simple view of your hierarchy, arranged in nested unit objects that are described with their “name”, “id”, and any child “units”. Simple view: GET => /byc/core/{service}/{tenant_id}/units/hierarchy This action will return a complex view containing the various user roles and information about all the units to which the user has access. The relevant role nodes in the returned data are “administrator_hierarchy” (Search and Tenure), “committee_manager_hierarchy” (Search only), and “eeo_officer_hierarchy” (Search only). Each of these nodes will contain the nested unit hierarchy for which the current user has the noted permissions. Each unit contained in these nodes will have its unit “id”, their “parent_unit_id”, an array containing any child units, and the “in_use” attribute. Complex view: GET => /byc/core/{service}/{tenant_id}/units/usage |
Check out the Units API documentation for more information.