Pull Faculty Vitas in Bulk in Faculty Activity Reporting via the API
Overview
The faculty vita is the most common tool used for communicating faculty activities, accomplishments, and credentials. Interfolio’s Faculty Activity Reporting (FAR, Faculty180) tool relies heavily on the vita as a form of reporting. In FAR, standardized vitas can be configured to collect, group, and filter faculty activities and credentials to serve many purposes at an institution. These vita, with all the associated activities on them, can easily be pulled via the FAR API. Pulling activities on a vita through the API can also provide a simple mechanism for FAR administrators to configure what will be pulled by an API script without having to do any programming.
Prerequisites
In order for this API endpoint to work as intended, two elements are needed in the FAR system: configured standard vitas, and input faculty activities intended to be displayed on those vitas. All institutionally configured vitas are available to be used as templates for pulling data via the endpoint, but faculty personally configured vitas cannot be pulled. It is important to note that by default there is always an automatically configured, institutional-level “Standard Vita”, which displays all of the activity sections that have been configured in FAR.
A list of vitas can be retrieved via the API and the vitaID for the desired vita can be obtained from the listed data. Vitas can be searched by keyword or by the unit that owns/configured the vita. In addition, vitas are pulled on a per-faculty basis, and doing so requires the FAR userid to be known for each faculty member whose vita is to be pulled. This userid can be obtained via the “users” endpoint.
Pull Faculty Vitas in Bulk in Faculty Activity Reporting via the API
About
There are two intended purposes for these API endpoints: deliver a complete vita (via the output=html or output=html_clean parameters) ready for use outside of FAR, and deliver the fielded activity data contained within a configured vita (via the output=json, or output=html_clean parameters). The other significant benefit of these endpoints is that they allow a direct interaction between automated/scripted use of FAR data, via the API calls, and an easy-to-use, highly functional interface within the FAR interface that non-technical administrators can use. This ability to deliver a data set based upon a vita that was configured within the system would allow administrators to build, tweak and manage the output of an automated script simply by making changes to the vita that the script calls. The system allows the ability to create multiple types of vita for any given purpose, all of which can be accessed via these API endpoints. It should be noted, however, that this endpoint only delivers standardized institutional vitas; there is no way to pull vitas personally configured by individual faculty.
In retrieving a vita via these endpoints, the vitaID is necessary. This ID is not available within the FAR interface, but only via a queried search of possible vitas through the API. The vita title is the only identifying characteristic shown in the FAR interface and this title can be searched for through the API to find the vitaID. This does require that vitas be titled in a way that would allow each to be uniquely identified.
It is also important to realize that each vita retrieved is for a single faculty member and the activities shown on it are only for the specified time period. If no time period is specified (through the termstart and termfinish parameters) the default is to show only activities on the vita for the current semester. Since each vita is shown only for a single faculty member to retrieve vitas for multiple faculty the endpoint will have to be called multiple times, once per faculty member, using the userid/faculty id from FAR.
Beyond just pulling vitas directly, these API endpoints are very valuable tools for extracting activity data in an organized way. The output=json parameter allows the activities on the output vita to be pulled as fielded JSON data ready for use in any data application. In order to understand which fields will be returned for the activities in each section, the Retrieve details of all vitae endpoint can be called with the data=detailed parameter to return a complete listing of all sections and fields associated with the activities for that section for any vita.
API Resources Available
| Resource | Description |
|---|---|
| Retrieve details of all vitas (get a list of vitas) |
Action: GET => /vitas Required Parameters: None Optional Parameters: “q”, “unitid”, “data” q: string - This optional parameter allows for the inclusion of a query string that will search the titles of all the configured standardized vitas and return any that have a match to the query string. A wild card “*”, asterisk, character can be used in the query string. unitid: integer - Providing a legitimate unitid specifies that the returned list of vitas should be only those owned by the unit specified. Unit IDs can be found using the units endpoint: “/units”. This endpoint is a necessary first step in retrieving vitas via the API. Calling it and finding the appropriate vita in the returned list is the only way to know the “vitaID” that is necessary for all later calls. Check out this article on Building and Managing Your Organizational Structure for more information. Note that it is acceptable to send a comma-separated list of unitids as the parameter value. 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 vita ID is sought, then “summary” is sufficient. The “detailed” option also returns the complete list of data sections that each returned vita is configured to display. |
| Retrieve details for a user’s vita |
Action: GET => /vitas/{vitaid}/{userid} Required Parameters: “vitaid”, “userid” Suggested Parameters: “output”, “termstart”, “termfinish” output - string - This determines how the vita’s data will be returned. The options are: “json”, “html”, “html_clean”. The JSON and “html_clean” output return the activity data contained within the vita with no formatting. The “html_clean”, delivered HTML without formatting is designed to be a delivered option that allows for immediate easy use with the institution's own stylesheets applied for formatting. The “html” output delivers the formatted HTML vita document/page exactly as it would have been delivered within the FAR user interface, with all formatting intact. termstart & termfinish - string - A vita is a list of activities that occurred within a given time frame, so these two parameters are important to determine the list of activities that will be shown based upon what start term and end term are specified. To see a list of terms and their associated termids (the required parameter value) you can use the Faculty Activity Reporting terms API endpoint. The default for either of these parameters, if they are not given, is the current term. |
Check out the Vita API documentation for more information.