Documentation API Reference

Understanding flow states

Zendesk Integration Services (ZIS) uses a JSON-based, structured language similar toAmazon States Languageto 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. SeeAction state
  • Choice - Adds conditional branching to a flow. SeeChoice 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. SeeWait 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. SeeSucceed state
  • 失败——停止流动的情况下考虑errors and passes a developer-defined message to the integration logs. Example: When a Choice state finds an invalid input value. SeeFail 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. SeePass state

Common state properties

Most states support the following properties.

Name Type Mandatory Description
Type string true The state's type. For supported values, seeState types. All states requireType
Next string Most state types require eitherNextorEnd Next state to run in the ZIS flow. You can't useNextandEndin the same state. The Fail and Succeed state types don't supportNext. The Choice state type supports multipleNextproperties
End boolean Most state types require eitherNextorEnd If true, the state is terminal and ends the ZIS flow. A flow can contain multiple terminal states.Enddoesn't support a value of false. The Choice, Fail, and Succeed state types don't supportEnd
Comment string false Human-readable comment
InputPath string false JSONPathto 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 supportInputPath
ResultPath string false Reference pathused 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 byOutputPath, if provided. Defaults to "$", which replaces the state's input with its output. The Choice, Fail, Succeed, and Wait state types don't supportResultPath
OutputPath string false JSONPathto 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 supportOutputPath

For example, the following state includes theComment,Type,ResultPath, andNextproperties.

             

              
"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 thereference documentation.

Reference paths

Some state properties can access or modify the$object using a reference path. A reference path is aJSONPathstring 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$参考路径。

For example, the following Choice state'sVariableproperty reads data from the$.subdomain参考路径。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'sResultPathproperty writes data to the$.comment_idreference path, overwriting any existing data for the$object'scomment_idproperty.

             

              
"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 aMessageproperty. 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: