Create Cases and Add Candidates to Case Packet for RPT via the API
Overview
Institutions can automatically create promotion or tenure cases in RPT and associate candidates with these cases. The review case can automatically be created and/or candidates can be associated with the case without time-consuming manual information entry. Utilizing this API recipe can reduce errors and ease the burden on administrators and staff managing review processes. This article will go over use cases and how to create an integration with RPT to automatically create cases.
Prerequisites
Before this API can be used, Interfolio Review, Promotion and Tenure (RPT) should be fully configured for use on campus, including defining Case types that might be used in these recipes (e.g. “Tenure”, “Promotion”, etc.). HMAC keys/credentials for RPT API access must be established (contact your Interfolio Project Manager or Customer Success Manager for acquiring API access keys), and you must know the “tenant_id” of the RPT database that you wish to be acting upon. Also, it is preferable that the following standard data be populated: units, faculty, and administrative roles. This recipe does not cover using the API to build a case from scratch. Rather, it will walk you through how to build a case from an existing template that has been configured within the RPT software interface. Therefore, the desired template must be properly configured before the cases can be assigned from it.
The API endpoints we will be calling use shared language common between both the RPT and Faculty Search software. The most relevant aspect of this shared API for this recipe is that “Cases” are accessed for RPT under endpoints labeled for “Packets”.
Create Cases and Add Candidates to Case Packet for RPT via the API
Build and Manage Cases
The key to utilizing this recipe for building and managing candidates for cases via the API is to have the RPT software properly configured with appropriate templates for the cases that need to be built. Using these templates greatly simplifies and helps assure accuracy in building cases dynamically. Building cases from defined templates automatically builds:
- Workflow “Steps” the case must progress through
- Associated “Committee” reviewers for each workflow step
- Sections for organizing case content
- Content requested for each section
Thanks to the automatic sequence above, there is no possibility of building a case and forgetting to build all of the complex elements that make the case function properly through the workflow in the RPT software. These templates, and associated cases built from them, are associated with academic units, and it is important to be able to use the API endpoints properly to determine the appropriate unit and its correct associated template. For example, when searching for the “templates” associated with a given “unit_id,” what the API returns is any templates directly associated with that unit as well as higher-level ancestor units that might apply.
Note that the word “packet” is consistently used to refer to what the software interface calls a “case”.
Also, it is important to recognize that these “Cases” are designed to allow flexibility and thus the designation of “candidates” is done in a very generic way that requires lastname, firstname, and email instead of a faculty or staff member user id. The system will take this information and, as the case is being built, look up the faculty account if it exists for the candidate information that is sent. If an account exists, it will put the user PID into the case; if no faculty account exists, it will build a new account. It is therefore important when sending the candidate email information to a candidate who is a faculty or staff member in the system to be sure to use the email that matches that which is already stored for the user account.
API Resources Available
| Resource | Description |
|---|---|
| Retrieve Units by Hierarchy |
Action: GET => /byc/core/tenure/{tenant_id}/units/hierarchy Required Parameters: “tenant_id” This endpoint will return a listing of units organized as a hierarchical JSON array of objects. The ID for the top-level unit in the hierarchy is always the tenant_id. Each descendant unit shows its name, id, and any of its descendants in a ‘units’ array. The unit_id is needed for each unit in which you want to build a case. It is also needed to identify the appropriate templates that exist to build cases from. These templates are organized by unit. |
| Retrieve Template List by Unit |
Action: GET => /byc-tenure/{tenant_id}/units/{unit_id}/packet_templates” Required Parameters: “tenant_id”, “unit_id This endpoint will return a listing of the RPT templates that are applicable to the specified unit, i.e. those built for the specific unit and all of its ancestors. From this list the 'packet_type_name', ‘unit_name’, and ‘name’ fields help identify the appropriate template to be used. The template_id in the ‘id’ field will be needed for building the cases using this template. |
| Create Case/Packet from Template |
Action: POST => /byc-tenure/{tenant_id}/packets/create_from_template Required Parameters: “tenant_id”, “template_id” (as “packet_id”), unit_id Optional Parameters: candidate _first_name: string candidate _last_name: string candidate_email: string These three parameters are necessary to indicate the candidate to be reviewed in this case. For existing users, these parameters will allow a lookup of the users PID (personal identification) to attach the case to, whereas for new users, an account will be created. candidate_involvement: boolean This boolean parameter serves the same function as the “Will the candidate submit their packet?” checkbox in the user interface as a case is built. It indicates that a candidate has an active role in preparing and submitting materials to be reviewed for the case. due_date: date The final date that this case is to be completed by. The above describes the primary way that cases for an individual candidate should be built using the API interface. Using the template automatically builds the appropriate workflow “steps” (with associated review “committees”), as well as the required sections and associated requirements for each section. |
| Create Case/Packet from Template in Bulk |
Action: POST => /byc-tenure/{tenant_id}/packets/bulk_create_from_template Required Parameters: “tenant_id”, “template_id” (as “packet_id”), unit_id, users array users[]: JSON array of objects This is an array of candidates. Each candidate can have: firstname, lastname, email, and eppn submitted. Optional Parameters: candidate_involvement: boolean This boolean parameter serves the same function as the “Will the candidate submit their packet?” checkbox in the user interface as a case is built. It indicates that a candidate has an active role in preparing and submitting materials to be reviewed for the case. due_date: date (The final date that this case is to be completed by.) This endpoint facilitates building multiple individual cases from the same template for a group of candidates. Using the template automatically builds the appropriate workflow “steps” (with associated review “committees”), as well as the required sections and associated requirements for each section. |
Use Cases
| Use Case | Description |
|---|---|
| Integration with External Systems for Case Creation | If utilizing systems that can determine the right timing for case creation, such as Customer Relationship Management (CRM) or Human Capital Management (HCM), you can develop an integration that allows these systems to trigger the case creation processes efficiently. |
| Candidate Initiated Cases | To enable faculty users to initiate cases for specific workflows, such as sabbaticals or non-routine reviews, consider developing a custom form that interfaces with your API. This form can be designed to initiate case creation directly in response to user input. |
| Automated Workflow Across Different Systems | In scenarios where your process begins in one system and needs to continue automatically in another (such as an RPT module), developing an integrated solution can ensure a smooth and automated transition between systems. |
| API-Driven Case Creation for High Volume Needs | If handling a high volume of cases annually, leveraging API technology can be a strategic move. It offers an efficient solution compared to manual, individual, case creation, thereby enhancing the overall efficiency and scalability of your case management process. |
| Automated Committee Assignments for Each Candidate | In scenarios where each candidate might need a different committee, implementing API-driven automated case creation and committee assignment can be advantageous. This approach removes the need for manual committee assignments for each candidate, promoting a more streamlined and error-free operation. |
Check out the API documentation for cases and candidates for more information.