Building an assessment app
This is a high level overview of how to build an assessment app for use in the Talent App Store platform. Please check our Assessments article for more detailed information.
The assessment app sits as a connector between the Talent App Store platform and your own platform.
Define your app in Talent App Store
-
- Create a developer
- Create an app
- Take note of the HMAC secret for your app, you’ll need this for making/receiving API calls, as it acts like an API key
- Browse to the APIs tab and define the APIs for your app as per below
Producing
/assessments/byID/{id}/tenantDeltaPings
You don't need to define the install / uninstall APIs here
Consuming
/applications/views/byKey/{key}
/assessments/byID/{id}/appDetails
/assessmentTypes/forApp/deltaPings/1
-
Browse to the Tazzy tab, and enter your backend server URL. For testing purposes you might want to use ngrok (
https://ngrok.com/) to expose your locally running code
- Browse to the Single sign on tab and set the principal type to “User”
TAS APIs your app must expose
Check that the value of the `tazzy-secret` header on all API calls matches the HMAC secret for your app.
This API is called when your app is installed by a tenant in the Talent App Store.
This API is called when your app is uninstalled by a tenant in the Talent App Store.
This API is called when someone who has your app installed in their tenant, views your app in the Talent App Store marketplace. It is used to indicate if the app is ready to use for them, or if any further configuration is required.
This API will be called to retrieve the different types of assessments that your app has available for the given tenant.
This API will be called on your app to let you know that an assessment has been requested to be started / updated / deleted.We recommend that you add the assessment id here to a queue and respond to this call immediately rather than making the subsequent calls to retrieve assessment data synchronously, for a better user experience.
APIs your app will call
These API calls can not be made from the front end, as that would result in exposing the HMAC secret for the app.
Set the tazzy-secret header with your app's HMAC secret value.
The host you call for these APIs will be https://{yourAppShortcode}.tazzy.io
This will retrieve the assessment details by the provided id. This is the id passed in the Start / Update / Delete Assessment call.
This contains who raised the assessment, and the type of assessment it is, and a field called “view” which can be used in the subsequent API call to retrieve details about the application/candidate the assessment is for.
Call this API to retrieve information about the application / candidate that the assessment is for. These views are application specific so if there is additional data you require, tenants who install your app will need to know the fields they need to add to your app's view.
Call this API to update the assessment status and/or details.
Once the assessment has been started.
Once the assessment has been finished.
If the candidate has rejected/refused to complete the assessment.
If there are any errors with the assessment for any reason that means it can not be completed. It’s important to set the error status, otherwise assessments can be left in limbo.
The image will usually be displayed in the ATS and is a good way to visually indicate the status of the assessment.
A quick and easy way to provide a message to the recruiter/user. This field is markdown so you can include links to results.
When provided, the webpage at the provided URI will be iframed into the ATS to provide results/information about the current status of the assessment
Flag to indicate a pass or fail if applicable.
This notifies any other parts of the system which may have cached the assessment types available from your app that assessment types have changed and they should refetch them.
