Action state

An Action state performs a task in a ZIS flow. For example, you can use an Action state to transform data in a flow or make a REST API call.

This example shows how the built-in jq transform action can convert the ticket id to a string format within the flow.

"TransformTicketIdToString": {
  "Type": "Action",
  "ActionName": "zis:common:transform:Jq",
  "Parameters": {
  "Parameters": {
    "expr": ".ticket_event.ticket.id | tostring",
    "data.$": "$.input"
  },
  "ResultPath": "$.transformed.ticket.id",
  "Next": "NextState"
}

Action types

The Action state supports two types of actions:

• Built-in actions
• Custom actions

Built-in actions are predefined requests for common tasks. For example, you can use a built-in action to load data from a ZIS config or transform data using jq.

A custom action is a wrapper for an HTTP request. You can use a custom action to perform a task not covered by a built-in action. For example, you can make a request to a Zendesk API or a third-party service, such as Slack or Shopify. To use a custom action, you must define the action as a separate resource in the ZIS bundle. For more information, see ZIS custom actions.

Supported properties

In addition to common state properties, an Action state supports the following properties.

Name	Type	Mandatory	Description
ActionName	string	true	Name of the action. For built-in actions, the name is predefined. For custom actions, the name is based on the action definition
Parameters	object	false	Parameters to pass to the action. For built-in actions, supported parameters are predefined. For custom actions, you define supported parameters in the action definition. Parameters values support reference paths and path placeholders. See Using reference paths in action parameters
Catch	array of objects	false	Contains a fallback state to run if the Action state encounters a runtime error. See Flow states retry and error handling

Using paths in action parameters

To use a reference path or path placeholder in a Parameters property value, the property key must end with .$. When running the action, ZIS renames the property to strip out the .$ suffix.

For example, the following LoadLinks action passes the "$.accountId" reference path in the left_object_name parameter.

"LoadLinks": {
    "Type": "Action",
    "ActionName": "zis:common:action:LoadLinks",
    "Parameters": {
        "link_type": "account_to_organization_link",
        "left_object_name.$": "$.accountId"
    },
    "ResultPath": "$.link_results",
    "Next": "NextState"
}

As another example, the following custom action uses an "{{$.input.user_event.user.email}}" path placeholder in the message parameter.

"PostNewUserMessage": {
  "Type": "Action",
  "ActionName": "zis:example_integration:action:PostMessage",
  "Parameters": {
    "message.$": "New user created for {{$.input.user_event.user.email}}"
  },
  "Next": "NextState"
}

Limitations

• A ZIS Action state doesn't support the Retry property from the Amazon States Language's Task state. Instead, ZIS uses a built-in retry logic for failed flows. Alternatively, you can use a Catch block to handle runtime errors in an Action state. See Flow states retry and error handling.