Part 3: Add a configuration UI

This tutorial is part of a series that builds a Zendesk integration for Slack:

• Part 1: Build a Zendesk app with OAuth
• Part 2: Connect to Slack
• Part 3: Add a configuration UI — YOU ARE HERE
• Part 4: Install the integration

The integration listens for Ticket Created events in Zendesk. When it detects an event with a specific ticket priority, the integration posts a related message to a provided Slack channel.

In the previous tutorials, you created a Zendesk app. So far, the app lets admins connect the integration to their Zendesk and Slack instances. In this tutorial, you'll add a configuration user interface (UI) to the app. Admins can use the config UI to set a ticket priority and a Slack channel for the integration.

Add the configuration UI

Your Zendesk app should include the following:

• A Ticket priority drop-down field
• A Slack channel text field
• A Save button

To configure the integration, an admin fills out the fields and clicks the Save button. The app then stores the field values as a config object in Zendesk Integration Services (ZIS). The app also fetches and displays the current config if it exists.

1. In your Zendesk app's assets folder, open iframe.html. Add the following HTML (lines 5 to 46) directly after the <div> tag containing the Connect to Slack button.

   ...
         Connect to Slack
       </button>
     </div>
     <div class="row">
       <div class="col-6">
         <div class="c-txt u-mb-small">
           <label class="c-txt__label" for="txt-priority"
             >Ticket priority</label
           >
           <select
             class="c-txt__input c-txt__input--select"
             id="select-priority"
           >
             <option value="low">Low</option>
             <option value="normal">Normal</option>
             <option value="high">High</option>
             <option value="urgent">Urgent</option>
           </select>
         </div>
       </div>
       <div class="col-6">
         <div class="c-txt u-mb-small">
           <label class="c-txt__label" for="txt-channel"
             >Slack channel</label
           >
           <input
             class="c-txt__input"
             id="txt-channel"
             placeholder="e.g. #general"
             type="text"
           />
         </div>
       </div>
     </div>
     <div class="row u-mt">
       <div class="col-12">
         <button
           id="submit"
           class="c-btn c-btn--primary"
           style="float: right"
         >
           Save
         </button>
       </div>
     </div>
   ...

2. In bootstrap.js, add the following:

   ...
       startSlackOAuth(integrationName, subdomain);
     });
   
     // Bind button to submit config
     document.getElementById("submit").addEventListener("click", function () {
       submitConfig(integrationName);
     });
   
     // Fetch configuration data and display in UI
     fetchConfig(integrationName);
   ...

   The code binds the Save button to the submitConfig function. The codes also calls the fetchConfig function when the Zendesk app loads. You'll define the submitConfig and fetchConfig functions in the next steps.

3. In the assets folder, create a config.js file. Paste the following into the file:

   // configScope is a custom defined key for referencing the configuration data
   let configScope = "slackNotification";
   
   // Indicates whether config data exists for slackNotification
   let scopeExists = false;
   
   // fetchConfig defines the function to fetch config data
   function fetchConfig(integrationName) {
     // Fetch config request
     let request = {
       type: "GET",
       url:
         "/api/services/zis/integrations/" +
         integrationName +
         "/configs?filter[scope]=" +
         configScope,
     };
   
     client.request(request).then(
       function (response) {
         console.log("Config fetched: ", response.configs[0].config);
         scopeExists = true;
         updateComponents(response.configs[0].config);
       },
       function (response) {
         console.log("Config fetching failed: ", response);
         if (response.status == 404) {
           scopeExists = false;
         }
       }
     );
   }
   
   // submitConfig maps the data from DOM and submit through ZIS Configs API
   function submitConfig(integrationName) {
     // Prepare the config payload
     let data = JSON.stringify({
       scope: configScope,
       config: {
         priority: document.getElementById("select-priority").value,
         channel: document.getElementById("txt-channel").value,
       },
     });
   
     // The request is for create or update config data
     let request;
   
     if (scopeExists) {
       // request for update config
       request = {
         type: "PUT",
         url:
           "/api/services/zis/integrations/" +
           integrationName +
           "/configs/" +
           configScope,
         contentType: "application/json",
         data: data,
       };
     } else {
       // request for create config
       request = {
         type: "POST",
         url: "/api/services/zis/integrations/" + integrationName + "/configs",
         contentType: "application/json",
         data: data,
       };
     }
   
     client.request(request).then(
       function (response) {
         console.log("Config saved: ", response);
         client.invoke("notify", "Config saved");
         scopeExists = true;
       },
       function (response) {
         console.log("Config submission failed: ", response);
       }
     );
   }
   
   // updateComponents updates the UI components with the newly fetched config data
   function updateComponents(config) {
     console.log("Updating components with config: ", config);
     document.getElementById("select-priority").value = config.priority;
     document.getElementById("txt-channel").value = config.channel;
   }

   The code defines the submitConfig function. When called, submitConfig uses the Configs API to create or update a configuration object. The config stores the Ticket priority and Slack channel settings as key-value pairs.

   The config object has a scope property of "slackNotification." Later, you'll use this scope to load the config data in your integration's ZIS flow.

   The code also defines the fetchConfig function. fetchConfig makes a Show Configuration request to get the current config for the "slackNotification" scope. If the config exists, the functions displays the config data in the Ticket priority and Slack channel fields.

4. In iframe.html, add the following:

   ...
   <!-- Establish OAuth connections -->
   <script type="text/javascript" src="connect.js"></script>
   
   <!-- Manage configuration settings -->
   <script type="text/javascript" src="config.js"></script>
   ...

5. Save iframe.html, bootstrap.js, and config.js. Then refresh the app.

   Your app now displays the configuration UI.

   

Save a configuration

Next, use the UI to set a ticket priority and Slack channel for your integration.

1. In your app, select a Ticket priority of Urgent.

2. In Slack channel, enter the name of a Slack channel in your workspace.

   

3. Click Save. A success notification is displayed.

   

Verify the config object

Use a Show Configuration request to get the config for the "slackNotification" scope. This lets you verify that you can use the config's data in your integration.

In your command-line interface, run the following curl request. Replace {access_token} with the OAuth access token you got in Verify the Zendesk access token.

curl -X GET https://{subdomain}.zendesk.com/api/services/zis/integrations/{subdomain}_zendesk_to_slack/configs?filter[scope]=slackNotification \
  -g -H "Authorization: Bearer {access_token}"

The response contains details about the "slackNotification" config, including its priority and channel values. For example:

{
  "meta": {
    "has_more": false
  },
  "next": null,
  "configs": [
    {
      "id": 123456,
      "scope": "slackNotification",
      "zendesk_account_id": 12345678,
      "integration": "sample_zendesk_to_slack",
      "config": {
        "priority": "urgent",
        "channel": "#zendesk-tickets"
      },
      "created_at": "2099-04-19T20:44:51Z",
      "updated_at": "2099-04-19T20:44:51Z"
    }
  ],
  "links": {
    "next": ""
  }
}

Add the Slack app to the channel

Next, invite your Slack app to the channel you selected. This lets your Slack app post messages to the channel.

1. In Slack, open your workspace.

2. Go to the Slack channel you selected earlier. In the channel, enter the following in the message field:

   /invite @Zendesk Ticket Bot

   

   Press Enter.

   Depending on your Slack settings, the channel may display a success message. The message indicates the app joined the channel.

   

In the next tutorial, you'll install the integration. Refer to Part 4: Install the integration.