Lifecycle of a Task: Workflows and Assignment

1
  "task_routing": {
2
    "filters": [
3
      {
4
        "expression": "type==\"Support\"",
5
        "filter_friendly_name": "Support Calls",
6
        "targets": [
7
          {
8
            "queue": <Just Support>,
9
            "timeout": 15,
10
            "expression": "worker.id IN task.preferred_agents"
11
          },
12
          {
13
            "timeout": 15
14
          }
15
        ]
16
      },
17
      {
18
        "expression": "type==\"Sales\"",
19
        "filter_friendly_name": "Sales Calls",
20
        "targets": [
21
          {
22
            "queue": <Just Sales>,
23
            "timeout": 15
24
          }
25
        ]
26
      }
27
    ],
28
    "default_filter": {
29
      "queue": <Everyone>
30
    }
31
  }
32
}

This configuration would be represented in Console like:

Expand image

A Workflow evaluates linearly from the top to the bottom. A Task will find the first filter that matches that Task's attributes. Within that filter, the Task will then work progressively through each target ("routing step" in Console). A Task will wait in each step for the defined timeout attempting to get an accepted Reservation. If the Task hits the step timeout, it will move to the next step. If the final step is passed without an accepted Reservation, a WorkflowTimeout event will fire and the Task will be canceled.

The default_filter is only invoked if a Task doesn't match any filters. In this case, TaskRouter will attempt to find a matching Worker in the Queue defined by default_filter until the Task reaches its TTL.

Suppose a Task is created for the Workflow defined above with the following attributes:

1
{
2
    "type": "Sales"
3
}

First, the Task would check against the "Support Calls" expression: type==\"Support\"". Failing that check, the Task then succeeds against the "Sales Calls" expression: "type==\"Sales\"".

Sales Filter:

1
{
2
    "expression": "type==\"Sales\"",
3
    "filter_friendly_name": "Sales Calls",
4
    "targets": [{
5
        "queue": <Just Sales>,
6
        "timeout": 15
7
    }]
8
}

The single routing step attempts to find a matching Worker in the "Just Sales" TaskQueue. This queue has the following Workers Expression: skills HAS "sales".

TaskRouter maintains a list of Workers associated with each queue. Here, TaskRouter already knows all Workers which have the sales skill. While the Task is attempting to be assigned, TaskRouter will filter the Workers in the queue for anyone that is in an Available activity state. For multitasking Workspaces, TaskRouter will additionally filter the Workers for anyone who has capacity for the Task's channel.

To summarize: the routing step above will find any Worker in the "Just Sales" queue that is Available and has capacity on the Task's channel.

TaskRouter will create a pending Reservation for a Worker, choosing Workers in a "round robin" (i.e., a sequential cycle). The new Reservation is sent to the client application in three ways:

1. An initialized Worker on the JS SDK can subscribe to the reservation.created event
2. A reservation.created event will POST to the Event Callback URL
3. An assignment event will POST to the Assignment Callback URL

If the Reservation is accepted, the Task will continue to its following Task States.

If the Reservation doesn't succeed (i.e., the Reservation is rejected or it times out), the Workflow will check the timeout on the routing step. If the Task is still within the timeout, TaskRouter will attempt to assign the Task to any other matching Workers. Otherwise, if the Task is past the routing step timeout, the Task will flow to the next routing step or filter.

If the Worker moves to a different Available activity state to another while they have Reservations, the Reservations remain with that Worker. This means that a Worker may have Reservations that don't match their new activity state. Reservations stay with the Worker until they are accepted, rejected, or time out.

Suppose a Task is created for the Workflow defined above with the following attributes:

1
{
2
    "type": "Support",
3
    "preferred_agents": ["agent01","agent04"]
4
}

First, the Task would check against the "Support Calls" expression: type==\"Support\"" and succeed.

Support Filter:

1
{
2
    "expression": "type==\"Support\"",
3
    "filter_friendly_name": "Support Calls",
4
    "targets": [{
5
        "queue": <Just Support>,
6
        "timeout": 15,
7
        "expression": "worker.id IN task.preferred_agents"
8
    },{
9
        "timeout": 15
10
    }]
11
}

Similar to the Sales example above, TaskRouter will first find any Worker in the "Just Support" queue that is Available and has capacity on the Task's channel.

In addition, this routing step has an expression to match a subset of the Workers within the "Just Support' queue. As a result, TaskRouter will only generate a reservation for the Worker identified by "agent01" or "agent04" as a Worker attribute.

Suppose our support Task is a voice call, and both "agent01" and "agent04" Workers are already on a call. If those Workers have their voice capacity set to 1, this Task will continue to wait for the 15 seconds timeout.

1
{
2
    "expression": "preferred_agents != null",
3
    "filter_friendly_name": "Preferred Agents",
4
    "targets": [{
5
        "queue": <Everyone>,
6
        "expression": "worker.id IN task.preferred_agents",
7
        "timeout": 15
8
    }]
9
}

After timeout, the Task will progress to the next routing step:

1
{
2
    "timeout": 15
3
}

Although that step doesn't contain a lot of detail, here is how that is rendered in Console:

Expand image

This second step has inherited the previous step's queue, but this time no matching workers expression is applied — any Available Worker can match. Therefore this step behaves similarly to the Sales filter from the previous section.

Filter Summary: TaskRouter will first find any Available Worker in the "Just Support" queue with voice capacity who has "agent01" or "agent04" as their ID. After 15 seconds without a match, TaskRouter will expand the search to anyone in the same queue for another 15 seconds.

In addition to the standard Workflow features mentioned here, there are additional features that impact how a Task finds a matching Worker.

• Worker Ordering — Influencing the sort of which Worker is selected if multiple match the routing step
• Skip Timeout — Moving to the next routing step if a matching Worker isn't immediately found
• Multi-reservation — Sending multiple Reservations simultaneously. First accepted gets the Task.