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
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 OAuth tokens for external systems
- 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. See Understanding ZIS Links
- ZIS Inbound Webhooks Service: Trigger workflows in ZIS from external systems
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.
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:
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.
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.
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.
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:
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.
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 (trigger and target): You can create a ZIS Inbound Webhook and configure a custom trigger and target in Zendesk to point at it. This enables some non-native events and more advanced filtering of Zendesk events before they reach 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 OAuth tokens.
An 'OAuthClient' resource in ZIS stores the credentials of an external system's OAuth client that you want to use with your integration. Using this client, the ZIS Connections Service can fetch and store access tokens for the users of your integration so data can be sent to the external system.
Registering an OAuth client with ZIS makes it easier to obtain an OAuth token from that client and make use of it in your flows. ZIS stores and manages OAuth tokens using a ZIS Connection. See Managing third-party OAuth tokens.
A Connection is an abstraction over an OAuth 2.0 access token. The connection can be used in ZIS Flow in order to make authenticated calls to REST APIs such as sending a message to Slack or posting a comment to a JIRA issue. The developer of the flow can declare the name of the connection to use for a specific HTTP action.