DocumentationAPI Reference

Anatomy of a ZIS bundle

A ZIS bundle is a declaration of the ZIS resources which are the building blocks of your integration.

Example bundle

To illustrate how ZIS resources work together in a ZIS bundle, here’s an example bundle where a message is posted in Slack when a comment is added to a Zendesk Support ticket. The following resources are defined:

  • A ZIS action which posts a message to Slack
  • A ZIS flow which executes the action
  • A job spec which tells ZIS that this flow should be invoked when a comment is added to a ticket

Let’s look at the JSON file for this bundle:

  • The action named slack.post_simple_message is referenced in the flow by its name
  • The flow named react_to_ticket_commentadded_flow is referenced in the job spec by its name
  • The job spec named react_to_ticket_commentadded_job_spec tells ZIS to listen for a ticket.CommentAdded event

You can view the bundle JSON file in ZIS bundle: Adding a Choice state.

Input data

A key feature of flows is the ability to access data from the event that triggered it. The triggering event's data is available via the $.input object.

You can see here where the flow makes use of the comment body from the ticket.CommentAdded event:

A more complex example bundle

A slightly more complex example can contain the following components:

  • A bundle with multiple flows, job specs, and custom action definitions
  • Flows with conditional logic using a Choice state. Choices let you evaluate some condition, and branch off in multiple directions
  • A flow terminated with a Success or Failed state. This not only makes your flow more readable, but also allows you to log a message

You can view the JSON file in ZIS bundle: Posting a message in Slack when the ticket status changes.

Creating a ZIS bundle

Using the ZIS Registry API, you can create the underlying resources in the ZIS bundle. Example:

{  "zis_template_version": "2019-10-14",  "name": "example_bundle",  "description": "A description of the bundle.",  "resources": "A JSON OBJECT CONTAINING FLOWS, ACTIONS, etc."}

The following properties are required:

  • name - name of your ZIS bundle
  • zis_template_version - denotes the version and capabilities of the ZIS bundle. The latest version is 2019-10-14 and currently is the only valid value
  • resources - specifies the bundle resources. Refer to ZIS bundle and resources

All resources for an integration need to specify the same integration name identifier when being created. See the ZIS Integrations API.

When you submit a bundle to the ZIS Registry Service, resources are created and stored with all associations established.