Channel framework startup tutorial - Step 5: Connect the integration service to Zendesk Support - Part 1 (Admin UI, Manifest)

After the previous two steps, you have an integration service that communicates with WordPress in both directions. The next step is to wire this up with Zendesk Support so it knows where the integration service is and what capabilities the integration service has.

Step 5A: Create the manifest

Integration services are self-describing. They expose a manifest which describes their attributes and capabilities in JSON. The manifest includes the name, globally unique id, author, version, and a list of all reachable endpoints on the integration service.

In wordpress.js, add the following code:

exports.manifest = res => {  res.send({    name: 'WordPress',    id: 'com.zendesk.anychannel.integrations.wordpress',    author: 'Zendesk',    version: 'v0.0.1',      channelback_files: true,    urls: {      admin_ui: './admin_ui',      pull_url: './pull',      channelback_url: './channelback',      clickthrough_url: './clickthrough',      healthcheck_url: './healthcheck'    }  });};

This returns the manifest JSON. The endpoints you built in steps 2 and 4 are described in pull_url and channelback_url respectively.

Now you can verify manifest endpoint works with curl.

Restart the server and run this curl command:

curl http://localhost:3000/manifest

You should get a JSON string like:

{"name":"WordPress","id":"com.zendesk.anychannel.integrations.wordpress","author":"Zendesk","version":"v0.0.1","urls":{"admin_ui":"./admin_ui","pull_url":"./pull","channelback_url":"./channelback","clickthrough_url":"./clickthrough","healthcheck_url":"./healthcheck"}}

Step 5B: Allow the Zendesk Support admin to set up the Integration Service

You have now built the necessary API endpoints for the Channel framework to interact with the integration service. However, the integration service doesn’t have a way for the Zendesk Support admin to provide WordPress login information. Now you are going to build the UI to collect the WordPress information from the Zendesk Support administrator. Zendesk Support will store this information in an integration account. In the Channel framework, an integration account records information about an instance of the origin service. For example, an integration account for WordPress integration service stores connection information for a WordPress login.

In this step, you'll create a UI for collecting the WordPress information the integration service needs, and embed it into a Zendesk Support admin view. Here's a sample screenshot of the UI you will create:

Note : The warning message and surrounding decorations are implemented in Zendesk Support. Only the form is implemented in the integration service.

First, implement the admin UI form.

In wordpress.js, add this adminUiHtml function:

function adminUiHtml(name, login, password, location, returnUrl, warning) {  let warningStr = '';
  if (warning) {    warningStr = `${warning}<br>`;  }
  return `<html><body> <form method="post" action = "./admin_ui_2"> Name: <input type="text" name="name" value="${escapeString(name)}"><br> Login: <input type="text" name="login" value="${escapeString(login)}"><br> Password: <input type="password" name="password" value="${escapeString(password)}"><br> WordPress location (URL): <input type="text" name="wordpress_location" value="${escapeString(location)}"><br> <input type="hidden" name="return_url" value="${escapeString(returnUrl)}"></input> ${warningStr} <input type="submit"> </form> </body></html>`;}

This function returns the HTML for the input form as seen in the screenshot. When the administrator is editing a pre-existing account, this form displays the previous values for name, login, and password. Therefore, this page can handle both creating new integration accounts and editing existing ones. Lines 8, 10, 14, and 18 are examples.

Zendesk Support provides a return_url when displaying the admin UI. Once the administrator has POSTed the form to the integration service, it will format the data according to Zendesk Support’s requirements and POST it back to Zendesk Support via the the return_url.

On line 10, the code sets the target of this form to ./admin_ui_2 for subsequent processing.

Step 5C: Handle the credentials entered by the Zendesk Support admin

After the Zendesk Support administrator enters the WordPress information, the integration service needs to save the information to use in future pull and channelback requests. Instead of storing this information local to the integration service, the Channel framework provides a simple way to store it inside Zendesk Support. The return_url mentioned above is the mechanism to store metadata in Zendesk Support.

In wordpress.js, add the ./admin_ui_2 function:

exports.admin_ui_2 = (attributes, res) => {  request.get(    userRequestOptions(attributes),    (error, wordpressResponse, body) => {      let users;      let user;      let adminHtml;      let metadata;
      if (!error && wordpressResponse.statusCode === 200) {        // Request to WordPress was successful- did we find the user?        users = JSON.parse(body);        user = users.find(currentUser => {          return currentUser.name === attributes.login;        });
        if (typeof user === 'undefined') {          // No user found, allow the admin to choose a different login          adminHtml = adminUiHtml(            attributes.name,            attributes.login,            attributes.password,            attributes.wordpress_location,            attributes.return_url,            `Sorry, the user '${attributes.login}' was not found, please try again.`);          res.send(adminHtml);
          return;        }
        // Validation passed and user found.  Format the WordPress data into        // a string that we understand and can use later (e.g. in pull.)        metadata = JSON.stringify({          name: attributes.name,          login: attributes.login,          password: attributes.password,          author: user.id,          wordpress_location: attributes.wordpress_location        });
        // Send the formatted data to Zendesk Support.  We do this by putting the info        // into a form and then programmatically submitting the form.        res.send(`<html><body> <form id="finish" method="post" action="${escapeString(attributes.return_url)}"> <input type="hidden" name="name" value="${escapeString(attributes.name)}"> <input type="hidden" name="metadata" value="${escapeString(metadata)}"> </form> <script type="text/javascript"> // Post the form var form = document.forms['finish']; form.submit(); </script> </body></html>`);      } else {        // Our API call to WordPress failed.  Alert the administrator and allow        // them to edit the connection info.        adminHtml = adminUiHtml(          attributes.name,          attributes.login,          attributes.password,          attributes.wordpress_location,          attributes.return_url,          `Sorry, we were unable to connect to WordPress at the requested location, please try again.`);        res.send(adminHtml);      }    }  );};

On line 2, this function calls the WordPress API to retrieve user info. This verifies the WordPress user information provided by the admin. See the userRequestOption function for more information about the request parameters. Lines 9-69 handle the response we get from WordPress.

If WordPress returns a parsable response, lines 12-15 check if the user the admin specified is available in WordPress. If not, line 17-26 re-renders the admin_ui form with error Sorry, the user '${attributes.login} was not found, please try again.`

If the code finds the user, it knows the login is working. Line 30-36 combines all the login information into a JSON string (the metadata). Then in line 39-55, it passes the formatted information back to Zendesk Support, using a http form POST to the return url. This metadata is similar to what you used to test the pull and channelback endpoints.

If the code encounters any other errors, line 59-66 re-renders the admin_ui form with error Sorry, we were unable to connect to WordPress at the requested location, please try again.

Note : For ease of use and testing in this tutorial, the integration service uses basic authentication with an unencrypted password. This is not recommended for a production integration service.

Continue on Channel framework startup tutorial - Step 6: Connect the integration service to Zendesk Support - Part 2 (Zendesk app) .