Understanding Zendesk Integration Services

Zendesk Integration Services (ZIS) is a group of services that simplify building and running an integration for Zendesk. This can include data synchronization between Zendesk and external systems, providing a backend (business logic) for Zendesk apps, or triggering automated workflows in another system.

Building an integration with ZIS provides the following benefits:

• A quicker and easier process to develop integrations
• Reduces the need for externally-hosted middleware thereby reducing the cost and effort of managing the infrastructure an integration is hosted on
• Leverages new features and enhancements to the ZIS platform as they’re rolled out
• Provides a common user experience across different integrations

ZIS services

At the core of ZIS is a workflow runner. It listens for an event in one system, and responds by taking action in another system. Event-driven data flows can be bi-directional, either from Zendesk to an external system, or vice versa.

ZIS provides the following services to support this functionality:

• ZIS Registry Service: Creates an integration, stores the workflow definitions and other resources for your integration
• ZIS Connections Service: Fetch, store, and manage API credentials for Zendesk and third-party services
• ZIS Configs Service: Stores user-specific configuration data for your integration
• ZIS Links Service: Stores relationships between entities. Example: For an integration with synced data to Jira, ZIS Links stores a link between a Jira issue and a Zendesk ticket. Refer to ZIS Links
• ZIS Inbound Webhooks Service: Trigger workflows in ZIS from external systems

Understanding ZIS bundle and resources

ZIS resources consist of ZIS flows, ZIS actions, and job specs. They are the fundamental components of a ZIS-based integration.

A ZIS bundle is a declaration of ZIS resources used in an integration. An integration is deployed when a bundle is uploaded to the ZIS Registry Service. See Anatomy of a ZIS bundle for more information.

ZIS flows

A ZIS flow object describes the logic behind a data flow as a state machine structure. It is defined in JSON and is based on the Amazon States Language.

A flow defines a number of steps and the order to execute them in. It allows flow controls like conditionals and provides the ability to pass data between states.

The following example shows a basic flow that runs a single action:

"example_flow": {
     "type": "ZIS::Flow",
     "properties": {
       "name": "example_flow",
       "definition": {
         "StartAt": "example_state",
         "States": {
           "example_state": {
             "Type": "Action",
             "ActionName": "zis:example_integration:action:example_action",
             "End": true
           }
         }
       }
     }
   }

Flow timeouts

Flows can only run for a set duration of 100 seconds. If a flow runs longer than this duration, the flow will be terminated. All states in the flow respect this timeout. If a flow times out midway through an action or Wait state, it will be terminated early.

Flow state transition limit

The execution of a ZIS flow can go through a maximum of 250 state transitions. This is something to be mindful of if your flow includes looping using a Map state.​​

ZIS actions

Actions are wrappers for HTTP requests. ZIS includes some built-in actions such as adding data to the ZIS Configs Service or performing simple data transformations. They can be referenced from a flow without having to be defined as a separate resource in your bundle. See ZIS built-in actions.

You can also define your own custom actions to perform tasks not provided by ZIS built-in actions. For example, making requests to public APIs for 3rd-party systems such as Slack or Shopify or making requests to Zendesk APIs that are not covered by our built-in actions. Custom actions could also be used to invoke an API call to a function hosted by the integration developer, creating an 'external action'. See ZIS custom actions.

Job specs

A Job Spec object tells ZIS which trigger event to listen for, and which flow to run when that event occurs. It specifies the event source and event type for the event and a flow that is triggered when that event occurs. Example:

"example_jobspec": {
  "type": "ZIS::JobSpec",
  "properties": {
    "name": "example_job_spec",
    "event_source": "support",
    "event_type": "ticket.TicketCreated",
    "flow_name": "zis:example_integration:flow:example_flow"
  }
}

Each job spec defines a relationship between one event and one flow. To associate multiple event types with the same flow, you need to create multiple job specs.

To learn about the types of events which can trigger flows, see Triggering ZIS flows.

Triggering ZIS flows

Flows in ZIS are triggered by events which are near-real-time notifications that something has happened. For example, a user has been created, a ticket’s status has changed, a custom object has been deleted, or a webhook has been received from an external system. There are three types of events:

• Native Zendesk events: Native Zendesk events are automatically published to ZIS. See Trigger events reference.
• Third party events: The trigger mechanism for third party events is the ZIS Inbound Webhook service, which you can configure to listen to events from an external system. See ZIS Inbound Webhooks API.
• Custom Zendesk events: You can create a Zendesk webhook that points to a ZIS Inbound Webhook. You can then connect the Zendesk webhook to a Zendesk trigger or automation. This setup lets you invoke a ZIS flow based on a custom event in Zendesk. You can also use this setup to filter native Zendesk events before they reach ZIS.

At-least-once delivery

Zendesk events are designed to fire at least once for a respective action. However, a single action could fire the same event multiple times. This could result in a ZIS flow running multiple times for the same action. For example, a ZIS integration designed to post a Slack message for new tickets may post multiple messages for the same Ticket Created event.

Asynchronous execution

ZIS flows are triggered asynchronously by a queue of events. The time it takes to trigger a flow varies based on the size of this event queue. In most cases, flows start within a few seconds of a triggering event. However, during busy periods, it may take several minutes.

A sudden increase in events or a large stream of ongoing events may delay the start of a ZIS flow. If there are errors within the flow, it may cause delays as ZIS retries the flow.

Avoiding delays

When building and testing new ZIS integrations, we recommend that you gradually ramp up the number of triggering events. This helps you detect bugs that may cause delays with a larger number of events.

We recommend you disable ZIS integrations before a data migration, bulk import, or other large-scale change. This helps you avoid delays and stay within usage limits. To disable a ZIS integration, see Disabling the integration.

As an alternative to disabling your ZIS integrations, you can update them to skip or ignore imported data. For example, you can include a specific tag on any tickets added during a bulk import. You can add a Choice state to any ticket-related ZIS flows to ignore tickets with this tag.

How an integration works with ZIS

The following diagram is an example of how an integration can operate using ZIS:

• Events are received from Zendesk products or external systems
• Selected events cause a flow to run. Flows are made up of a series of states which represent the business logic that needs to be executed.
• These states can leverage information from other ZIS services such as customer configuration settings, object relationships, and API credentials.

Connections

A connection stores credentials for a service or system, such as Slack, Shopify, or Zendesk. You can use a connection to authenticate API requests in a ZIS flow. Connections are stored as resources in the ZIS Connections Service.

For more information, see Understanding connections.