Retrieve Faculty Activities Details in Faculty Activity Reporting via the API
Overview
Faculty180's API provides the ability to bulk view and retrieve faculty activities data for any given activity type from any group of faculty members. Using this tool, institutions have multiple options for retrieving this data to meet their needs. In addition, this system has the ability to filter the output data to only show activities that have been updated after a certain date: allowing efficient, continuous updating of external data stores or applications.
Prerequisites
Data is pulled from one activity “section” at a time, for example, Grants, Institutional Service, Scholarship, etc. Thus, the use of the activity pull resource requires knowing the ID for the appropriate section(s) that activities are to be pulled from. These section IDs can be found using the sections endpoint. This section endpoint can also be used to show you the data fields that would be returned for each section. This field listing can be used to plan your data handling for the returned activity data. In terms of data handling it is also important to note that some activity data, like Scholarly Activities and Creative Productions (section_id = -21), will return complex data with nested arrays.
Retrieve Faculty Activities Details Using the API
Retrieve
This activity pull resource is one of the most flexible API endpoints. It has numerous options to both filter the content exposed and enrich that content. This flexibility is controlled through multiple optional parameters. The main filtering mechanisms involve filtering which faculty data is pulled for (using the “userlist” parameter) by specifying a list of faculty IDs, and filtering by a specified “term” period.
It is also worth noting here that if the intention is to access activities on a per-faculty basis, there are more efficient methods for doing that: pulling use the “userdata” resource, and pulling via the “vita” resource. Both of these will pull activities across all sections for a given faculty member.
This activities resource interacts very heavily with the “Activity Classification” metadata about faculty activities. These activity classifications can be used as filters (“activityclassificationfilter” parameter), e.g. show only scholarship that is peer-reviewed, or you can choose to list activity classification metadata that should be returned along with the standard activity field data about each activity (“activityclassificationpull” parameter). Both of these parameters allow multiple activity classifications to be utilized by taking comma-separated lists as arguments.
To find possible activity classifications that might be of interest they can either be viewed in the Faculty180 application under the “Setup” menu, or you can use the “/activityclassifications” API resource to pull a list of them and their ID values (the ID values are needed when specifying the activity classifications as parameter values.)
When using the activity classifications API resource be sure to use the optional “sectionid” parameter in the activity classification resource to limit the output to only those activity classifications that are tied to the activity section for which you are pulling data. In addition to pulling metadata about activities, there is also a separate Faculty180 API resource that allows you to pull any supporting documents associated with faculty activities. In order to do this you would have to “walk” the list of returned activities and for each activity (using its “activityid”, and associated “sectionid”) you can call the Download Attachments API resource: “/activities/{sectionid}/{activityid}/attachments”. Using this resource, in conjunction with the activity classification metadata pulls, would allow you to download all data associated with every activity in the system.
API Resources Available
| Retrieve List of Activity Sections |
Action: GET => /section Required parameters: none Suggested query parameters: “data=detailed” or “data=summary” data=summary: provides a simple list of the section names and their sectionid’s data=detailed: provides not only the section name and id but a complete listing of information for all the fields that activity data in that section will contain. |
|---|---|
| Retrieve Activities Details |
Action: GET => /activities_details/{sectionid} Required parameters: “sectionid” Suggested query parameters: “last_updated”, “page”, “limit” last_updated: (date in format) YYYY-MM-DD Last updated will allow you to search for activities within a section that were last updated on or after the day specified. Note: this parameter was introduced on 2018-01-17, thus any activity not updated after that date will be marked as “updated” 2018-01-17. page: integer Page will allow you to paginate the results if there is an exhaustive list of data. limit: integer Limit will allow you to limit the amount of data displayed, the default limit is set to 25,000. Note: There are many query parameters that can be utilized, the most important are the ones suggested above. A request with these parameters would look like: This will retrieve data from section with sectionid=-21 (Scholarly and Creative Productions) that was updated or created on or after 05-25-2018, it will also limit the search to 20 activities per page. If the activity is a Scholarly or Creative Production, a request could look like: This will search for the same as the previous API call, but, it will only search for Journal Publications. |
Check out the Activities Details API Documentation for more information.