Task Lifecycle

A task represents the need for an employee to fill out a form in order to meet the compliance requirements of one or more placements. When a task is first created, its status shows "Requires Action". Most forms only need to be filled out by employees, and for tasks representing those forms, you will see "Employee" under the task "Next Action". This indicates that the employee needs to take action to complete the task.

Once tasks for an employee are created, employer usually sends an onboarding link to the employee so that they can start filling out the forms. If a form has sections that need to be completed by the employer, the task representing that form will see its next action transition to "Employer" once all the preceding employee sections are completed. Once employer completes their sections, the task's next action will transition back to "Employee" if there are remaining employee sections. Once all pages of the form is completed, the task status will transition to "Completed", and next action will become empty.

Once a task is completed, employees can no longer make edits from the onboarding link. They can still view their submission. However, the form becomes read-only (as shown below).

If an employee notices a mistake in their submission, they will have to contact you directly (please let us know if you'd like Onboarded to offer a feature that allows employees to request changes within our platform). To allow the employee to make edits to a completed task, click on the "Request Change" button from the task view (shown below).

Changes can only be requested against tasks in completed status. Once change is requested, the task status transitions back to "Requires Action", and the "Next Action" is set to the party responsible for filling out the first section of the form (which is usually employee). Now the employee can use their previous onboarding link and make edits to their previous submission.

API Integration

When integrating with Onboarded Task APIs, the Task API resource contains status and next_action fields. The status field follows the state machine below.

The next_action field returns a nested object in the following format:

{
  ... other task properties
  next_action: {
    type: "employer_action" | "employee_action"
    subtask_id: "subtask_xxx"
  }
}

Subscribe to task.updated webhooks to receive notification whenever task changes status. If you have forms that require both employee and employer actions, you will also receive task.updated webhooks when next_action.type changes as employees complete their form sections.