Build and Manage Your Organizational Structure in Faculty Activity Reporting 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, 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 Faculty Activity Reporting (FAR, Faculty180) API. Using 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 the renaming of units, and other functions.
Prerequisites
Before creating the organizational structure, an institution is required to complete setup of the Unit Designations and Academic Terms within the Interfolio Faculty Activity Reporting software (these can be found in Setup > School > Details).
Each unit in an organizational structure has a unique “unit_id”, “unit_name”, “unit_prefix” and “parent_unitid”. Units will share a “unit_level” that is unique to each unit designation in your structure. (For example: colleges are unit_level=2, departments are unit_level=3, etc.)
Every implementation will start with a single node at the top of an institution's organizational structure, in most cases this is the university.
The units created will not inherit rights from the parent unit, and newly created units will have no rights assigned to them by default. Editing and assigning the rights for unit admins must be done through the user interface.
Build and Manage Your Organizational Structure in FAR via the API
Using the API
In order to set up a structure that represents your university or institution, start at the top level and work down. The first unit, your institution, will be provisioned by Interfolio. From there, create units for each college, school, and department at your institution. To view your structure, retrieve units through the “retrieve units” action above or view it through our user interface. This can help identify what unit_level and parent unitid should be identified to create the 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 unitid as discussed above
- Understand the implicit unit_level of your new unit in the unit hierarchy
Next, start creating units with the “create a unit” action described above. When you create the first unit in your hierarchy, you will pass a number of parameters that will create your first unit under your 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 (generally level 2 units), followed by the departments (level 3) underneath, etc.
You can check your progress as you go by viewing your structure through “retrieving units” resource or through our user interface (under Setup > Organizational Structure.)
API Resources Available
| Resource | Description |
|---|---|
| Create a Unit |
When creating a unit, you are required to define the unit’s “name”, the unit’s “prefix”, the unit’s “level,” and the unit’s parent “unitid.” The parent unit must exist in the system prior to creating any of its children. The units “prefix” is used by institutions for the common abbreviation of a unit name, and is the default way that the unit is shown to administrators in the system, e.g. CoB for the College of Business. If your institution does not use such abbreviations, simply use the units “name” again for the unit_prefix field. This will create a new unit below the indicated parent unit. It will also assign your new unit a unitid. The unitid is an integer field that is created automatically as units are built. Since your university is the first node, it has a unitid of 1. The next unit created will be 2, the next will be 3, etc. Note that unit ids are independent of the unit level. Action: POST => /units Required parameters: “unit_name”, “unit_prefix”, “unit_level”, “parent_unitid” |
| Retrieve Units |
You can view existing units by running the retrieve action. The API response will contain every unit in your organizational structure. The “summary” query parameter will return a subset of key values, while “detailed” will return all of the values. This is used most commonly to retrieve the system’s assigned unit id for a unit for which you know the name. Action: GET => /units Required parameters: none Suggested query parameters: “data=detailed” or “data=summary" |
| Retrieve a unit by unitid |
You can view an existing unit by running the retrieve action. The API response will contain the unit specified in the path parameter of your request. The query parameters will return the same information that the /units path provides. Action: GET => /units/{unitid} Required parameters: “unitid” Suggested query parameters: “data=detailed” or “data=summary” |
Check out our Units API documentation for more information.