# Assessment Connector

An assessment vendor is a specialized vendor which allows you to define the underlying endpoints where requests are made. Requests and Responses to these external endpoints are well defined and can be validated against. Only one assessment vendor can be integrated in your Cornerstone portal using the connector. Workflows in the UI as well as the business objects remain exactly the same.

# Deep Dive

# Assessment Workflow

  1. User requests a list of assessments from the assessment vendor.
  2. User selects an assessment from the list of available packages and assigns an assessment to an applicant.
  3. User is updated periodically regarding the status of the assessment

assessment-workflow

The assessment workflow can be broken down into 2 outbound messages (WebHooks) and 1 inbound message (Callbacks).

# WebHooks (Outbound)

https://app.swaggerhub.com/apis/csodedge/Assessment/1.0.1

The contract for the webhooks can be found on the page located above. These are the endpoints expected to be implemented by the developer. At various points of the integration workflow, Cornerstone will make calls to these endpoints.

# Get Assessments

This call is used to get a list of available assessments that can be assigned to an applicant. This is displayed on the UI in the form of a dropdown. The list returned is a simple key value collection.

# Initiate Assessment

This call is used to return an assessment URL that can be given to the target user to complete. The message includes a parameter for which assessment was selected, as well as a tracking id. If the option "Redirect via RedirectURL" is selected, this will also include a RedirectURL field allowing the assessment to redirect back into the CSOD application workflow upon completion.

# Callback (Inbound)

https://swaggerhub.com/apis/csodedge/Assessment/1.0.1

The contract for the callback can be found on the page located above. This is the expected message format when sending status back to Cornerstone via the CallbackUrl given as part of the InitiateAssessment call. Please remember to include the x-csod-edge-api-key custom header with the correct key when posting status back to this endpoint. Note: The callback is only valid for 100 days after the assessment is initiated.

# Callback API Key

When posting data to callback endpoints, you must include an API key in your request header. This API key can be found in the client's Cornerstone portal on the Edge Settings page.

Header: x-csod-edge-api-key:{API Key for your connector}

# Update Assessment Status

When posting results back to Cornerstone, use the callback URL that was provided as part of the initiate assessment request (you will need to store this). This callback URL already contains the necessary tracking information, which means the payload only needs to consist of the updated score, whether the assessment has been passed/failed, and any details URLs you wish to provide.

# Functional Requirements

You will need the following in order to successfully setup your assessment integration:

  • Base Service URL
  • Username
  • Password

# Technical Specifications

For each assessment vendor, a new external service needs to be created and implemented against the contracts as defined in the following documents:

Note: The external service needs to support TLS 1.2 for its communication with Cornerstone.

# Testing and Verification

After installing and configuring the assessment connector in your Cornerstone portal, you can test the integration by following the steps below. We strongly suggest validating the integration in either your stage or pilot environment prior to installing/enabling in the production environment.

There are two ways to assign an assessment to an applicant: through the ATS Workflow and post application via Assign Integration Assessment. We will be focusing on post application via Assign Integration Assessment for this quick verification.

Prerequisites:

  • Your assessment connector is set up and configured properly.
  • Your assessment connector is turned on within the Edge Integration Center.
  • Your Cornerstone Client Account has access to the Recruiting Admin Page as well as the Manage Requisitions Page.

Create Custom Status - Set Custom Integration to "Custom Assessment"

  1. Navigate to Admin / Tools / Recruit / Applicant Statuses
  2. Navigate to the parent division you want to setup the status for.
  3. Click on Create Custom Status. A window should popup. Add a name and description to your custom status. Select Custom Integration for Type. Select Custom Assessment for Integration.
  4. Click on Save to close the Create Custom Status box. Navigate to the bottom of the Manage Applicant Statuses page and click on Save to save your changes.

Assign Custom Assessment Status to Job Requisition

  1. Navigate to Admin / Tools / Recruit / Requisition Templates
  2. Find the position you want to add the status to and click on the "Manage Requisition Templates" icon.
  3. Click on Add Template (or copy an existing template).
  4. After filling in necessary requisition details, click on the Status List "Edit" icon to edit the requisitions status list.
  5. Click the "+" icon to add the custom status you created to this job requisition.
  6. Click on Done and proceed with completing your job requisition template.

Assigning Custom Assessment to Applicant

  1. At this point, it is assumed that you have already posted the requisition you created and applied as an applicant via the career site. If you need assistance with this step, please check out Online Help.
  2. Change the status of the applicant to the custom assessment status you created.
  3. Navigate to Manage Applicants for the requisition you posted and click on the checkbox next to the applicant's name that you just applied with. Click on the "Actions" dropdown.
  4. Click on "Assign Integration Assessment", and select the Assessment you would like to assign to the applicant. Click on Submit.
  5. You should see a new popup stating that the application action was successful.

If you are able to assign an assessment successfully you have validated that the integration setup is correct (username, password, Base Service URL). Once the applicant has completed the assessment you can view the status of the applicant within the Manage Applicant page. You can also click on the applicant's name from the Manage Applicant's page and click on the "Application" tab. Look for the custom status you created and you should be able to see a few different statuses that the assessment is in. Once the assessment has successfully been completed and a result has passed through, you should be able to see how the applicant scored.

# Sample Code

This is a base repository that you can clone and start building the external service. Please read the quick start to familiarize yourself.

This is the Swagger you should implement in the external service:

This is the contract you need to observe and send to Cornerstone Edge when making callbacks:

You can view an actual implementation based off AON here: