Developing private ZIS integrations

Zendesk Integration Services (ZIS) lets you build and run private integrations in your Zendesk instance. This article describes the main steps for developing and managing a private integration.

ZIS is available on the Suite Growth plan or above, and the Support Professional plan or above.

Zendesk recommends building and testing a private integration in a sponsored test account before running it in a customer account.

This article covers the following development workflow:

Registering the integration name

The first step in building an integration is registering the name of the integration with the ZIS Registry Service. This name is also called the integration key.

To register the integration, make a POST request to the Create Integration endpoint specifying a unique name for the integration.

Example:

curl https://example.zendesk.com/api/services/zis/registry/slack_integration_development_acme1234 \
  -d '{"description": "An example integration"}' \
  -H "Content-type: application/json" \
  -v -u [email protected]/token:6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv -X POST

The request registers an integration named slack_integration_development_acme1234.

The integration name can be a string up to 64 characters long consisting of lower-case letters (a-z), numbers, the dash (-) character, or the underscore (_) character.

Since the name of an integration must be globally unique, use one name when building an integration in your test account and a different name when running it in production in your customer's account. For example, you can use “slack_integration_development_acme1234” in your developer account and “slack_integration_acme1234” in your customer account.

You can authorize the API request using a Zendesk API token. See Security and authentication in the Zendesk API documentation.

You must be a Zendesk admin to make the API request. If you're not an admin, ask an admin in your organization to assign the admin role to you.

When you register a ZIS integration, the request automatically creates an OAuth client for Zendesk. The response contains the OAuth client's details. Example:

{
  "description": "An example integration",
  "jwt_public_key": "***The RSA Public Key to be saved***",
  "zendesk_oauth_client": {
    "id": 10066,
    "identifier": "zis_{integration_name}",
    "secret": "***secret***"
  }
}

Save the response in a safe place. Later, you can use the client id to obtain a ZIS OAuth token.

Obtaining a ZIS OAuth token

Most ZIS integrations have a private Zendesk app that the developer creates. The app typically uses ZIS APIs to let Zendesk admins:

• Connect the integration to their Zendesk instance and third-party services
• Configure settings for the integration
• Enable the integration by installing the job spec
• Disable the integration by uninstalling the job spec

In most cases, the app uses the admin's browser session to authenticate these ZIS API requests. See Making API requests from a Zendesk app.

A ZIS OAuth token lets developers make ZIS API requests without creating a Zendesk app. This is useful when building or testing an integration. Developers can also use the token with ZIS API endpoints that don't support browser session authentication.

Important: Keep the following in mind when creating and using a ZIS OAuth token:

• The token isn't intended for use in a ZIS flow. To authenticate Zendesk API requests in a ZIS flow, use a connection instead. See Understanding connections.

• The token is scoped to a specific ZIS integration and Zendesk subdomain. You can't use the token to authenticate ZIS API requests for other integrations or subdomains.

To get a ZIS OAuth token

1. If you have the client id for your integration's Zendesk OAuth client, skip to step 3. Otherwise, make a curl request to the List OAuth Clients endpoint.

   curl https://example.zendesk.com/api/v2/oauth/clients.json \
     -u [e-mail]/token:6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv

   The request returns a list of your account's Zendesk OAuth clients.

2. In the response, find the client with an identifier that matches your integration's name with a zis_ prefix.

   Copy the client’s id. This is the same client id returned when you registered the integration name.

   {
     "clients": [
       {
         "url": "https://example.zendesk.com/api/v2/oauth/clients/10066.json",
         "id": 10066,
         "user_id": -1,
         "name": "ZIS Client",
         "identifier": "zis_slack_integration_development_acme1234",
         "company": null,
         "description": null,
         "redirect_uri": [
           "https://zis.zendesk.com/api/services/zis/connections/oauth/callback"
         ],
         "secret": "***secret***",
         "created_at": "2099-05-06T01:22:08Z",
         "updated_at": "2099-05-06T01:22:08Z",
         "global": false,
         "logo_url": null
       },
       ...
     ],
     "next_page": null,
     "previous_page": null,
     "count": 1
   }

3. Make a curl request to the Create Token endpoint. Specify the client id for the integration's Zendesk OAuth client.

   curl -X POST https://example.zendesk.com/api/v2/oauth/tokens.json \
     -u [e-mail]/token:6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv \
     -H "Content-Type: application/json" \
     -d '{
       "token": {
         "client_id": "10066",
         "scopes": ["read", "write"]
       }
     }'

   The response's token.full_token property contains the ZIS OAuth token. Save the token in a safe place.

   {
     "token": {
       "url": "https://example.zendesk.com/api/v2/oauth/tokens/1234.json",
       "scopes": ["read", "write"],
       ...
       "full_token": "***access token***"
     }
   }

Creating a ZIS bundle

A ZIS Bundle is a JSON object that defines the logic of your integration. It contains three types of nested objects: Action, Flow, and JobSpec. Each of these nested objects must have a unique name within an integration. See Anatomy of a ZIS bundle.

To create a simple bundle for testing, see Building your first ZIS integration. To make authenticated API requests in the integration's ZIS flow, use a connection. See Understanding connections.

Uploading the ZIS bundle

To deploy your integration, upload the bundle to the ZIS Registry Service using the Upload or Update Bundle endpoint.

Example request:

curl https://example.zendesk.com/api/services/zis/registry/slack_integration_development_acme1234/bundles \
  -d @my_bundle_file.json \
  -H "Content-type: application/json" \
  -v -u [email protected]/token:6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv -X POST

If the bundle was uploaded successfully, the request returns an empty 200 response.

Installing the job spec

A ZIS JobSpec is an object in the ZIS bundle that specifies the flow to run when a given event happens. Example:

"react_to_ticket_created_job_spec": {
  "type": "ZIS::JobSpec",
  "properties": {
    "name": "react_to_ticket_created_job_spec",
    "event_source": "support",
    "event_type": "ticket.TicketCreated",
    "flow_name": "zis:my_integration:flow:my_new_ticket_flow"
  }
}

After uploading your ZIS bundle, you need to tell ZIS to install each job spec contained in the uploaded bundle.

To install a job spec, make an API request to the Install Job Spec endpoint.

Example request:

curl "https://example.zendesk.com/api/services/zis/registry/job_specs/install?job_spec_name=zis:slack_integration_development_acme1234:job_spec:handle-ticket-created-event" \
  -H "Authorization: Bearer 29cb46de50dd1d7d600fc1057e7b72" \
  -X POST

Make sure to enclose the endpoint in quotes because of the special characters.

If the job spec was uploaded successfully, the request returns an empty 200 response.

Note: Removing a job spec from a ZIS bundle doesn't uninstall the job spec. A removed job spec can still kick off its ZIS flow. To uninstall a job spec, see Disabling the integration.

Testing and updating the integration

You can test your the ZIS integration after deploying it. The workflow is to test, update the ZIS bundle locally, upload the bundle, then test the update.

See Uploading the ZIS bundle for more information.

You can use the integrations log in the Zendesk Admin Center to help troubleshoot issues:

1. Sign into your Zendesk account as a admin.

2. In Admin Center, click Apps and integrations in the sidebar, then select Integrations > Logs.

   

For more information, see Viewing the integrations log in the Zendesk help center.

Disabling the integration

We recommend you disable ZIS integrations before a data migration or other large-scale change. Such changes can create a large number of events and kick off multiple ZIS flows in a short period, exceeding usage limits. Depending on the integration, it may also create an undesired user experience.

You can disable a private integration by uninstalling the job spec in a customer’s account using the Uninstall Job Spec endpoint.

Example request:

curl "https://example.zendesk.com/api/services/zis/registry/job_specs/install?job_spec_name=zis:slack_integration_development_acme1234:job_spec:handle-ticket-created-event" \
  -H "Authorization: Bearer 29cb46de50dd1d7d600fc1057e7b72" \
  -X DELETE

If the job spec was uninstalled successfully, the request returns an empty 204 response.

Note: You can't delete a ZIS integration or bundle. To disable an integration, you must uninstall its job spec.