# Job Distribution Connector

A job distribution vendor aggregates jobs and sends them to multiple job boards. The Job Distribution Connector allows you to develop an integration between Cornerstone and a job distribution vendor. You define the endpoints where Cornerstone sends the job posting requests. Cornerstone has defined standard contracts that you can implement at these endpoints. Recruiters can then send jobs to the job distribution vendor’s system directly from Cornerstone. They can also edit, repost, and delete postings from Cornerstone. The integration also supports sending the status and certain metrics about each job posting from the job distribution vendor to Cornerstone.

Note that only one job distribution vendor can be integrated in your Cornerstone portal using the connector.

# Deep Dive

# Job Distribution User Interface Workflow

  1. The recruiter creates a job requisition and posts to a Career Site.
  2. On the Job Postings page (Manage Requisitions > Edit Postings), the recruiter selects the job distribution vendor.
  3. The recruiter clicks on the Post button.
  4. The recruiter is redirected to the job distribution system in a new pop-up window where they choose the job boards and update the posting details.
  5. When the posting details have been configured, the recruiter closes the job distribution pop-up window and returns to the Cornerstone window/tab.
  6. The recruiter clicks on the Refresh button which updates the job boards table to display the job boards to which the job requisitions have been posted.
  7. If the job distribution supports the edit, re-post, delete and delete all workflows, the recruiter can perform these additional actions on the Job Posting page.

# Job Distribution Integration Workflow

job-distribution-integration-workflow

The job distribution integration workflow supports six actions. All actions are outbound (from Cornerstone to vendor) and are initiated by Cornerstone. There is no callback action (inbound) required or supported. At a minimum, the job distribution vendor must be able to support the Create Job Post and Refresh Job Posts workflows. While Cornerstone recommends that a job distribution vendor support all six workflows listed below to provide a seamless user experience, the remaining four workflows are optional and can be turned off through the Edge Client Settings page.

The contract for the actions is defined here: https://app.swaggerhub.com/apis/csodedge/Job-Distribution/. 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.

# Create Job Post

This call is used to create a job post on the job distribution vendor's system. The action is initiated when the end user clicks on the Post button on the Job Postings page > Job Boards section (Manage Requisitions > Edit Postings) in the Cornerstone Recruiting UI. The list of fields included in the request can be configured by a client admin through Edge (Admin > Tools > Edge > Integrations > Job Distribution Connector).

On receiving the request, the vendor is expected to respond with a re-direct URL. In the Cornerstone UI, the end user is re-directed to this URL in a new pop-up so that they can perform additional actions on the job distribution vendor's site, including completing required fields and choosing the job boards to which they want the job posted.

# Refresh Job Post

This call is used to fetch the status, job posting start date, end date, number of clicks and cost for each job board to which the job is posted to. This action is initiated by clicking the Refresh button on the Job Postings page > Job Boards section (Manage Requisitions > Edit Postings) in the Cornerstone Recruiting UI.

# Edit Job Post

This call is used to edit posting details for an existing job post. The action is initiated by clicking the Edit button on the Job Postings page > Job Boards section (Manage Requisitions > Edit Postings) in the Cornerstone Recruiting UI.

On receiving the request, the vendor is expected to respond with a re-direct URL. In the Cornerstone UI, the end user is re-directed to this URL in a new pop-up so that they can perform additional actions on the job distribution vendor's site.

# Re-post Job

This call is used to re-post an expired, deleted, or a job post with an Error status. The action is initiated by clicking on the Repost Job on the Job Postings page > Job Boards section (Manage Requisitions > Edit Postings) in the Cornerstone Recruiting UI.

On receiving the request, the vendor is expected to respond with a re-direct URL. In the Cornerstone UI, the recruiter is re-directed to this URL in a new pop-up so that they can perform additional actions on the job distribution vendor's site.

# Delete Single Job Post

This call is used to delete a single posting for a specific job board made through the job posting vendor. The action is initiated by clicking on the trash can icon on the Job Postings page > Job Boards section (Manage Requisitions > Edit Postings) in the Cornerstone Recruiting UI.

This action does not support a re-direct URL from the vendor. When Cornerstone makes this call to the vendor, it is expected that the vendor will delete the posting for the specific requisition and job board included in the request. The actual implementation of the delete action is up to the vendor since that is agnostic to Cornerstone - you can choose to implement a soft delete or a hard delete.

# Delete All Job Post

This call is used to delete postings for all job boards made through the job posting vendor. The action is initiated by clicking on the Delete All button on the Job Postings page > Job Boards section (Manage Requisitions > Edit Postings) in the Cornerstone Recruiting UI.

This action does not support a re-direct URL from the vendor. When Cornerstone makes this call to the vendor, it is expected that the vendor will delete all postings for the specific requisition included in the request. The actual implementation of the delete action is up to the vendor since that is agnostic to Cornerstone - you can choose to implement a soft delete or a hard delete.

# Functional Requirements

Upon installing the Job Distribution Connector through Edge, you will need to configure the items below in order to successfully set up your job distribution integration. For additional details on how to set up the job distribution integration in your Cornerstone portal, please refer to the starter guide.

Settings Page

  • Username
  • Password
  • Secret Key
  • Vendor Name
  • Base Service URL

Manage Users Page

  • Cornerstone User ID
  • Vendor User ID
  • Vendor Password
  • Vendor Token

# Technical Specifications

For each job distribution vendor, a new external service needs to be created and implemented against the contract as defined in https://app.swaggerhub.com/apis/csodedge/Job-Distribution/1.0.1.

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

# Encryption/Decryption

Cornerstone uses AES-256-CBC to encrypt the password and token configured on the Manage Users page. The encrypted password and token are included in all requests from Cornerstone to the job distribution vendor. The vendor should decrypt this information using the secret key defined in the Client Settings page in Edge and the 'salt' value included in the UserAccountData object in the request body.

For reference, here are sample codes for decrypting a user's credentials.

# Supported Languages

Cornerstone supports the following languages. The job distribution vendor will need to ensure the language code returned in the response to the Refresh action is one of the values listed below.

Code Langauge
en-US English - United States
en-GB English - United Kingdom
fr-CA French - Canada
de-DE German - Germany
ru-RU Russian - Russia
ja-JP Japanese - Japan
zh-CN Chinese - China
zh-SG Chinese - Singapore
zh-HK Chinese - Hong Kong SAR
it-IT Italian - Italy
pl-PL Polish - Poland
pt-BR Portuguese - Brazil
fr-FR French - France
es-MX Spanish - Mexico
es-ES Spanish - Spain
pt-PT Portuguese - Portugal
th-TH Thai - Thailand
nl-NL Dutch - The Netherlands
tr-TR Turkish - Turkey
ro-RO Romanian - Romania

# Testing and Verification

After installing and configuring the job distribution 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.

Prerequisites

  • The job distribution connector is installed and configured properly in your Cornerstone portal.
  • The job distribution connector is enabled through the Edge Manage Integrations page.
  • Your Cornerstone user account has access to the Recruiting Admin and Manage Requisitions page.
  • A job requisition has been created in your Cornerstone portal.

Step 1: The client admin posts a job requisition to a Career Site.

  1. Navigate to Recruit > Manage Requisitions > search for your requisition > click on the Options drop down > click on Edit Postings.
  2. Under the Career Sites section, post your job to at least one career site.
  3. Click on the Job Boards section.

Step 2: The client admin posts a requisition to a job distribution vendor's system.

  1. On the Edit Postings page, click on the appropriate job distribution vendor tab.
  2. Click on the Post button.
  3. The job distribution system will open in a pop-up window where you will configure and submit the posting details. Close the window.
  4. Navigate back to the Cornerstone window/tab.
  5. Click on the Refresh button.
  6. You will see relevant details for each of the job boards you selected to post your job in the job distribution vendor's portal.

Step 3: The client admin edits an existing job posting.

  1. On the Edit Postings page, click on the appropriate job distribution vendor tab.
  2. Click on the Edit button.
  3. The job distribution system will open in a pop-up window where you will make changes to an existing job posting. Close the window.
  4. Navigate back to the Cornerstone window/tab.
  5. Click on the Refresh button.
  6. You will see the changes you made for each of the job posting you edited.

Step 4: The client admin deletes a single job posting.

  1. On the Edit Postings page, click on the appropriate job distribution vendor tab.
  2. Click on the trash icon for the job posting that you want deleted.
  3. Click on the Refresh button.
  4. The deleted job posting is no longer displayed.

Step 5: The client admin deletes all job postings.

  1. On the Edit Postings page, click on the appropriate job distribution vendor tab.
  2. Click on the Delete All button.
  3. Click on the Refresh button.
  4. All job postings have been deleted.

Step 6: The client admin re-posts all job postings.

  1. On the Edit Postings page, click on the appropriate job distribution vendor tab.
  2. Click on the Re-post button. Note that you will only see the Re-post button if all your postings have been deleted or are in an expired or error status.
  3. The job distribution system will open in a pop-up window where you will perform any required actions. Close the window.
  4. Navigate back o the Cornerstone window/tab.
  5. Click on the Refresh button.
  6. You will see relevant details for each of the job boards you re-posted.