Debugging the Zendesk Apps framework (ZAF)

The Zendesk Apps framework allows you to build apps with complex functionalities and features. It's important to establish a set of good practices and behaviours when it comes to debugging a malfunctioning app.

This article provides guidelines on how to approach the most common scenarios.

DISCLAIMER: The Zendesk Support Team can only assist in demonstrating the capabilities and functionalities of the Zendesk Apps framework (ZAF). Any issue concerning custom code or implementations must be discussed with the app developers.

‣ CAPTURE THE ERRORS

When an app is showing an unexpected behaviour, chances are some errors are produced. The place where these errors can be gathered for further research is the browser's developer tools console window.

Access the console on Chrome

• To open the console window on Chrome, use the keyboard shortcut Cmd+Shift+J  (on Windows) or Cmd+Option+J (on Mac). Or by selecting View > Developer > Developer Tools.

Access the console on Firefox

• To open the console on Firefox, the keyboard shortcut is Cmd+Shift+K  (on Windows) or Cmd+Option+K (on Mac). Or by selecting Tools > Web Developer > Web Console.

Access the console on Safari

1. To open the console on Safari, you will first need to turn on the Develop menu. To do this, open the Safari menu in the Mac menu bar, then select Preferences.
2. Once in the Preferences dialog, navigate to the Advanced tab, then check the "Show Develop menu in the menu bar" box.
3. Once the Develop menu has been enabled, you can go to the Develop menu in the menu bar and then select the "Show JavaScript Console" option.

Access the console on Microsoft Edge

• To open the console on Edge, hit F12 to access the F12 Developer Tools. Once in the F12 Developer Tools, navigate to the Console tab.

Any error or warning message will be displayed in the Console tab. For Network request errors, you want to take a look at the browser's developer tools network tab.

‣ GENERATE A LIST OF THE INSTALLED APPS

It's not uncommon having multiple apps installed in the same Zendesk account. It can be useful to have a list of all the apps installed in the account.

The API endpoint List App Installations generates a JSON list of installed apps. Properties included can be used for the noapps and app_ids query parameters discussed later:

• enabled: that indicates whether or not an app is currently active
• app_id: the id of the app. This is needed when using the app_ids debug query parameter.
• installation ID: the installation ID of the app. This can optionally be used for the noapps debug query parameter. Apps can be installed multiple times, if the app allows it. Each install will have a different installation ID but have the same app ID.

To access the endpoint, you must be an Agent or Admin in the Zendesk account.

You can access the endpoint in different ways:

Using curl:

curl https://{subdomain}.zendesk.com/api/v2/apps/installations.json \
  -u {email_address}:{password}

Appending /api/v2/apps/installations.json to the account's subdomain URL:

https://your_subdomain.zendesk.com/api/v2/apps/installations.json

‣ IDENTIFY THE APP

In the debugging phase, it's important to be able to selectively activate and deactivate apps.

You can deactivate an app in two ways:

1. Via the Zendesk Support interface, as shown in Managing your installed apps. This disables the app entirely. It can be re-activated in the same way.
2. Via the current session. Disable the app by appending the following suffix to the ticket URL:

?noapps 

https://your_subdomain.zendesk.com/agent/tickets/123456?noapps

For more details and tips about avoid apps conflicts, see Avoid conflicts between applications.

‣ GENERATE A HAR FILE 

The HAR file (short for HTTP Archive) is a standard format used to track information and events between a browser and a website. It is always a good idea to record the network events in a HAR file to troubleshoot performance or rendering issues.

To generate a HAR file, see Generating HAR file for troubleshooting.

‣ USING THE APPS API FOR TROUBLESHOOTING 

We have already mentioned how to leverage the API endpoint List App Installations to generate a list of the installed apps. Among the properties contained in the JSON response, we find the installation ID.

The installation ID can be used as a query parameter for ?noapps to disable multiple apps at the same time:

https://your_subdomain.zendesk.com/agent/tickets/123456?noapps=11111,22222,44444 

‣ HOW TO BUILD AN APP 

How-to: install and use ZAT on MacOS, Window and Linux.

• Installing and using the Zendesk Apps Tool

How-to: build a Support app from scratch

1. Build your first Support app - Part 1: Laying the groundwork
2. Build your first Support app - Part 2: Designing the user interface
3. Build your first Support app - Part 3: Creating and inserting templates
4. Build your first Support app - Part 4: Getting data
5. Build your first Support app - Part 5: Installing the app in Zendesk Support

How-to: build a server-side app

1. Core concepts
2. Display server-side content in a Zendesk app
3. Access external APIs
4. Access framework APIs
5. Deploy the app
6. Bonus part: Secure the app

A list of useful links to articles and tutorials about the Zendesk Apps Framework.

• Managing your installed apps
• Why can't I download apps?
• Uploading and installing a private app