DocumentationAPI Reference

Using the ZIS Playground app

Note: The ZIS Playground app is in open beta and may change at any time. By enabling the app, you agree to the Built By Zendesk Application Agreement.

Zendesk Integration Services (ZIS) is a set of Zendesk-hosted web services that let you build and run private integrations. A ZIS integration consists of one or more automated workflows, called ZIS flows, that are triggered by events in Zendesk or a third-party system.

The ZIS Playground app is a Zendesk Support app that lets you build and test ZIS flows. You can use the app to:

  • Streamline API requests to Zendesk and other systems

  • Build and run a ZIS flow without defining a job spec or creating a test event

  • Get detailed logs for a test run of a ZIS flow, including validation checks and flow output

What you'll need

To use the ZIS Playground app, you'll need the following:

  • A Zendesk account with the Zendesk Suite Growth plan or above, or the Support Professional plan or above. We recommend you install the ZIS Playground app in a sandbox or sponsored test account rather than a production instance. This helps prevent accidental data leaks during testing.

  • Be an admin on the account or have access to someone who is an admin. The admin can give you admin access. Refer to Setting roles and access in Zendesk Admin Center.

Installing the app

You can install the ZIS Playground app from the Zendesk Marketplace.

To install the ZIS Playground app

  1. In your browser, navigate to the ZIS Playground app in the Zendesk Marketplace at https://www.zendesk.com/marketplace/apps/support/651210/zis-playground.

  2. Click Install.

  3. Select your Zendesk Support account and click Install.

  4. Use the Enable role restrictions? field to limit the app to the Admin role. Agents and other roles won't get much value from the app.

  5. Accept the terms and license and click Install.

After installation, you can open the app from the left nav bar of Zendesk Support.

Setting up the app

The ZIS Playground app requires a related ZIS integration and Zendesk OAuth connection. You create these resources when you first set up the app.

To set up the ZIS Playground app

  1. Open the ZIS Playground app.

  2. Click Connect playground. A Zendesk OAuth page opens in a separate browser tab.

  3. On the Zendesk OAuth page, click Allow.

    The OAuth page closes. Behind the scenes, the ZIS Playground app does the following:

    • Registers a private ZIS integration named zis_playground_{SUBDOMAIN}, where {SUBDOMAIN} is your Zendesk subdomain
    • Registers a Zendesk OAuth client named "zendesk" for the integration
    • Creates a Zendesk OAuth connection named "zendesk" for the integration

Building a ZIS flow

You can use the app's Playground tab to build and run ZIS flows. The app organizes the tab into the following panels:

  • Flow: Contains a ZIS flow definition. A ZIS flow describes the integration's logic as a state machine. You define the flow using a JSON-based, structured language similar to the Amazon States Language.

  • Actions: JSON object containing one or more ZIS custom action definitions. A custom action is a wrapper for an HTTP request. You can use a custom action to make API requests to Zendesk or a third-party service, such as Slack or Shopify, in a ZIS flow's Action states.

  • Input: JSON object containing mock event data. The ZIS flow can access this data using the $.input reference path.

  • Output: Output logs for the app's most recent ZIS flow run

The Playground tab also displays the app's ZIS integration key in the upper right.

Preloaded examples

The Playground tab comes preloaded with an example ZIS flow, custom action definitions, and event input data. The example flow first retrieves a ticket based on its id. The flow then retrieves the detail of the user who submitted the ticket.

To reset the Playground tab to the preloaded examples, click Reset all.

Running a ZIS flow

To run a ZIS flow in the Playground tab, click Execute.

The Output panel displays a detailed log of the flow's output and execution steps. The log's ExecutionStates lists the flow states that ran during the flow's execution. This is often helpful for troubleshooting flows with Choice states or other branching logic.

Creating an OAuth connection

When you set up the ZIS Playground app, the app automatically creates a "zendesk" OAuth connection and a "zendesk" OAuth client. You can use the app's Connections tab to create other OAuth connections. You can't use the tab to update or delete connections.

To create an OAuth connection

  1. In the ZIS Playground app, click the Connections tab.

  2. Click Create Connection. The Create Connection opens.

  3. On the Create Connection page, configure the connection:

    • Name: The connection's name. You can use this name in custom action definitions to authenticate API requests. See Using a connection to authenticate API requests in a ZIS flow.

    • Client: Select an OAuth client. To create an OAuth client, select Add client. See Registering an OAuth client.

    • Scopes: OAuth scopes for the connection. Supported OAuth scopes vary based on the system to which you're connecting. To get a list of supported scopes, check the system's documentation. For Zendesk connections, see Using OAuth authentication with your application in Zendesk help.

    • Subdomain: Subdomain used to interpolate the {{oauth_url_subdomain}} placeholder in the OAuth client's authorize and token URLs. For Zendesk connections, leave this field blank.

  4. Click Save.

  5. The browser opens an OAuth authorization page for the connection's other system. Complete the authorization steps on the page.

    When authorization is complete, the OAuth authorization page automatically closes, and ZIS creates the OAuth connection.

Registering an OAuth client

In addition to creating OAuth connections, you can use the Connections tab to register OAuth clients for third-party systems.

You can only use the Connections tab to register OAuth clients that use the authorization code grant type. You can't use the tab to update or delete OAuth clients.

To create an OAuth client

  1. Create an OAuth client in the third-party system. These steps vary based on the system. Set the client's callback URL as "https://zis.zendesk.com/api/services/zis/connections/oauth/callback". When done, the system should provide a client id and secret.

  2. In the ZIS Playground app, click the Connections tab.

  3. Click Create Connection.

  4. In the Client field, select Add client. The Add Client modal opens.

  5. In the modal, configure the OAuth client:

    • Name: The client's name

    • Client ID: id for the client. The system provides this id when you create the client.

    • Client secret: Secret used to authenticate the client. The system provides this secret when you create the client.

    • Authorize URL: Authorization request URL used to start an OAuth flow. This URL varies by system. To get the URL, check the system's documentation.

      The URL can include an optional {{oauth_url_subdomain}} placeholder. You define this placeholder's value when you create a connection that uses the client. This lets you use the client with multiple instances of the system. Example: https://{{oauth_url_subdomain}}.myshopify.com/admin/oauth/authorize

    • Token URL: URL used to exchange the OAuth verification code for an access token. This URL varies by system. To get the URL, check the system's documentation.

      The URL can include an optional {{oauth_url_subdomain}} placeholder. You define this placeholder's value when you create a connection that uses the client. This lets you use the client with multiple instances of the system. Example: https://{{oauth_url_subdomain}}.myshopify.com/admin/oauth/access_token

    • Default scopes: Default OAuth scopes for connections created using the client. To get a list of supported scopes, check the system's documentation.

  6. To register the OAuth client in ZIS, click Save. This closes the modal and reloads the Create Connection page.

Viewing an OAuth connection or client

You can also use the app's Connections tab to view an OAuth connection or client. You can't use the tab to view connections of other types.

To view an OAuth connection or client

  1. In the ZIS Playground app, click the Connections tab.

  2. Find the connection or client in the list, and click View. This opens the details page for the connection or client.

    For security purposes, client secrets are redacted on the client's details page.

Limitations

  • The ZIS Playground app can only create and view OAuth connections. To create and view connections of other types, use the related Connections API endpoints. See Connection types.

  • You can't use the ZIS Playground app to directly create or manage ZIS configs or ZIS links. Instead, use the respective ZIS Configs and ZIS Links APIs. See ZIS configs and ZIS links.

  • The ZIS Playground app can only store and run one ZIS flow at a time.