Understanding flow states
Zendesk Integration Services (ZIS) uses a JSON-based, structured language similar to Amazon States Language to define an integration. This language can define states in ZIS such as performing tasks, determining which states to transition to next, and stopping an execution with an error. A ZIS flow is made up of one or more states.
State types
ZIS supports the following state types:
- Action - Performs a task, such as transforming data or making a REST API call. See Action state
- Choice - Adds conditional branching to a flow. See Choice state
- Map - Enables looping or iterating over a set of input data. See Map state
- Wait - Pauses for the specified number of seconds before transitioning to the next state. See Wait state
- Succeed - Stops the flow in cases that are considered successful and passes a developer-defined message to the integration logs. Example: When a Choice state indicates no further action is required. See Succeed state
- Fail - Stops the flow in cases that are considered errors and passes a developer-defined message to the integration logs. Example: When a Choice state finds an invalid input value. See Fail state
- Pass - Passing a step's input to its output without doing any work. It can optionally add data to the output. Example: To mockup the result of a Choice or Action state for testing or debugging purposes. See Pass state
Common state properties
Most states support the following properties.
Name | Type | Mandatory | Description |
---|---|---|---|
Type | string | true | The state's type. For supported values, see State types. All states require Type |
Next | string | Most state types require either Next or End | Next state to run in the ZIS flow. You can't use Next and End in the same state. The Fail and Succeed state types don't support Next . The Choice state type supports multiple Next properties |
End | boolean | Most state types require either Next or End | If true, the state is terminal and ends the ZIS flow. A flow can contain multiple terminal states. End doesn't support a value of false. The Choice, Fail, and Succeed state types don't support End as they are implied terminal states |
Comment | string | false | Human-readable comment |
InputPath | string | false | JSONPath to a part of the state's input. The state can only access this part of the input. Defaults to "$", the entire input. The Action and Succeed state types don't support InputPath |
ResultPath | string | false | Reference path used to the store the state's output. Later states of the ZIS flow can access the output at this path. The state's output is further filtered by OutputPath , if provided. Defaults to "$", which replaces the state's input with its output. The Choice, Fail, Succeed, and Wait state types don't support ResultPath |
OutputPath | string | false | JSONPath to a part of the state's output. The state only passes this part of the output to the next state. Defaults to "$", the entire output. The Action and Succeed state types don't support OutputPath |
For example, the following state includes the Comment
, Type
, ResultPath
, and Next
properties.
"SlackSettings.LoadConfig": {
"Comment": "Loads the Slack channel and ticket priority settings",
"Type": "Action",
"ActionName": "zis:common:action:LoadConfig",
"Parameters": {
"scope": "slack_settings"
},
"ResultPath": "$.config_result",
"Next": "NextState"
}
Accessing data in a state
ZIS flows have access to a top-level $
JSON object. The object contains data
about the event that triggered the flow, the flow's integration, and the
Zendesk account. Example:
{
"account_id": 123456,
"integration_key": "zis_example_integration",
"subdomain": "acme",
"input": {
...
}
}
For more information about the $
object's schema, see the reference
documentation.
Reference paths
Some state properties can access or modify the $
object using a reference
path. A reference path is a JSONPath
string that points to a single node of the $
object. The node must be a single
value, an array, or an object.
Reference paths always start with $
. To reference the entire $
object, use
the $
reference path.
For example, the following Choice state's Variable
property reads data from
the $.subdomain
reference path. When the state runs, ZIS replaces the path
with its referenced value. In this case, the path's value is the Zendesk subdomain of the account running the ZIS flow.
"choice.checkSubdomain": {
"Type": "Choice",
"Choices": [
{
"Not": {
"Variable": "$.subdomain",
"StringEquals": "acme-production"
},
"Next": "ErrorStep"
}
],
"Default": "NextStep"
}
As another example, the following Pass state's ResultPath
property writes data
to the $.comment_id
reference path, overwriting any existing data for the $
object's comment_id
property.
"Pass.GetCommentId": {
"Type": "Pass",
"Result": {
"commentId": "123456"
},
"ResultPath": "$.comment_id",
"Next": "NextStep"
}
Path placeholders
Some state properties support a mix of static JSON and path placeholders. This
lets you interpolate data from the $
object into the property's value.
To create a path placeholder, wrap a reference path in double curly brackets
({{ }}
). When the state runs, ZIS replaces the placeholder with the reference
path's value.
For example, the following Succeed state contains a Message
property. The
property contains a path placeholder for the integration's key.
"Logs.Succeeded": {
"Type": "Succeed",
"Message": "Message posted for integration: {{$.integration_key}}"
}
State limitations
The documentation for each state type includes known limitations and differences from the Amazon States Language. ZIS flows also have the following limitations:
-
ZIS flows don't support the Parallel state type. ZIS flows don't support concurrent execution.
-
ZIS flows don't support the Task state type. Use an Action state instead.
-
ZIS flow states don't support intrinsic functions.
-
ZIS flows have limited support for retries. See Flow states retry and error handling.