Using the Conditions Utility
Depending on your business requirements you might want to route payments in EUR down one path, and payments in USD down another. You can also create multiple routes based on other available data, from payment status down to individual e-mail addresses if you would want to.
The Conditions Utility enables you to create all these conditions.
Conditions are used to evaluate if a certain path should be followed during the execution of the workflow. They are based on selecting a field (for example: Currency), an operator (for example: equals), and a value (for example: EUR).
Build conditions only on fields that will be present at runtime. If you build conditions on fields that aren't always present, you might risk unintended consequences. Be sure to test conditions accordingly so that they lead to the right route being followed. You can also use the "is (not) empty" operator to add explicit checks for the presence of fields.
Available fields
Available fields for any condition depend on the Outputs from previous blocks. A condition can use information from any block upstream, like the amount and currency for a payment, or a link to a created ticket with Freshdesk.
Available operators
The available operators to evaluate a condition depend on the data type of the field. For some data types and operators a setting to either use a case-sensitive or a not case-sensitive comparison is available too.
Supported operators are:
| Operator | Description | Example |
|---|---|---|
| Equal | The value passed in must be equal to the value set up in the condition. | "Currency equals 'EUR'" or "Order status equals 'CONFIRMED'" |
| Not equal | The value passed in must be different to the value set up in the condition. | "City does not equal 'test'" or "Product category does not equal 'gift card'" |
| Greater than or equal | The value passed in must be greater than or equal to the value set up in the condition. | "Amount is greater than or equal to 100" or "discount amount is greater than or equal to 15** |
| Less than or equal | The value passed in must be less than or equal to the value set up in the condition. | "Risk score is less than or equal to 50" or "quantity is *less than or equal** to 10" |
| One of | If multiple options are set up, either one will be accepted to follow the route for this condition. | "Currency is one of EUR, GBP, USD" will evaluate to true for GBP, but not for NOK. |
| Not one of | If multiple options are set up, any one will stop the route from being followed for this condition. | "Currency is not one of EUR, GBP, USD" will follow NOK payments, but not EUR, GBP, or USD. |
| Between | Evaluates if a numeric value is between two other values. The range is inclusive of the values entered. | "Amount is between 30 and 90" or "risk score is between 51 and 100" |
| Contains | The value set up in the condition must be part of the variable it's compared with. | "Email contains '@primer.io'" or "Product title contains 'testproduct'" |
| Does not contain | The value set up in the condition must not be part of the variable it's compared with. | "Statement descriptor does not contain 'Authorization'" or "Discount code does not contain 'XMAS'" |
| Is empty | Checks if the field set up in the condition has no value assigned to it or is missing. Good to know: For string values this could be an empty text or a null value, while for numbers "0" counts as not empty. | "Cancellation reason is empty" or "Zip code is empty" |
| Is not empty | Checks if the field set up in the condition is not missing and has a value assigned to it. Good to know: For string values this could be any value, while for numbers this includes "0". | "Mobile phone number is not empty" or "Customer note is not empty" |
Assign values
Values for the condition can either be entered manually (like e-mails) or select from a list of available values (like currencies or payment states), dependent on the data type of the selected field.
We also support comparing values to build routes comparing different fields, like issuing country with order country, or billing address zip code and shipping address zip code.
Using metadata for routing
One special type of conditions is based on unstructured data sent in via the metadata field attached to the Client Session when creating a payment. This field is used to send additional information with the payment outside of the available fields from the Payments API. This can also be used to attach information to create routes on, like custom risk scores or customer account status.
When using metadata for routing, make sure to specify the full path like in the example here.
1234567
"metadata": { "customObject": { "customField": "TEST" }, "accountStanding": "VIP", "internalRisk": "LOW",}
Condition evaluation
All conditions are evaluated together (AND) by default, meaning that if there are three conditions set up, like Amount>100, Currency=EUR, Payment Type=UNSCHEDULED, then all three need to be fulfilled for the path to be followed during workflow execution.
To avoid having to create too many routes based on specific conditions, you can also create groups of conditions by using the OR evaluation. In this example, a blocking route is created evaluating if a payment uses certain e-mail addresses or if a custom flag with the value "BLOCK" is sent in.
You can use multiple conditions in a group to achieve an outcome of (A AND B) OR (C) OR (D AND E) OR (F AND G AND H).
It is not possible to nest these groups further, but the ability to use trigger conditions, multiple condition builders, and multiple routes already gives you a lot of opportunity for complex branching.
Conditions are evaluated top down
Creating multiple sets of conditions is a great way to branch a workflow into multiple routes. Each block can have its own name, making it easier to keep track, as well as debug the workflow log.
When multiple sets are used, they are evaluated from top to bottom. In this example, first the conditions within the email block will be checked and if they match, that path will be taken. Otherwise, the conditions within “recurring payments” will be checked, and so on until the “all other conditions” block at the bottom is reached.
You need to put the most specific routes on top and getting more generic towards the bottom. If you create a route with “Currency=EUR” first and then a second one with “Currency=EUR AND Risk=high” below, then the second one will never be evaluated.
All other conditions
When the Conditions Utility is used within a workflow, then a fallback condition called “all other conditions” is always at the bottom. This could be used as an else path, creating a route that is set up more generic than the specialized routes above, or could also be left empty. If left empty and the Workflow Run reaches this condition, the workflow will still end with as the workflow ended without a failure.
Duplicate a route
If you have to set up multiple similar routes where only some of the inputs change (like different processors for different markets) then you can use the menu within the condition block to duplicate the route. A new copy will be created below the original, retaining all conditions and assigned blocks.
Trigger Conditions define when to start a workflow
It is perfectly valid to have more than one published workflows based on the same trigger. However, if you want to start each workflow only in very specific cases, be sure to set up the Trigger accordingly.
If an event is sent that would trigger a workflow, but the conditions prevent that workflow from being started, then the workflow will neither run nor create a record in the Runs section, because the conditions do not apply.
Conditions within a workflow are evaluated top to bottom, but this logic does not apply to Triggers with Conditions as each workflow is evaluated independently.
Use explicitly
We recommend being very specific about how to use the Trigger Conditions to avoid unnecessarily starting unrelated workflows.
If there are two workflows for Cards & Klarna, they can have a triggering condition where for one the payment method is explicitly set to cards, and for the other it’s explicitly set to Klarna. Now each workflow only gets started, when the right payment method is used.
Best practices
Head over to the best practices guide to see our recommendations on how to use create granular flows based on distinct use cases.