Workflow Status Update

The Workflow Status Update Event is used to initiate a connection from iCIMS to a Partner. This event is triggered by a Platform user who wishes to send candidate or new hire and job information to a Partner.

What does the event do?: 

The Status Flow Update event was designed to provide recruiters and other Platform users with a way to initiate a connection to an iCIMS Partner.  A Platform user must select a Workflow profile and take action on a candidate/new hire that is attached to a Job or New Hire Category.  A specific status can be set as the trigger; once the candidate/new hire is placed into the trigger status, the connection will begin. The payload will be a JSON message containing the following parameters used to describe the request:

The partner replies to the original request in Step 1 with any of the following HTTP Status Codes and the criteria for these responses:

• HTTP 200 OK: The request was valid and was processed successfully; no further action is required. The partner should send a confirmation message to be displayed to the user in the JSON payload - {"userMessage":"Your message goes here.","code":200}
• HTTP 303 See Other: The request was valid and was processed successfully; the redirect link is provided in the response header.
• HTTP 400 Bad Request: The partner received an incorrect or malformed request, or is otherwise unable to service the request due to its contents.

In iCIMS, each Workflow Status change event has a ‘Show Confirmation’ option that must be configured in the platform. If this is ‘on’ for a successful transaction either a default message will be shown to the user that states  'Follow the link to confirm the action' or the partner can code a successful usermessage with the 200 OK response code. The default message will only apply to the integration if the partner is redirecting the iCIMS user with a 303 See Other return code to the partner platform to complete the request. If this is not the case, the partner will need to code a successful message or have the ‘Show Confirmation’ option turned 'off', in the sandbox as well as for each client. It provides a better user experience when the user sees a confirmation message however, it is not required. The partner will need to request to have the 'Show Confirmation' option set based on how they will be handling a successful transaction. All error messages returned with the 400 Bad Request response code will be displayed to the user. 

Example:
iCIMS -> Partner:

POST /rest/rest/echo HTTP/1.1
Connection: close
Link: https://api.icims.com/customers/1234/applicantworkflows/2203;rel="applicantWorkflow";title="Applicant Workflow",https://api.icims.com/customers/1234/jobs/1242;rel="job";title="Job Profile",https://api.icims.com/customers/1234/people/1364;rel="person";title="Person Profile",https://api.icims.com/customers/1234/people/3;rel="user";title="Posting User",
Content-Length: 280
Content-Type: application/json
Content-Encoding: gzip
Host: dummyserver.icims.com
User-Agent: Apache-HttpClient/4.2.1 (java 1.5)
Accept-Encoding: gzip,deflate

{
    "newStatus": "9782",
    "oldStatus": "1752",
    "customerId": "1234",
    "jobId": "1242",
    "userId": "3",
    "personId": "1364",
    "links": [
        {
            "title": "Applicant Workflow",
            "rel": "applicantWorkflow",
            "url": "https://api.icims.com/customers/1234/applicantworkflows/2203"
        },
        {
            "title": "Job Profile",
            "rel": "job",
            "url": "https://api.icims.com/customers/1234/jobs/1242"
        },
        {
            "title": "Person Profile",
            "rel": "person",
            "url": "https://api.icims.com/customers/1234/people/1364"
        },
        {
            "title": "Posting User",
            "rel": "user",
            "url": "https://api.icims.com/customers/1234/people/3"
        }
    ],
    "eventType": "WorkFlowStatusChangeEvent",
    "systemId": "2203"
}

Use Cases: 

Status Flow Update:

The Status Flow Update event is used by iCIMS to send person and job data to a third party vendor when an internal Platform user modifies a candidate’s status in the iCIMS Talent Platform. This event is most commonly used by clients who use a third party Background Check, Assessment, Video Interview, or Tax Credit provider, but can be used for other integrations as well.