ZIS configs

A ZIS config stores settings for an integration. In most cases, the setting values are specific to a customer's account. For example, a config may contain a customer's AWS account ID or a Slack channel.

Managing configs

You manage ZIS configs in two ways:

• Using the ZIS Configs API
• Using the following built-in actions in a ZIS flow:
  • LoadConfig
  • PatchConfig

In a typical setup, a Zendesk admin specifies their integration settings using a private Zendesk app. You create this app using the Zendesk Apps framework (ZAF). The app uses the ZIS Configs API to store the settings in a config. You can then use the built-in config actions to load or update the config in a ZIS flow.

Tip: For an example of this setup, check out the Zendesk app as an admin interface tutorial series.

Creating a config

You can create a config using the ZIS Configs API's Create Configuration endpoint. Requests to the endpoint require the following parameters:

• A registered integration name
• A scope string that uniquely identifies the config
• A config JSON object. This object contains integration settings as arbitrary key-value pairs.

An admin typically specifies the values for the config object using a configuration user interface (UI) in a Zendesk app.

For example, the following snippet contains an HTML form. This form serves as a basic config UI for a Zendesk app. The form lets admins specify the ticket priority and Slack channel settings for a Slack integration.

The snippet also imports the ZAF SDK. The SDK lets you use the ZAF client to make API requests.

<form id="form">
  <label for="priority">Ticket priority</label>
  <select id="priority">
    <option value="low">Low</option>
    <option value="normal">Normal</option>
    <option value="high">High</option>
    <option value="urgent">Urgent</option>
  </select>

  <label for="channel">Slack channel</label>
  <input id="channel" placeholder="For example: #general" type="text" />

  <input type="submit" value="Submit" />
</form>

...

<script
  type="text/javascript"
  src="https://static.zdassets.com/zendesk_app_framework_sdk/2.0/zaf_sdk.min.js"
></script>

The following JavaScript uses the ZAF client's request() method to make a Create Configuration request in a Zendesk app. The request's config object contains user input from the HTML form.

// Initializes the ZAF client
const client = ZAFClient.init();

const integration = "my_slack_integration";

client.request({
  type: "POST",
  url: "/api/services/zis/integrations/" + integration + "/configs",
  contentType: "application/json",
  data: JSON.stringify({
    scope: "slack_settings",
    config: {
      priority: document.getElementById("priority").value,
      channel: document.getElementById("channel").value,
    },
  }),
});

When run, the request creates a config in the ZIS Configs Service. The config is scoped to the admin's Zendesk account and integration. Example response:

{
  "config": {
    "id": 123456,
    "scope": "slack_settings",
    "zendesk_account_id": 12345678,
    "integration": "my_slack_integration",
    "config": {
      "priority": "urgent",
      "channel": "#zendesk-tickets"
    },
    "created_at": "2099-05-06T17:14:30Z",
    "updated_at": "2099-05-06T17:14:30Z"
  }
}

Fetching configs

You can use a Show Configuration request to look up existing configs. The request matches configs based on the integration and filter[scope] parameters.

The filter[scope] parameter supports wildcard (*) values. For example, the following request matches configs with a scope that begins with "slack".

const client = ZAFClient.init();

const integration = "my_slack_integration";
const scope = "slack*";

let fetched_config = {};

client
  .request({
    type: "GET",
    url:
      "/api/services/zis/integrations/" +
      integration +
      "/configs?filter[scope]=" +
      scope,
  })
  .then(function (response) {
    fetched_config = response.configs[0].config;
  });

The response contains an array of matching configs. If the request returns multiple pages of results, you can navigate them using cursor pagination.

{
  "meta": {
    "has_more": false
  },
  "next": null,
  "configs": [
    {
      "id": 123456,
      "scope": "slack_settings",
      "zendesk_account_id": 12345678,
      "integration": "my_slack_integration",
      "config": {
        "priority": "urgent",
        "channel": "#zendesk-tickets"
      },
      "created_at": "2099-05-06T17:14:30Z",
      "updated_at": "2099-05-06T17:14:30Z"
    },
  ],
  "links": {
    "next": ""
  }
}

You can display the returned configs in a Zendesk app. The following JavaScript displays a fetched config in the HTML form from Creating a config.

document.getElementById("priority").value = fetched_config.priority;
document.getElementById("channel").value = fetched_config.channel;

Replacing a config

You can use an Update Configuration request to replace an existing config. To identify the existing config, the request requires the integration and scope parameters. The request also requires a new config object. This new config object completely overwrites any existing settings in the config.

Note: You can't use an Update Configuration request to change a config's scope.

const client = ZAFClient.init();

const integration = "my_slack_integration";
const scope = "slack_settings";

client.request({
  type: "PUT",
  url: "/api/services/zis/integrations/" + integration + "/configs/" + scope,
  contentType: "application/json",
  data: JSON.stringify({
    config: {
      priority: "high",
      channel: "#zendesk-tickets",
    },
  }),
});

Updating a config

You can use a Merge Configuration request to make partial updates to an existing config. To identify the existing config, the request requires the integration and scope parameters. The request also requires a config object. The request only changes settings in the config object that you specify.

Note: You can't use the Merge Configuration endpoint to change a config's scope.

For example, the following Merge Configuration request updates the priority setting in an existing config object. The action doesn't change other settings in the object.

const client = ZAFClient.init();

const integration = "my_slack_integration";
const scope = "slack_settings";

client.request({
  type: "PATCH",
  url: "/api/services/zis/integrations/" + integration + "/configs/" + scope,
  contentType: "application/json",
  data: JSON.stringify({
    config: {
      priority: "high",
    },
  }),
});

Deleting a config

You can use a Delete Configuration request to delete an existing config. The request requires the integration and scope parameters.

const client = ZAFClient.init();

const integration = "my_slack_integration";
const scope = "slack_settings";

client.request({
  type: "DELETE",
  url: "/api/services/zis/integrations/" + integration + "/configs/" + scope,
});

Loading a config in a ZIS flow

You can use the LoadConfig action to look up an existing config in a ZIS flow. The action identifies the config based on the scope parameter.

Note: We recommend you provide an specific scope in the scope parameter. The scope parameter supports wildcard (*) values. However, if the action matches multiple configs, it only loads the first config found. This result may be inconsistent over time.

To use the action's response in later states of the ZIS flow, specify a ResultPath.

"SlackSettings.LoadConfig": {
  "Type": "Action",
  "ActionName": "zis:common:action:LoadConfig",
  "Parameters": {
    "scope": "slack_settings"
  },
  "ResultPath": "$.config_result",
  "Next": "NextState"
}

The response contains the matching config object.

{
  "config": {
    "priority": "urgent",
    "channel": "#zendesk-tickets"
  }
}

Later states of the ZIS flow can access the response from the ResultPath. For example, the following state references a setting value from the config.

"PostMessageOnNewTicket": {
  "Type": "Action",
  "ActionName": "zis:INTEGRATION_NAME:action:PostToSlack",
  "Parameters": {
    "channelId.$": "$.config_result.channel",
    "text.$": "$.input.ticket_event.comment.body"
  },
  "Next": "NextState"
}

Updating a config in a ZIS flow

You can use the PatchConfig action to make partial updates to an existing config. To identify the existing config, the action requires a scope parameter. The action also requires a config object. The action only changes settings in the config object that you specify.

Note: You can't use the PatchConfig action to change a config's scope.

For example, the following state uses the PatchConfig action to update the priority setting in an existing config object. The action doesn't change other settings in the object.

"SlackSettings.PatchConfig": {
  "Type": "Action",
  "ActionName": "zis:common:action:PatchConfig",
  "Parameters": {
    "scope": "slack_settings",
    "config": {
      "priority": "high"
    }
  },
  "Next": "NextState"
}

Best practices

• Don't store secrets in ZIS configs. Configs aren't encrypted. Depending on your integration, data in a ZIS config may be accessible in connected systems.