Lifecycle of a Task: Task State
A Task is the core of TaskRouter — It represents a single item of work waiting to be processed. TaskRouter's primary role is to match a Task with a Worker, someone who can take action on the pending Task.
All of the other TaskRouter entities (TaskQueues, Activities, Channels, and especially Workflows) are used to support this assignment.
A Task progresses through a series of states, starting with pending, until successfully ending with completed. These Task states are closely associated with the Reservations that attempt to assign a Task to a Worker.
When a Task is created, it starts as pending. A Task will stay in pending until a matching Worker is found via a Workflow. Workflows and Assignment provides detail on how a Task is evaluated by a Workflow to be assigned.
A Task moves to reserved when a Reservation is created with a matching Worker.
Once reserved, a Task will move back to pending if the Reservation is rejected or the Reservation Timeout is reached. Otherwise, if the Reservation is accepted, the Task will move to assigned.
For multi-reservations, where multiple reservations are created simultaneously for a Task, the Task will only move back to pending if all of the created reservations end without acceptance.
At any point until the Task has been assigned, the Task can be canceled. This will primarily occur for one of three reasons:
- The Task is canceled by an API request.
- The Task times-out according to the TTL set on the Task.
- The Task passes the final step in a Workflow without an accepted Reservation.
- The Task has reached the Max Assignment Count, which is the number of times that a Task can move from status
pendingtoreserved.
canceled is one of two terminal states for a Task (the other is completed), and the Task will be deleted five minutes after moving into this state. Once a Task is canceled, it cannot be queued for assignment anymore.
Once a Reservation has been accepted, the Task is assigned. This is the period where the work represented by the Task actually gets done. For example, if the Task represents a voice call, the Worker would be connected to the other call participant.
After a Task has been assigned, it will only terminate at completed. An assigned Task won't move to canceled.
If the Task is not transitioned to completed within 24 hours, it is being deleted from the system after being in the assigned state for 24 hours.
Once the work associated with a Task is finished, the Task can be completed. For some Tasks, this will happen automatically by TaskRouter — for example, voice calls accepted via reservation.conference. Otherwise, a Task must be completed via the API.
In a multitasking Workspace, Tasks will move to wrapping first when the state is automatically transitioned by TaskRouter. Tasks can also be manually moved into wrapping by the API. wrapping Tasks must be moved to completed via the API.
The Task will be deleted five minutes after moving into completed.