Assert a chain result

The Assert event is a debugging tool, similar to the Conditional event, that tests the logic of your chain and validates it works as intended. At the most basic level, a chain branch will continue uninterrupted when an assertion passes and stop when an assertion fails — but there are a number of conditions that affect this rule. You can find a list of common use cases at the bottom of this article.

Step 1: Add the event to the chain

1. In Chain Builder, from the Chains  device_hub tab, click Edit create for the chain.
2. Click Chain Eventsevent, and move Assert to where the event should occur in the chain.
3. Drag a link to the event from the preceding node in the chain.

   Note: To change a node's position in the chain, unlink it from other nodes, and then move it to where it should occur. To move multiple nodes at once, hold SHIFT as you select them.

4. Select the event's node, and click Edit  create.
5. Under Basic Info, enter a unique name and description to help identify the event.
   

   Note: Enable Stop Chain on Fail if the entire chain should halt when this assertion fails. If left unchecked, other chain branches will run to completion even if this particular one fails.

Step 2: Set up the conditional logic

Under Conditions, build the conditional logic as rules or groups of rules to test outputs and variables of various data types:

• String, for one or more characters
• Integer, for any whole, non-decimal numeric value
• Date, for a date string or variable
• Float, for any numeric value
• JSON, for Javascript Object Notation

  Note: For JSON, use a variable transformation to parse values.

1. Select whether to add a Rule or Group of rules.
   
2. If you include multiple rules or groups, join them with an AND or OR boolean:
   • If all rules or groups must be true for the condition to pass, select AND.
   • If any rule or group must be true for the condition to pass, select OR.
3. For each rule, select the type of data and the output or variable to test, and set its criteria to pass the condition:
   • To test whether the value is blank, select Is blank or Is not blank.
   • To test whether the value includes specific characters or another output or variable value, select Contains, and enter or select the value to match. 
   • To test whether the value meets a regular expression, select Matches RegExp, and enter the expression to match.
   • To test whether the value starts or ends with specific characters or another output or variable value, select Start with or Ends with, and enter or select the value to match.
   • To test whether a numeric value equals an amount, select = or !=, and enter or select the amount.
   • To test whether a numeric value is greater or less than an amount, select < or >, and enter or select the amount.
   • To test whether a numeric value is greater or less than or equal to an amount, select <= or >=, and enter or select the amount.
4. After you set up the conditional logic, click Save.

Note: To remove a rule from the conditional logic, click Delete delete.

Conditions and common use cases

The Assert event can be added to multiple paths or "branches" of a chain. Each assertion operates independently, meaning a failed assertion will halt only the particular branch where it is placed — all other branches will continue to run to completion. However, if any single assertion fails then the entire chain will be marked as "Failed."

Things to know:

• Enable the Stop chain on fail option to immediately halt the entire chain when an assertion fails.
• You can override a chain failure by adding a Set Chain Result event. When a Set Chain Result node is set to "Succeed," the chain will always pass regardless of any failed assertions.
  
  

Condition	Result	Explanation
Assertion passes	Run continues; Chain succeeds	The chain run continues without interruption.
Assertion fails (single assertion)	Run fails; Chain fails	When a single assertion is placed on a chain path, the chain run stops when the assertion fails. Example: (Click to enlarge) Note: An assert event can be used as a "guard" that stops a chain before critical points if a condition is not met. When an Assert event is a dependency of the subsequent nodes, the entire chain will halt.
Assertion fails (with "Stop Chain on Fail" enabled)	Run fails; Chain fails; Chain halts immediately	When the ""Stop Chain on Fail" option is enabled and that assertion fails, all other branches are immediately halted. Example: (Click to enlarge)
Assertion fails (multiple branches/ assertions)	The chain run halts on the failed branch, but continues for all other branches until a Guard/Stop condition is met; Chain fails	The Assert event can be placed on multiple paths or "branches" within the same chain. A failed assertion will halt that particular branch, but all other branches will continue to run. This allows you to test multiple conditions within the same chain. Example: (Click to enlarge)

Assert event vs. Conditional event

The Conditional event, when combined with the Set Chain Result event, can be used to achieve similar results — but multiple nodes and branching paths are required vis-à-vis the Assert event. The Assert event is intended to simplify and replace this more complex process.

To demonstrate, here's an example of the typical logic required to recreate a "Pass" and "Fail" branch with a Conditional event:

And here is the same logic using a single Assert event:

Note: When used on the same chain, the Set Chain Result event will always override the results of an Assert event. For example, a chain with a Set Chain Result node that is set to "Succeed" will always pass regardless of the Assert event.