Purpose
The evaluation task controls the job execution path depending on run-time conditions.
Figure 1: Evaluation Task
If the evaluation condition is met, the task returns true on output and execution continues down any success transitions bound to the task.
Figure 2: Evaluation Task Output Success
If the evaluation condition is not met, the task returns undefined on output by convention and execution continues down any failure transitions bound to the task.
Figure 3: Evaluation Task Output Failure
Properties
Single Evaluation
An evaluation is a single expression consisting of a left operand, a comparison operator, and a right operand. The left operand is compared to the right operand yielding either true or false. Note that if the yield is false, undefined is returned as the output by convention.
- Select the Location and Value for the left operand.
- It may come from a job variable, a static value, or an earlier task's outgoing variable.
- If the operand location is a job variable or earlier task, the operand value shows a dropdown of available variable names for selection.
- If the operand location is static, the operand value becomes a text edit box where you can type a value.
- Enter a query in the Query field. Query syntax follows that of the workflow operation query task. The left Operand Location and Operand Value fields define the object to query, the Query field specifies the query to execute, and the query result becomes our left operand.
- Select the Location and Value of the right operand.
- It may come from a job variable, a static value, or an earlier task's outgoing variable.
- If the operand location is a job variable or earlier task, the operand value shows a dropdown of available variable names for selection.
- If the operand location is static, the operand value becomes a text edit box where you can type a value.
runEvaluation Tasks
Operators are overloaded to match the data types they compare. The following table displays how the Workflow (WF) evaluation tasks function on a per data type basis.
| Left Operand Data Type | Operator | Right Operand Data Type | Comparison |
|---|---|---|---|
| string | contains | string | True if right operand is a sub-string of left operand. String patterns from the JavaScript RegExp Library can be used also. RegExp are only supported in static operand locations. We do not support template variables for the right operand. The RegExp will only work when the Operator uses contains or !contains and the Operand Location is set to static. ⚠ Important: A string of all numbers in the right operand will interpret as a number and will not follow the regExp rules defined here. |
| boolean | contains | boolean | There is no contains evaluation for booleans so this will do equality tests (true if left operand == right operand). |
| number | contains | number | Evaluate to true based on whether the modulus operation returns a remainder or not. If there is a remainder, it returns false; it returns true otherwise. Examples: Left operand = 4 and Right operand =2 returns true because 4%2=0 Left operand = 5 and right operand = 2 returns false because 5%2=1. |
| array | contains | string boolean number | True if the right operand is an element in the left operand array. |
| array | contains | object array | Contains uses the inherent indexOf method so these always return false due to how arrays handle complex objects. |
| object | contains | string | If no "query" parameter is sent in with the evaluation, this will check if the there is a property in the left operand that contains the text of the right operand Example: left Operand : {"color": "red"}, right operand: "col" : this will return true because there is a property name "color" in the left operand that contains the value "col". |
| object | contains | string number object array | If a "query" parameter is sent in with the evaluation, it will check if there is a property name in the left operand with the provided query value and check whether its value contains the right operand. Example: left operand: {"color" : "reddish-brown"}, query: "color" right operand: "red" This will return true because there is a property in the left operand named "color" and it's value (reddish-brown) contains the right operand value (red). |
| Left Operand Data Type | Operator | Right Operand Data Type | Comparison |
|---|---|---|---|
| string | !contains | string | True if the right operand is not a sub-string of left operand. |
| boolean | !contains | boolean | There is no !contains evaluation for booleans so this will do inequality tests (true if left operand != right operand). |
| number | !contains | number | Evaluate to true based on whether the modulus operation returns a remainder or not. If there is a remainder, it returns true; returns false otherwise. Examples: Left operand = 4 and Right operand =2 returns false because 4%2=0 Left operand = 5 and right operand = 2 returns true because 5%2=1. |
| array | !contains | string boolean number | False if the right operand is an element in the left operand array. |
| array | !contains | object array | Contains uses the inherent indexOf method so these always return false due to how arrays handle complex objects. |
| object | !contains | string | If no "query" parameter is sent in with the evaluation, this will check if the there is a property in the left operand that contains the text of the right operand. Example: left Operand : {"color": "red"}, right operand: "col" : this will return false because there is a property name "color" in the left operand that contains the value "col" left Operand : {"color": "red"}, right operand: "abcd" : this will return true because there is no property in the left operand with a name that contains the value "abcd". |
| object | !contains | string number object array | If a "query" parameter is sent in with the evaluation, it will check if there is a property name in the left operand with the provided query value and check whether its value contains the right operand. Example: left operand: {"color" : "reddish-brown"}, query: "color" right operand: "blue" This will return true because there is a property in the left operand named "color" and it's value (reddish-brown) does not contain the right operand value (blue). |
| Left Operand Data Type | Operator | Right Operand Data Type | Comparison |
|---|---|---|---|
| string | > | string | Does evaluations based on lexicographical ordering. See Wikipedia - Lexicographical Order for details on how lexicographical ordering works. Examples: "aa" > "ab" returns false "ab" > "aa" returns true. |
| boolean | > | boolean | True is always > than false. |
| number | > | number | Returns true if the left operand is > the right operand. |
| array | > | number | Returns true if the number in the right operand is > the length of the left operand array. |
| array | > | array | Returns true if the length of the left operand array is > the length of the right operand array. |
| object | > | any data type | Always returns false. |
| Left Operand Data Type | Operator | Right Operand Data Type | Comparison |
|---|---|---|---|
| string | < | string | Does evaluations based on lexicographical ordering. See Wikipedia - Lexicographical Order for details on how lexicographical ordering works. Examples: "aa" < "ab" returns true "ab" < "aa" returns false. |
| boolean | < | boolean | False is always < true. |
| number | < | number | Returns true if the left operand value is < the right operand value. |
| array | < | number | Returns true if the number in the right operand is < the length of the left operand array. |
| array | < | array | Returns true if the length of the left operand array is < the length of the right operand array. |
| object | < | any data type | Always returns false. |
| Left Operand Data Type | Operator | Right Operand Data Type | Comparison |
|---|---|---|---|
| string | == | string | Returns true if the 2 strings are equal. |
| boolean | == | boolean | Returns true if the 2 booleans are equal. |
| number | == | number | Returns true if the 2 numbers are equal. |
| array | == | number | Returns true if the right operand number is the exact length of the left operand array. |
| array | == | array | Returns true if the length of the right operand array is the exact length of the left operand array. |
| object | == | object | Returns true if the 2 objects are deeply equal (same properties and values). |
| Left Operand Data Type | Operator | Right Operand Data Type | Comparison |
|---|---|---|---|
| string | != | string | Returns true if the 2 strings are not equal. |
| boolean | != | boolean | Returns true if the 2 booleans are not equal. |
| number | != | number | Returns true if the 2 numbers are not equal. |
| array | != | number | Returns true if the right operand number is not the exact length of the left operand array. |
| array | != | array | Returns true if the length of the right operand array is not the exact length of the left operand array. |
| object | != | object | Returns true if the 2 objects are not deeply equal (same properties and values). |
| Left Operand Data Type | Operator | Right Operand Data Type | Comparison |
|---|---|---|---|
| string | >= | string | Does evaluations based on lexicographical ordering. Wikipedia - Lexicographical Order for details on how lexicographical ordering works Examples: "aa" >= "aa" returns true because "aa" is not > "aa" but it is equal "ab" >= "aa" returns true. |
| boolean | >= | boolean | True is always > false. |
| number | >= | number | Returns true if the left operand is >= the right operand. |
| array | >= | number | Returns true if the right operand number is >= the length of the left operand array. |
| array | >= | array | Returns true if the length of the right operand array is >= the length of the left operand array. |
| object | >= | object | Always returns false. |
| Left Operand Data Type | Operator | Right Operand Data Type | Comparison |
|---|---|---|---|
| string | <= | string | Does evaluations based on lexicographical ordering. See Wikipedia - Lexicographical Order for details on how lexicographical ordering works Examples: "aa" <= "aa" returns true because "aa" is not < "aa" but it is equal "aa" <= "ab" returns true. |
| boolean | <= | boolean | True is always > false. |
| number | <= | number | Returns true if the left operand is <= the right operand. |
| array | <= | number | Returns true if the right operand number is <= the length of the left operand array. |
| array | <= | array | Returns true if the length of the right operand array is <= the length of the left operand array. |
| object | <= | object | Always returns false. |
Evaluation Groups
- One or more evaluations can be combined into an evaluation group. The evaluation group resolves to true or false by logically combining its evaluations' results.
- Specify how to combine evaluations in the group's "If [any/all] of the following are met" setting.
- When set to any, the evaluation group is true if one or more of its evaluations have a true condition.
- When set to all, the evaluation group is true only if all of its evaluations have a true condition.
Final Evaluation
- The evaluation task resolves to true or false by logically combining its evaluation groups.
- Specify how to combine evaluation groups in the task's "If [any/all] of the following are met" setting.
- When set to any, the evaluation task is true if one or more of its evaluation groups have a true condition.
- When set to all, the evaluation task is true only if all of its evaluations groups have a true condition.
The following table provides sample evaluation conditions and the result.
| Left Operand | Operator | Right Operand | Results |
|---|---|---|---|
| "er1.atl" | contains | "atl" | T |
| "er1.atl" | contains | "ATL" | F |
| [ "cr1.atl", "er1.atl" ] | contains | "er1.atl" | T |
| [ "cr1.atl", "er1.atl" ] | contains | "atl" | F |
| { "name": "apple", "color": "red" } | contains | "color" | T |
| { "name": "apple", "color": "red" } | contains | "apple" | F |
| a1111z | contains | a[\d][\d][\d][\d]z] | T |
| a1111z | contains | a[\D][\D][\D][\D]z] | F |
| a1111z | contains | a[\d]+z | T |
| a1111z | contains | a[\D]+z | F |
| white space | contains | [\s] | T |
| white space | contains | ^ [\s]$ | F |
| 4 | > | 2 | T |
| 1 | > | 2 | F |
| true | > | false | T |
| true | > | 0 | F |
| 1 | > | false | F |
| false | > | true | F |
| "chassis" | > | "card" | error |
| "chassis" | > | 4 | F |
| "code" | > | "card" | error |
| "code" | > | "17" | F |
| [ "cr1.atl", "er1.atl" ] | > | 1 | T |
| [ "cr1.atl", "er1.atl" ] | > | [ "cr2.atl" ] | T |
| [ "cr1.atl", "er1.atl" ] | > | 3 | F |
| 6 | < | 9 | T |
| 9 | < | 6 | F |
| false | < | true | T |
| false | < | TRUE | T |
| false | < | 5 | F |
| true | < | false | F |
| "card" | < | "chassis" | error |
| "card" | < | 5 | F |
| "code" | < | "card" | error |
| [ "cr1.atl", "er1.atl" ] | < | 3 | T |
| [ "cr2.atl" ] | < | [ "cr1.atl", "er1.atl" ] | T |
| [ "cr1.atl", "er1.atl" ] | < | 1 | F |
| 6 | == | 6 | T |
| 6 | == | "6" | T |
| 6 | == | 7 | F |
| false | == | false | T |
| false | == | FALSE | T |
| false | == | "FALSE" | T |
| true | == | false | F |
| "card" | == | "card" | T |
| "card" | == | "chassis" | F |
| "card" | == | "code" | F |
| [ "cr1.atl", "er1.atl" ] | == | [ "cr1.atl", "er1.atl" ] | T |
| [ "cr1.atl", "er1.atl" ] | == | [ "er1.atl", "cr1.atl" ] | T |
| [ "cr1.atl", "er1.atl" ] | == | [ "cr1.atl", "cr2.atl" ] | T |
| [ "cr1.atl", "er1.atl" ] | == | [ "cr1.atl" ] | F |
| [ "cr1.atl", "er1.atl" ] | == | [ "cr1.atl", "cr1.atl", "cr1.atl" ] | F |
| { "name": "cr1.atl", "ned": "cisco-ios-xr", "slots" = 8 } | == | { "name": "cr1.atl", "ned": "cisco-ios-xr", "slots" = 8 } | T |
| { "name": "cr1.atl", "ned": "cisco-ios-xr", "slots" = 8 } | == | { "name": "cr1.atl", "ned": "cisco-ios-xr", "slots" = "8" } | F |
| { "name": "cr1.atl", "ned": "cisco-ios-xr", "slots" = 8 } | == | { "name": "cr2.atl", "ned": "cisco-ios-xr", "slots" = 8 } | F |
| 6 | != | 7 | T |
| 6 | != | 6 | F |
| 6 | != | "6" | F |
| true | != | false | T |
| false | != | false | F |
| false | != | "FALSE" | F |
| "card" | != | "chassis" | T |
| "card" | != | "code" | T |
| "card" | != | "card" | F |
| [ "cr1.atl", "er1.atl" ] | != | [ "cr1.atl", "cr2.atl" ] | F |
| [ "cr1.atl", "er1.atl" ] | != | [ "er1.atl", "cr1.atl" ] | F |
| [ "cr1.atl", "er1.atl" ] | != | [ "cr1.atl", "er1.atl" ] | F |
| [ "cr1.atl", "er1.atl" ] | != | [ "cr1.atl" ] | T |
| [ "cr1.atl", "er1.atl" ] | != | [ "cr1.atl", "cr1.atl", "cr1.atl" ] | T |
| { "name": "cr1.atl", "ned": "cisco-ios-xr", "slots" = 8 } | != | { "name": "cr2.atl", "ned": "cisco-ios-xr", "slots" = 8 } | T |
| { "name": "cr1.atl", "ned": "cisco-ios-xr", "slots" = 8 } | != | { "name": "cr1.atl", "ned": "cisco-ios-xr", "slots" = 8 } | F |
| { "name": "cr1.atl", "ned": "cisco-ios-xr", "slots" = 8 } | != | { "name": "cr1.atl", "ned": "cisco-ios-xr", "slots" = "8" } | T |
| 4 | >= | 4 | T |
| 1 | >= | 2 | F |
| true | >= | true | T |
| false | >= | true | F |
| "FALSE" | >= | true | F |
| "chassis" | >= | "card" | error |
| "code" | >= | "card" | error |
| "code" | >= | 4 | F |
| "card" | >= | "chassis" | error |
| [ "cr1.atl", "er1.atl" ] | >= | 1 | T |
| [ "cr1.atl", "er1.atl" ] | >= | [ "cr2.atl" ] | T |
| [ "cr1.atl", "er1.atl" ] | >= | 3 | F |
| 6 | <= | 9 | T |
| 9 | <= | 6 | F |
| false | <= | true | T |
| FALSE | <= | "TruE" | T |
| false | <= | 0 | F |
| true | <= | false | F |
| true | <= | "FALsE" | F |
| "card" | <= | "chassis" | error |
| "code" | <= | "card" | error |
| "code" | <= | 3 | F |
| "code" | <= | 9 | F |
| "code" | <= | "3" | F |
| [ "cr1.atl", "er1.atl" ] | <= | 3 | T |
| [ "cr1.atl", "er1.atl" ] | <= | 1 | F |
| [ "cr1.atl", "er1.atl" ] | <= | [ "cr2.atl", "cr3.atl", "cr4.atl" ] | T |
| [ "cr1.atl", "er1.atl" ] | <= | [ "cr2.atl" ] | F |
References
For more information on using regular expression syntax: