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 JobSpec 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](/documentation/integration-services/getting-started/understanding-zis#understanding-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.