Assessments

See the assessment type schema for a detailed description of every property you can pass for your assessment types.

In this example:

• Assessment results can be reused within 365 days. So if a candidate completes the assessment for one job, and then applies for another within this time, they won't be asked to complete the assessment again.
  
• The assessment results are sortable within the user's UI. So your app must be prepared to respond to POST /assessments/sorts.
  

If your app is completely "on demand" then it will be ready to return its assessment types immediately after the app is installed.

Otherwise, if your app requires setup (e.g. you need to set up an account for the customer) before it can meaningfully offer any assessment types, then you should return an empty set of assessment types.

Then, later on when your app's setup is complete, tell the assessment hub that you have new assessment types by consuming POST /assessmentTypes/forApp/deltaPings/1. In response the hub will consume GET /assessmentTypes/forApp on your app.

Apps can use different strategies for their assessment types:

• highly customised assessment types, e.g. each tenant has their own unique set of assessment types, tailored to their needs (e.g., "Acme 2018 finance graduate assessment").
  
• a single, universal assessment type that is the same for all tenants installing the app (e.g. "MS Word proficiency").
  
• some combination of the above.
  

This example shows a reusable assessment type. When your assessment type is marked as reusable, an assessment result on one job application is reused when the same candidate makes another job application within "daysExpired" - i.e the candidate only completes the assessment once.

For example, if the candidate has completed a medical check for one job, and then applies for another a few days later, we don't want them to be asked to complete the same check again. In this example, the assessment is reusable, and if the candidate completed the previous assessment within one year, then that previous result will be reused.

Most assessment types should be reusable. Before deciding that your assessment type should not be reusable, ask yourself "if a candidate completes my assessment and then a few minutes later they apply for another, identical job, does it make sense for them to complete the assessment again?".

Note that although the API doc. specifies a request body, currently no body is sent. You should assume that if the assessment does not already exist in your own database, then this is a new assessment, otherwise it is an update to an existing assessment.

You might do your own system's housekeeping for the new assessment, e.g. creating rows in your own tables, sending messages, etc.

In the future, your app may be informed via POST /assessments/byID/{id}/tenantDeltaPings that an assessment has been deleted (e.g. in response to a privacy response, or to conform to data retention laws). In response, your app should clean up data held its own database relating to the assessment.

Also in the future, your app may be informed that an assessment has been updated (e.g. in response to the tenant putting it on hold), in which case your app should stop whatever it is doing with the candidate.

An assessment can be in any of these statuses. There are 2 statues that can be set by the hub, and 4 statuses that can be set by your app.

Some statuses are final i.e. once the assessment is in this state, it will never leave it again.

Below are some typical scenarios:

The assessment is completed normally.

Started -> In progress -> Complete

The assessment is started.
The app detects a problem of some sort, and informs the customer.
The customer corrects the problem and restarts the assessment.
The assessment now completes normally.

Started -> Error -> Started -> In progress -> Complete

Assessment is started and the candidate opts out half way through.

Started -> In progress -> Opted out

The assessment is started and the customer cancels it while underway.

Started -> In progress -> Cancelled

Once the candidate has completed the online process hosted at your app, your app pushes the results, with the updated status.

The assessment's image appears in the assessment strip, which in turn is usually embedded in the ATS alongside the other applicant details (name, email etc.). Setting the image is a good way for you to help the user understand the results from your assessment at a glance, without needing to drill in (unless they choose to). This is useful in the tightly packed screens in a typical ATS, which show many applicants and many assessments on a single page.

You can simply serve up a static image, or generate your images dynamically, e.,g. passing in the candidate's score as a URL parameter. For an example of this, see this demo dynamic image generator for assessment apps, written in node.js.

Users will appreciate an image which is a great visual representation of your assessment:

• A video interviewing app could render a video thumbnail
• A psych assessment could render text with a percentage score, over a solid background in their corporate theme.
  
• A multi-stage probity test could render a series of checkboxes, with more boxes ticked as the assessment proceeds
  
• A culture fit test might show a colored graded heat gauge, with the needle pointing to the candidate's score
  
• A document check app could show a stamp, signifying complete
  

The status image should be suitable for displaying at an effective resolution of 52x32. Ideally your image should be 2x this to cater for high density displays (e.g. Retina Macbooks).

Previously the assessment hub could send an email to the candidate on behalf of your app, which could include the candidate interaction url.

This functionality has been deprecated, but you might still want to set the candidate interaction url (to e.g. the url for your quiz), as in the future there may be a UI that allows the candidate to reorient themselves from e.,g. within the ATS, and find their way back to you assessment.

You can optionally protect your web pages with TAS SSO, using principal type of candidate. This protects against the link falling into the hands of someone other than the candidate, and means the candidate enjoys a seamless experience as they navigate into your app.

If you do use SSO, you should probably perform a sanity check that the candidate who logs in matches the one the assessment is for.

You should set the user interaction uri and/or message when you want to convey or display something to the user (i.e. someone looking at a list of applicants, and seeing your assessment there).

The message is an easy and quick way to display an error message, a link to your ractual results (e.g. in pdf format), or just a short message about the assessment.

The message is treated as markdown format, and you can include links (these will open in a new tab/window).

The URI allows you to provide a complete web page. This might show:

• The results of your assessment (status == Complete)
  
• The reason why your assessment couldn't be completed (status == Error)
  
• Something the user has to do before the assessment can proceed (status == In progress)
  

When userInteractionUrl is set, your app's web page is rendered within an iframe in the popup over the assessment strip (i.e. within the ATS pages).

The iframe has a minimum width of 380px by default, and a maximum width of 960px. If no height is supplied the browser will default to 150px.

The following problems may cause a blank iframe inside the assessment popup.

• Make sure your content is served as https, not http. Otherwise in some browsers you may see errors in the browser such as "Mixed Content: The page at 'blah' wa loaded over HTTPS, but requested an insecure resource 'blah'. This request has been blocked; the content must be served over HTTPS."
  
• Make sure your page does not include the response header X-Frame-Options (e.g. something like X-Frame-Options:SAMEORIGIN). This is a security measure designed to stop your page from being framed - but in this case, that's exactly what you want.