Apps

What is a Zendesk App

A Zendesk App is an application (written in HTML/CSS/JS) that runs in a location of Zendesk. What it does and how it does it varies greatly from application to application. Applications can be run in a great many places, but the traditional locations are:

Applications can be run in a great many places, but the traditional locations are:

• Ticket sidebar
• User sidebar
• Organization sidebar
• Navbar
• Background

You can see more resources on application locations via the Zendesk Developer Manifest Reference documentation.

Zendesk applications tend to come from one of two areas:

• Zendesk Marketplace
• Developed in-house

Zendesk Global App List

Advanced Search

Advanced Search is an app that provides a simple visual interface for constructing complex search queries against tickets, users, and organizations (orgs). It also enables you to export the search results in a CSV format.

App information:

• Located in the navbar
• This application was developed by Zendesk and is available in the Zendesk Marketplace.

GitLab Reminders App

The Reminders App appears in the navbar and allows the agent a more specialized view of tickets they are involved in. It currently shows:

• Tickets assigned to you with a pending/overdue task that are not in a Closed state
• Recent tickets you have viewed
• Tickets assigned to you that are not in a Closed state
• Tickets you are CC’d on that are not in a Closed state

It also allows you to quickly manage your tasks by seeing the notes you have left for said task, when it is due, and a button to quickly mark the task as done (remove the notes and due date).

App information:

• Located in the navbar
• This application was developed in-house and can be found GitLab Reminders App project.

GitLab Super App

A plugin controlled app that can do several things GitLab related

The current plugins are:

• User Lookup

  This lets you search gitlab.com for a username or email. It then displays information based on the results.

• Namespace Lookup

  This lets you search gitlab.com for a namespace. It then displays information based on the results.

• Collaboration Project

  This checks the organization for a collaboration project ID. If one exists, it then provides a link to said project.

• Two Factor Auth Helper

  This creates a usable form to checking if a 2FA verification has passed. It calculates the Risk Factor from the Data Classification and modifies it to reflect the passed challenges.

• Email Suppressions

  This searches mailgun for suppressions from bounces (note it does not do it on complaints or unsubscribes). It will display the results (with the message for the suppression).

  It also gives the option of removing the suppression (if one if found). Doing so deletes it from mailgun and adds an intenral comment on the ticket with the results of the suppression deletion.

• Fieldnotes

  This app checks the Fieldnotes project for any existing Issues which reference the current Zendesk ticket ID. If no existing Issues are found, then agents are able to create a new Fieldnotes Issue from directly within the Zendesk ticket.

App information:

• Located in the ticket sidebar
• This application was developed in-house and can be found Zendesk Supper App project.

Mechanizer

This app incorporates Mechanizer into Zendesk.

App information:

• Located in the ticket sidebar
• This application was developed in-house and can be found at Mechanizer project

Out of Office

This will enable an agent to mark when they are out of office in Zendesk, which then updates tickets and makes it visible in the views.

Managers are also able to do this for their reports.

App information:

• Located in the navbar
• This application was developed in-house and can be found Out of Office project

Ticket Redaction App

This allows for redacting content in a ticket. You input a string or URL for the app to check for. If it finds it, it removes said string and inserts a black bar over the string (if an attachment, it replaces the attachment with a redacted text file).

App information:

• Located in the ticket sidebar
• Restricted by Role
  • Administrator
  • Support Managers
  • Support Staff
  • Support Staff - Explore
• This application was developed by Zendesk and is available in the Zendesk Marketplace.

Unbabel

Powered by state-of-the-art AI and a worldwide community of translators, Unbabel delivers translation at enterprise scale. We help you serve customers in any language, with fast, native-quality translations of your customer support tickets in Zendesk.

App information:

• Located in the ticket sidebar
• Restricted by Role:
  • Administrator
  • GitLab Staff
  • GitLab Staff - Delete tickets
  • GitLab Staff - Explore
  • Support Managers
  • Support Staff
  • Support Staff - Explore
  • Support Staff - Professional Services
  • Tech Support
• This application was developed by Unbabel and is available in the Zendesk Marketplace.

Configuring Unbabel in Zendesk

Every Agent profile in Zendesk needs to be individually configured so that only tickets submitted in the supported languages are translated.

To do this you can use a javascript snippet created internally.

You can also do the configuration manually by following these steps.

1. Open any existing ticket in Zendesk and navigate to and open the Apps sidebar.
2. Scroll to the Unbabel app and click on Settings.
3. Add all the languages except those supported by GitLab to the “Languages you speak” list.
4. When you are finished, click the Save button.

Replying with a Translation

To request a translation automatically, simply reply as you normally would as an internal note with the #unbabel hashtag included at the top of your content. As per our working with tickets workflow, please remember to assign yourself to the ticket if the ticket doesn’t currently have an assignee when you respond.

Please also ensure that the unbabel_en, unbabel_reply, unbabeled tags are included, otherwise your response might not be translated automatically. Should this happen, you will need to add the missing tags, and create a new internal note with the #unbabel hashtag included at the top of your content.

Once you submit your response, it may take several seconds for Unbabel to automatically translate your internal comment, but it can take several minutes if a human is required to manually translate your internal comment. To view the status of the translation, you can open the Apps sidebar in the ticket, and scroll down to the Unbabel for Zendesk Support box.

After a translated response has been sent to the customer via Unbabel it is necessary to manually set the ticket status as Pending since Unbabel will incorrectly set the ticket status as Open. You must do this with an empty comment (remove any #unbabel added by the plugin, before you Submit as Pending).

Excluding Text from Translation

The highlighted code can be skipped for translation by adding 3 brackets around the text:

<<< text/code >>>

The above can also be used to protect sensitive information from a human translator when sending a translation request.

Disabling Unbabel in a Specific Ticket

Sometimes Unbabel is triggered if a customer’s signature was written in a language that requires translation but the customer replies in English, and the translation is not needed. In this case, there is a way to disable Unbabel in this specific ticket:

• Open the ticket in question.
• Click Apps > Unbabel for Zendesk Support.
• Change the Customer language to English.

From now on, Unbabel will not be triggered in this ticket.

Help with Translation

If for some reason you have difficulty in understanding the automated translation, an actual human intervention can actually be requested. Simply click the link Can’t understand the translation? in the Unbabel app box and this will send your response for translation to Unbabel editors.

Best Practices for Unbabel

As indicated in the training session, please keep in mind of the following best practices when writing a response for translation.

• Respond in one language
  • It is likely that you can speak another language and understand what the customer is trying to say. Please ensure that you only use the English language when responding tickets as the system may not detect the language correctly.
• Copy only the body of the content that needs translation.
  • When referring to a quoted texts from our customers, please only use the content that requires translation. Including snippets/code/elements may take more time to translate and could result in a mistranslation.
• Mind the punctuation.
  • Punctuation can be sometimes tricky for Unbabel so please be sure there are no unnecessary periods/punctuations in between.
• Single Word Use
  • It is likely that the response you are sending may be lost in translation, for example the word pass would differ to a boarding pass.

Zendesk Triggers

Unbabel relies on two Zendesk triggers to work properly. These should never be changed, as it can cause significant problems.

• Unbabel for agent
• Unbabel for user

Zendesk Super App

A plugin controlled app that can do several things Zendesk related

The current plugins are:

• Due date picker

  This allows you to customize what the Due Date for a Task ticket is set for. By default, Zendesk only allows setting the date. This enables you to set the date, time, and timezone.

  You can also set the Due Date Note and disable (or enable) task notifications using this app.

• Escalated tickets

  This searches for tickets under the organization that have been escalated within the last 6 months.

• Related tickets

  This looks for tickets related to the current one based off the category (or subcategory) the ticket is currently using. It then displays up to 5 of them (sorted by the update_at value of the ticket, descending).

• Support Uploader

  A simple app to create FTP credentials for a ticket.

• Attachments

  Displays attachments present on the ticket.

App information:

• Located in the ticket sidebar
• This application was developed in-house and can be found Zendesk Supper App project.

Zendesk US Federal App List

Zendesk US Federal has some similiar apps as Zendesk Global. The ones they have in common are:

• Advanced Search
• GitLab Reminders App
• Out of Office
• Ticket Redaction App

Architecture Diagrams

This app uses the Organization field AM Project ID to check for an existing Account Management project. If it finds it, it will then link to that project’s Architecture Diagram.

NOTE: The AM Project ID field is manually populated. To get that added in, you would want to submit a Support Ops Project issue.

App information:

• Located in the ticket sidebar
• This application was developed in-house and can be found GitLab Architecture project.

Due Date Picker

This is a GitLab built app that allows you to customize what the Due Date for a Task ticket is set for. By default, Zendesk only allows setting the date. This enables you to set the date, time, and timezone.

App information:

• Located in the ticket sidebar
• This application was developed in-house and can be found Due Date Picker project.

GitLab User Lookup

This app looks in Salesforce and GitLab.com for a contact or account based on the requestor’s email address and provided GitLab.com username. If it finds a GitLab.com account, it will present some basic account information as well as the membership of the user (and the corresponding plans of said memberships). The app also does checks to determine if the requester is an enterprise user. If it determines they are, it displays this in the app’s output and auto-tags the ticket using the enterprise_user tag.

App information:

• Located in the ticket sidebar
• This application was developed in-house and can be found GitLab User Lookup.

Show Related Tickets

This uses the ticket subject to search for other tickets with a similar subject. This helps to locate potentially related tickets you can check to see how they were solved.

App information:

• Located in the ticket sidebar
• This application was developed by Zendesk and is available in the Zendesk Marketplace.

Understanding Zendesk Apps

Before you can start creating and editing apps in Zendesk, it is important to understand the ins and outs of both Zendesk Apps and Zendesk Apps framework.

There is a lot to this, so the Zendesk documentation is the best resource you have to learn the various ins and outs. This training documentation will cover what is viewed at “the most important” parts, but it is highly recommended you read and reference the Zendesk developer documentation as often as possible.

ZAT

ZAT, or Zendesk App Tools, is a ruby gem that makes working with Zendesk Apps locally considerably easier. It is highly recommended you install it on your computer:

1
2

gem install rake
gem install zendesk_apps_tools

To update it:

1
2

gem update rake
gem update zendesk_apps_tools

Sometimes on Mac terminal, you will get write permission error. You may use:

1
2

sudo gem update rake
sudo gem update zendesk_apps_tools

Note: ZAT is having issues with Ruby version 3.0.0 and plus. You’ll likely need to use old stable versions like 2.6.3p62

manifest.json

This file is used to configure you application. As such, it is very important and vital it is accurate.

The common configuration settings are:

Location

This setting determines where the app will appear and run. This is a very important setting. The first setting determines the product type location, and within that setting you can specify many other configurations, including the physical location the app will appear in. For the product type location, we always use support.

The physical locations are as follows:

Within the physical location settings, you can include more configuration settings, with the most common being:

As an example, to have an app load “https://google.com” automatically in the ticket sidebar with a starting height of 200px, your configuration block would look like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

"location": {
  "support": {
    "ticket_sidebar": {
      "autoLoad": true,
      "url": "https://google.com/",
      "size": {
        "height": "200px"
      }
    }
  }
}

As another example, to have your app load in both the user and organization pages, rendering the locale assets/iframe.html file, you would do this:

1
2
3
4
5
6

"location": {
  "support": {
    "user_sidebar": "assets/iframe.html",
    "organization_sidebar": "assets/iframe.html",
  }
}

Parameters

This is where you would define variables you want the app to use during installation.

Domain whitelists

If your app is using secure parameters and you plan to make requests outside of Zendesk, you must whitelist the domains in question. Each parameter is a hash that contains the following:

• name: the name of the parameter
• type: the type of parameter
• secure: ensures users cannot see the variable value when making HTTP requests (you should always use this)
• require: specifies if the parameter is required for installation

As an example, to use two required parameters (param1 and param2), both of which are text parameters in a secure way, you would do the following:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

"parameters": [
  {
    "name": "param1",
    "type": "text",
    "secure": true,
    "required": true
  },
  {
    "name": "param2",
    "type": "text",
    "secure": true,
    "required": true
  }
]

During the installation of the app, Zendesk will ask you to give the values for these parameters. To utilize this in the code of your app, you will use this:

{{setting.NAME_OF_PARAMETER}}

Where NAME_OF_PARAMETER is the name you gave the parameter in the manifest.json file.

init

To create a client instance of the ZAF (Zendesk App Framework) client, you need to ensure the following is present in the javascript of your app:

1

var client = ZAFClient.init();

App resizing

To resize the app during runtime, you would use the invoke class, specifying you wish to invoke the resize function. This is done like so:

1
2
3

// First line shown to clarify you use the ZAF client object to do this
var zafclient = ZAFClient.init();
zafclient.invoke('resize', { width: '100%', height: '100px' });

Required javascript library

To utilize the ZAT, you must include the following javascript in your app’s HTML file(s):

1

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

Getting metadata

To get metadata and use it in your app, you need to use the ZAF client’s get function. This takes an array of values to get from the ticket metadata, which you use in a function.

As an example, to get the ticket requester’s name and the ticket’s organization, and then log them to the console, you would do the following:

1
2
3
4
5
6

// First line shown to clarify you use the ZAF client object to do this
var zafclient = ZAFClient.init();
zafclient.get(['ticket.requester.name', 'ticket.organization']).then(function(data) {
  console.log("Ticket requester name: " + data['ticket.requester.name']);
  console.log("Ticket organization: " + data['ticket.organization']);
});

As another example, to get the ticket’s due date and the due date notes (a custom ticket field) and then log them to the console, you would do the following:

1
2
3
4
5
6

// First line shown to clarify you use the ZAF client object to do this
var zafclient = ZAFClient.init();
zafclient.get(['ticket.customField:due_date', 'ticket.customField:custom_field_360017383799']).then(function(data) {
  console.log("Due date": + data['ticket.customField:due_date']);
  console.log("Due date notes:" + data['ticket.customField:custom_field_360017383799']);
});

Making requests

Your app might need to make requests, whether they be “internal” (i.e. within Zendesk itself) or external. To do this, we use the request function of the client object.

The format of this is very close to that of making AJAX requests in jQuery. The format you will normally use is:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

// First line shown to clarify you use the ZAF client object to do this
var zafclient = ZAFClient.init();
zafclient.request({
  method: 'REQUEST_TYPE',
  url: 'URL_TO_USE',
  contentType: 'CONTENT_MEDIA_TO_SEND',
  data: DATA_OBJECT,
  secure: BOOLEAN,
  headers: HEADERS_OBJECT
}).then(function(data) {
  // do stuff
});

The exact parameters in the request will vary from request to request.

As an example, if you wanted to update the due date of a ticket, you might do:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

// First line shown to clarify you use the ZAF client object to do this
var zafclient = ZAFClient.init();
zafclient.request({
  method: 'PUT',
  url: '/api/v2/tickets/123456.json',
  contentType: 'application/json',
  data: JSON.stringify({
    due_at: new Date('2021-01-01').toISOString()
  }),
  secure: BOOLEAN,
  headers: HEADERS_OBJECT
}).then(function(data) {
  console.log('Due date updated to 2021-01-01');
});

As another example, if you wanted to make a GET request to gitlab.com to find information about user ID 987654, using a secure parameter from app installation, you might do:

1
2
3
4
5
6
7
8
9

// First line shown to clarify you use the ZAF client object to do this
var zafclient = ZAFClient.init();
zafclient.request({
  method: "GET",
  url: 'https://gitlab.com/api/v4/users/987654?private_token={{setting.GitLab_token}}',
  secure: true
}).then(function(data) {
  console.log('User email: ' + data.email);
});

How to create a Zendesk App

To create a Zendesk app, you will first make a new folder on your local computer (where you will build the app) and cd into the new directory:

1
2

jcolyer@jcolyer-Desktop:~$ mkdir my_new_app
jcolyer@jcolyer-Desktop:~$ cd my_new_app

From there, run the command zat new and fill out the requested details (author name, author email, app URL, app name, iFrame URI, directory). After doing so, you will have the baseline files you need to create your application.

jcolyer@jcolyer-Desktop:~/my_new_app$ zat new
Enter this app author's name:
 test
Enter this app author's email:
 test@test.com
Enter this app author's url:
 https://gitlab.com/test/my_new_app
Enter a name for this new app:
 Test App
Enter your iFrame URI or leave it blank to use a default local template page:
 (assets/iframe.html)
Enter a directory name to save the new app (will create the dir if it does not exist):
 (./)
       exist  
      create  README.md
      create  assets/iframe.html
      create  assets/logo-small.png
      create  assets/logo.png
      create  assets/logo.svg
      create  manifest.json
      create  translations/en.json

From here, you will edit the files for your app. By default, assets/iframe.html will be the main file you will work out of (although you can have the javascript load from a separate file and work from there if you so desire).

Once you are done creating your application, you will need to package it. To do this, run the command zat package:

jcolyer@jcolyer-Desktop:~/my_new_app$ zat package
        info  Checking for new version of zendesk_apps_tools
     warning  Your version of Zendesk Apps Tools is outdated. Update by running: gem update zendesk_apps_tools
    validate  OK
     warning  Please note that the name key of manifest.json is currently only used in development.
     package  adding translations/en.json
     package  adding manifest.json
     package  adding README.md
     package  adding assets/logo.png
     package  adding assets/iframe.html
     package  adding assets/logo-small.png
     package  adding assets/logo.svg
     package  created at ./tmp/app-20210920131122.zip

Alternatively to this, you can manually package the app using the zip command:

1
2

jcolyer@jcolyer-Desktop:~/my_new_app$ zip -r application.zip - -x .git
jcolyer@jcolyer-Desktop:~/my_new_app$

The created zip file it what contains your Zendesk App. Go to the Admin Center (Zendesk Global / Zendesk US Federal), locate the Apps management pages under Apps and integrations > Apps > Zendesk Support apps. On this page, click the white Upload private app button in the top-right of the page.

On this page, enter the App’s name and select the zip file from your local computer. After doing so, click the black Upload button. A pop-up will appear asking you to confirm the upload. Click the black Upload button once more to confirm.

After it installs the app, you will be brought to the app management page for your new app. If you used any parameters, you would add them here. You also have the option to set role or group restrictions if needed. Once you are done, click the blue Install button.

How to update a Zendesk App

To update an app, you edit the code and the version (found in the manifest.json file) and package it up (much like when creating an app).

After doing so, go to the Admin Center and locate the Apps management pages under Apps and integrations > Apps > Zendesk Support apps. On this page, locate the app you are updating, hover over it, and click the down arrow that appears (next to a gear icon). Click the Update option to proceed.

From here, it is basically the same as creating a new app. You select the file from your local computer, click the black Upload link, and the app updates.

How to deactivate a Zendesk App

Note To keep the Apps management page clean, we aim to uninstall an app instead of just deactivating it.

To deactivate an app, go to the Admin Center and locate the Apps management pages under Apps and integrations > Apps > Zendesk Support apps. On this page, locate the app you are deactivating, hover over it, and click the down arrow that appears (next to a gear icon). Click the Uninstall option to proceed. A pop-up will ask you to confirm the uninstall process. Click the blue Uninstall button to confirm.

Testing an app

There are two ways to test a Zendesk app before you put it into production:

Locally

Note: This cannot be done if your app is using secure parameters. Instead, you would need to install the app into the Sandbox and test from there.

To test your app locally, cd into the app directory on your local computer and then run the zat server command. This will start up a ZAT server on your computer. Once it has booted up, go to a Zendesk URL and put ?zat=true at the end. This will now load the apps from your local computer, allowing you to test out the app locally.

Via the Sandbox

If your app is using secure parameters, you will need to test via the Sandbox instead. Follow the process for creating an app or for updating an app (whichever fits best) to get the app into the Sandbox and then you can test from there.

Change management

As these are maintained via repositories, our standard change management process applies to all Zendesk apps. See standard change management for more information.

Labels to use

For all issues and MRs involving apps, the label Support-Ops-Category::Apps should be used.

Change criticality

As Zendesk apps tend to have far less of an impact, adding/editing/deleting Zendesk apps will be classified as either criticality 3 or criticality 4