Managing Workflows via the Public API

This deployment guide will explain what a Workflow is in intelliHR and what workflows are designed to accomplish. From there, it'll describe the different Workflow Event Types that are available in intelliHR's public API and how each of these event types can be initiated. 

Navigation:

• What is a Workflow?
• Workflow Event Types
• Initiating a Workflow

What is a Workflow?

In intelliHR, many events can have workflows attached to them.

Workflows are a series of forms (sent as forms) assigned to various people at different points in time as a result of an action or change in the system. The forms are sent in a specific order based on the day of the event with the subject person always being the person who's profile triggered the event. The respondent to each form can vary between the subject employee, their supervisor or specific people such as a member from the HR Team or Payroll. 

For example, when adding a new job to the system, an administrator may want to trigger a series of onboarding tasks. These workflows are fully customisable and vary from customer to customer.

At a high level, to initiate workflows via the API, you’ll need to do the following:

1. When an event occurs, GET workflows attached to the associated Workflow Event Type
2. Iterate through until you find the workflow you're interested in through some nature of lookup or logic
3. Take the array of form designs and perform relevant date calculations, where you take the event date and determine the appropriate offset (and optionally compare with today and assert today if calculated value < today)
4. Construct the form design array with the newly minted dates
5. Perform a request to the PATCH Trigger a Workflow by ID endpoint to trigger the workflow

Workflow Event Types

Workflows are associated to an event type in the API like they are in the system. In order to initiate a workflow, you’ll need to retrieve the contents of the workflow by retrieving the workflows for the event type you’re interested in via the GET Workflows by Event ID endpoint.

The workflow events are listed below along with their associated Id’s.

Initiating a Workflow

The GET Workflows by Event ID endpoint will provide you with a list of all workflows attached to that Event Type. Each workflow will contain an array of form designs.

Example Code (JSON):

{
"id": "8a5f3ea6-ea6b-4425-8a87-3c256bb7b6f9",
"name": "Onboarding (Permanent)",
"actionName": "First Day of Job",
"description": "This event is triggered when a new job with the work type of Permanent is created for a person.",
"workflows": [
{
"id": "8a5f3ea6-ea6b-4425-8a87-3c256bb7b6f9",
"name": "New Permanent Onboarding",
"description": "This workflow contains a series of checklists and employee feedback tasks",
"workflowFormDesigns": [
{
"id": "8a5f3ea6-ea6b-4425-8a87-3c256bb7b6f9",
"days": -14,
"months": 0,
"formDesign": {
"id": "8a5f3ea6-ea6b-4425-8a87-3c256bb7b6f9",
"name": "New Employee Checklist",
"description": "Compliance task to check all necessary preparations before start date."
}
}
]
}
]
}
}

Each form ‘object’ in a workflow will return with the below pieces of information (also highlighted in blue in the above code block). 

• Id
• Name
• Description
• Information about the offset of the form from the triggering event, detailed in days and months. These offset values represents how the form has been staggered based on the event date of the workflow (i.e. for an onboarding workflow, the event is the employees First Day of Job, for offboarding, the event is the Last Day of Employment).

Form designs can be issued in the past - if you send a form design with a start date of 2 days ago, the form will issue immediately and 2 days will have lapsed on the due date for the form. While this doesn't always make human sense, it's a valid option as some businesses may want to represent that an action was processed far too late and desire the forms be closer to their due date to encourage completion. 

Once you’ve retrieved your list of workflows and identified the desired workflow, you’ll want to construct the body of the Trigger a Workflow by ID endpoint using the steps below. 

Method:

"method": 'PATCH'

Request URL:

"Url": https://api.intellihr.io/v1/workflows/{id}

The Id required in the path parameter of this request is the id returned along with the workflow name and description. In the example respond body above, this would be: "id": 8a5f3ea6-ea6b-4425-8a87-3c256bb7b6f9

Body:

To construct the body of your request, you’ll want to take the workflowFormDesigns.id and the calculated send dates to create to construct your list of workflow form design objects.

{
"workflowFormDesigns": [
{
// workFlowFormDesigns.id #1 here
"id": "8a5f3ea6-ea6b-4425-8a87-3c256bb7b6f9",
// calculated send date #1 here
"sendDate": "2021-03-02"
},
{
// workFlowFormDesigns.id #2 here
"id": "53ffe11b-3e06-44bd-8059-42e3743aca37",
// calculated send date #2 here
"sendDate": "2021-03-01"
}
]
}

You’ll also need to specify the job Id that the workflow is associated with.

{
"jobId": "bdebe724-426e-4f14-b727-ab3661b5d4c6",
"workflowFormDesigns": [
{
"id": "8a5f3ea6-ea6b-4425-8a87-3c256bb7b6f9",
"sendDate": "2021-03-02"
},
{
"id": "53ffe11b-3e06-44bd-8059-42e3743aca37",
"sendDate": "2021-03-01"
}
]
}

Bringing this all together, you can see an example of this procedure in JavaScript below.

Where idToGet represents the workflow you’re interested in sending.

output = {}

const options = {
url: `https://api.intellihr.io/v1/workflow-events/${inputData.workfloweventid}`,
method: "GET",
headers: {
"Content-Type": "application/json",
Accept: "application/json",
Authorization: `Bearer ${inputData.apikey}`,
Tenant: `${inputData.tenant}`,
},
}

const request = await fetch(options.url,{headers: options.headers})

const workflowFormDesigns = await request.json()

console.log(workflowFormDesigns.data)

const getWorkflowFormDesignsWithSendDate = (workflowEvents, idToGet, jobStartDate) => {
let formDesignsWithSendDate = []
workflowEvents.workflows.forEach((workflow) => {
if (workflow.id === idToGet) {
workflow.workflowFormDesign.forEach((formDesign) => {
console.log(formDesign)
let sendDate = new Date(inputData.jobStartDate)
console.log(sendDate)
const today = new Date()
sendDate.setMonth(sendDate.getMonth() + formDesign.months)
sendDate.setDate(sendDate.getDate() + formDesign.days)
const formDesignForPatch = {
id: formDesign.id,
}
console.log(sendDate)
console.log(today)
if (sendDate <= today) {
formDesignForPatch["sendDate"] = today.toISOString().split('T')[0]
} else {
console.log(sendDate)
formDesignForPatch["sendDate"] = sendDate.toISOString().split('T')[0]
}
formDesignsWithSendDate.push(formDesignForPatch)
})
}
})
return formDesignsWithSendDate
}


const getFormDesignsWithSendDate = getWorkflowFormDesignsWithSendDate
(workflowFormDesigns.data, inputData.idToGet) 

output.data = JSON.stringify (getFormDesignsWithSendDate) 
output.message = `Workflow Successfully Triggered`