Task Expiration

When the expiration time of a task passes, the task status becomes "expired". Expired tasks are no longer considered in the calculation of a related placement's completion progress. Setting expiration time on tasks allows employers to, for example, require candidates to re-verify their eligibility to work before their temporary work authorization expires. This guide covers different ways to set task expiration time and how you can monitor when a task becomes expired.

Setting task expiration time

There are several options for setting task expiration time. Please choose from the options below based on your use case.

Expiration time by candidate input

Task expiration rules allow tasks to dynamically expire based on date/time information provided by candidates when they submit a form. Use task expiration rule if you have a form, with input that collects ID/license expiration date, and you want the task to expire based on the date provided.

To manage task expiration rules, first go to the details view of an active form. Click on the "Expiration Rules" button to bring up the expiration rule management panel.

The panel shows existing expiration rules for the form. To add a new expiration rule, select a date field from the "New Rule" dropdown - this list shows all the date fields from the form. The field you select will determine when a task created from this form expires. Click on the "Create Expiration Rule” button to save your selection.

In the example above, we see an expiration rule has been created for the field form.document_b_expiration. This means whenever a candidate submits the form (I-9, in this case), the completed task will automatically expire based on the date they provide in the field form.document_b_expiration.

To delete an expiration rule, click on the trash icon from the rules table.

Expiration time by task

If you know exactly when a task should expire, you can directly set the expiration time of a task via Onboarded Dashboard or the Task API. This can be helpful when your expiration logic lives outside Onboarded.

Dashboard

To set task expiration time, go to the details view of a task. Click on "Edit" in the top-right corner to get to the task-edit view (shown below). From there, you can set or update the expiration time of a task.

API

Task expiration time can be set via the Update-Task API as shown below.

curl -i -X PATCH \
  'https://app.onboarded.com/api/v1/tasks/{id}'
  -d '{
    "expired_at": "2019-08-24T14:15:22Z"
  }'

Expiration time by form

In addition to setting expiration time directly to a task, you can also set it on a form. Doing so allows you to expire all tasks of the form at a specific time. This can be helpful if the form itself has a natural expiration time.

To set form expiration time, click on the draft version of any form in your account, then click on the pencil icon to open the edit view:

You can then set the task expiration time as shown below. Don't forget to click "Update Version" to save your changes.

Expiration by task completion time

In addition to setting specific expiration time, you can also set task expiration based on when it's completed. For example, if you have a form that requires candidate to be re-certified every x days after completion, you can set the "Days Before Task Expires" field on any draft version. Setting the value to 365, for example, will cause every completed task under this form to expire 365 days after its completion time.

Task expiration behavior

When a task expires, you will receive a task.updated webhook. In the webhook payload, the task status will show as “expired”. Furthermore, if a candidate has yet to complete a replacement task, you will receive placement.updated webhooks for each placement affected by the expired task. In the placement.updated webhook payload, you will see reduced completion percentage. This indicates that the candidate no longer meets all compliance requirements under the placement.

Once a task has expired, it can no longer be edited. Employers should create a new task (POST /api/v1/tasks) and send an onboarding link to the candidate, so that they may complete the task by submitting the form again.

Retrieve task expiration time

In the API, task expiration time is returned under the field expired_at in Task API resource. You can find this field in APIs such as Get-Task and List-Tasks endpoints, as well as Task webhook payload.

In the dashboard, you can view task expiration time by visiting the task details view (shown below)

Special Considerations

• A task may have multiple, competing sources that simultaneously affect its expiration time. For example, you can set explicit expiration time on both a task and its form. At the same time, the form may also have an expiration rule, as well as an expiration day by completion. When this happens, Onboarded calculates the expiration time from all applicable sources and uses the earliest timestamp as the task's actual expiration time.
• Only "completed" tasks may expire. If you set expiration time on a task under the "requires_action" status, the task will not transition to "expired" status until it's completed.
• Task expiration time is only calculated upon task completion. This means unless you set an expiration time directly on a task, you will not see any task expiration time (neither via dashboard nor API) until your task is completed (even if there are relevant form-level expiration settings).
• Task expiration time is calculated out of band when a task is completed. This means you may first receive a task.updated webhook with "completed" status and no expired_at; then another task.updated webhook with either "completed" or "expired" status and a value under expired_at.
• Task expiration is evaluated from a batch process, and tasks may not transition to "expired" status immediately past their expiration times. Onboarded SLO aims to transition all tasks within 6 hours past their expiration time.
• When a task expiration rule is created, it will only apply to tasks completed from that moment onwards. Tasks that are completed before an expiration rule is created will not be affected by the expiration rule.
• When a task expiration rule is deleted, any task that was completed while the rule was present, will continue to expire based on the candidate's field input. In other words, deleting a task expiration rule will not alter the expiration behavior for tasks that have already been completed.

If your use cases are not well supported by the features above, please let us know.