Run EEO / Form response reports
Run an EEO form report
Overview
The EEO form report leverages the API endpoint for our forms report. The API runs a report for a specific custom form, an EEO form for your use case, and accepts one or more position_ids. The API will take those position_ids and look up all applications for them and retrieve any form response data that exists for the specified custom_form_id. The report itself comes in two flavors, aggregated (summary) or detailed, and both can be converted to CSV output. The advantage to using this approach is that it is a straightforward and direct way to getting all the EEO data that you need for a single form. The downside is that it can timeout if the data set is too large. You also cannot specify what data to return beyond the two flavors of reports.
Pre-requisites
- The custom_form_id for the EEO form for which you want a report
- One or more position_ids that have the EEO form attached to it
-
Fetch custom forms list
- Run a GET call to the /units/{unit_id}/custom_forms/eeo endpoint.
- For this call, you're using byc-api, the core API, to retrieve all EEO forms for a given unit. You can use your tenant_id aka your institution_id as the unit_id. If you want to lookup EEO forms for a different unit other than your Institution, you can pass a different unit_id here.
- The API will respond with an array of custom form objects expressed in JSON. Each object will have an "id". This ID is the value that you will use for "custom_form_id" when running the forms report.
-
Fetch positions list
- Run a GET call to the /positions endpiont.
- For this call, you're using byc-search-api, the API that powers Faculty Search. You're retrieving a list of all positions at your institution. You can further limit this list by using URL query parameters "archived=true/false", "open=true/false", and "unit_id=id". For example, "/positions?archived=false&open=true" would return all open and active positions.
- The API will respond with an array of position objects expressed in JSON. Each object will have an "id". This ID is the value that you will use for "position_ids[]" when running a forms report.
- Run a forms report
- Aggregated
- Aggregated CSV
- Detailed
- Detailed CSV
- Run a POST call to one of the the /reports/custom_forms endpoints using a custom_form_id in the URL and position_ids[] in the form-data of the POST body.
- For this call, you're using byc-search-api to render a report either in JSON or CSV format. Here, you are passing custom_form_id in the URL path and also passing position_ids[] as form-data in the POST body.
- The API will respond with the custom form object containing the response data for each question. If you add the CSV extension to the URL, the API will respond with a CSV representation fo this data.
Fetch EEO Responses
Overview
This use case leverages the API endpoints to retrieve application data directly. The concept is essentially the same as the form report except that it is much more piecemeal. For this use case, you will retrieve EEO response data for individual applications rather than for a position or list of positions. Technically, you will be fetching the applications list for each position and then fetching EEO responses for each application. The advantage to using this approach is that you will never timeout when running through applications individually and it gives you more control over which applications for which you retrieve this data. The downside is that you have to retrieve data for each application and that requires that you run many more API calls to reach your end goal.
Pre-requisites
- List of position_ids
- List of application_ids
-
Fetch positions list
- Run a GET call to the /positions endpoint.
- For this call, you're using byc-search-api, the API that powers Faculty Search. You're retrieving a list of all positions at your institution. You can further limit this list by using URL query parameters "archived=true/false", "open=true/false", and "unit_id=id". For example, "/positions?archived=false&open=true" would return all open and active positions.
- The API will respond with an array of position objects expressed in JSON. Each object will have an "id". This ID is the value that you will use for "position_id" when fetching applications and then fetching EEO responses.
-
Fetching applications list
- Run a GET call to the /applications endpoint.
- For this call, you're using byc-search-api to fetch a list of applications for the given position_id.
- The API will respond with an array of application objects expressed as JSON. Each object will have an "id". This ID is the value that you will use for "application_id" when fetching EEO responses.
-
Fetch EEO response data
- Run a GET call to the /applications/{application_id}/eeo_responses endpoint.
- For this call, you're using byc-search-api to retrieve EEO response data for a given application_id.
- The API will return a custom form object containing the application's response data expressed as JSON.
Run Application Report
Overview
This use case leverages the API endpoints to run a faceted search report for application data, including EEO data. This concept is significantly different from the previous two use case. In this use case, you're using one endpoint to generate a report (CSV also available) of application data at your institution that matches a given set of facets or filters. You can also tell the API what data to return to you, so you can filter out extraneous data that you won't use. The advantage to using this approach is that it is a significantly more robust solution. You can filter the search results based on a set of facets, and you can filter the data returned based on a set of criteria. The downside is that this endpoint is significantly more complex and can time out if the results set is too large. Note: The data contained in these examples is not live in Sandbox, but is still test data that I've generated for this example.
Pre-requisites
The custom_form_id and question_ids for the EEO form for which you want data
-
Fetch custom forms list
- Run a GET call to the /units/{unit_id}/custom_forms/eeo endpoint.
- For this call, you're using byc-api, the core API, to retrieve all EEO forms for a given unit. You can use your tenant_id aka your institution_id as the unit_id. If you want to lookup EEO forms for a different unit other than your Institution, you can pass a different unit_id here.
- The API will respond with an array of custom form objects expressed in JSON. For this use case, you will record the "id" of the custom_form and the "id" of each question contained therein.
-
Run application report
- Run a POST call to the /reports/application_search endpoint with the defined "Accept" and "Content-Type" headers and a JSON payload in the POST body.
- For this call, you're using byc-search-api to run an application_search report. This endpoint takes a JSON body, parses the data that you send it, searches for applications that match the given set of facets, and then generates a JSON response that includes the criteria you define. For EEO data, you will include an array "custom_forms" that contains arrays of "questions" paired with the custom form "id" that further contains the question "id".
- In this example, I've filtered the result set by a facet "position_ids" that contains an array of position IDs. The API returns only applications to those positions. I've also set the values for "size" and "from" such that I will receive only 5 applications at a time, starting with the second page of 5 applications. I've also set the criteria to include only the application_id, position_id, and the given form ID and question IDs that correspond to the EEO form's questions.
- You can choose to filter the results by position_id to limit the size of your report, or you can run the report for all applications at all positions by not including that facet.
- You can optionally return a CSV of the results by appending ".csv" to the end of the URL => "application_search.csv". However, the CSV functionality will ignore "size" and "from" parameters.