TaskRouter uses a SQL-like expression syntax for binding Workers to TaskQueues and filtering Tasks into TaskQueues in a Workflow configuration. Expressions are composed of constants, JSON keys, as well as logical and comparison operators.
For example, a TaskQueue TargetWorkers expression looks like:
(skills HAS 'support') AND (languages HAS 'english')
And a Workflow filter expression looks like:
customer_value == 'Gold' AND type == 'ticket'
Expressions are made up of simple comparisons of constants and/or JSON keys, grouped together by parenthesis and logical operators.
Examples:
1 == 1
0 != 1
"apple" != "orange"
key > 1
object.param != "apple"
language IN ["en", "es"]
(condition_a == true) OR (condition_b == true)
(language == "en" OR language == "fr") AND skill_rating >= 5.1
There are 3 types of constants supported:
"string"
or
'string'
.
1
,
1.0
,
1.00
,
3.141529
true
or
false
.
Constants can be the left or right values of a comparison operator.
References to JSON object keys can also exist in the expression. These are resolved against the JSON document (Worker or Task attributes), and the value from the JSON is substituted. Keys are used as unquoted strings, using dot notation to reference sub-properties and square brackets to reference array indices. If the document does not contain the requested key, it resolves to NULL.
Given the Task attributes:
1{2"string_const": "foo",3"object": {4"array": ["a","b","c"],5"attr": "bar"6}7}
The following are valid keys in a Workflow configuration, and would resolve as follows:
string_const
- a string that resolves to
"foo"
object.array
- an array that resolves to
["a","b","c"]
object.array[2]
- a string that resolves to
"c"
object.attr
- a string that resolves to
"bar"
Comparison operators compare two constants and return true
or false
. Comparisons between different types should be avoided. Scalar operators can compare two scalar values (i.e. not arrays). Array operators can have Arrays as one side of the operation.
Valid scalar operators are:
> greater than
>= greater than or equal to
== equals
!= does not equal
<= less than or equal to
< less than
CONTAINS
- does the scalar value on the left contain the scalar value on the right.
Valid array operators are:
HAS
- does Array on the left contain the value on the right
IN
- does the scalar value on the left exist in the array on the right.
NOT IN
- does the scalar value on the left not exist in the array on the right.
Using scalar operators on Arrays results in false
. Using array operators on two scalar values also returns false
.
Compares the results of sub-expressions to the left and right and return true
or false
based on the operand. Parenthesis can be used to group sub-expressions.
Valid logical Operators
AND
- if both the left and right subexpressions are true, resolves to
true
; otherwise
false
OR
- if one or both of the left or right subexpressions are true, resolves to
true
; otherwise
false
Expressions are used in three primary places to manage the assignment of Tasks to Workers:
The definition of a TaskQueue
A Workflow filter to find matching Tasks (filter:
in a Workflow configuration JSON)
A routing step expression to match Workers to a Task (target.expression:
in a Workflow configuration JSON)
task.
or
worker.
sid
,
friendly_name
,
activity_sid
, or
activity_name
.