Installing and using the Zendesk apps tools

Developing Zendesk apps without some local testing tools is possible but not easy. For example, each time you want to test a change, you have to package and upload the app and then install and run it remotely in Zendesk Support. To get around this problem, you can use a collection of local development tools called Zendesk Apps Tools (ZAT). Among other tasks, ZAT lets you do the following:

• Automatically create all the necessary files and folders for a new app
• Test your app locally in a browser
• Validate your app
• Package your app for upload

This article explains how to install and use the tools on the command line in macOS and Ubuntu for Windows 10. It covers the following topics:

• Using the command line
• Installing Ruby
• Installing ZAT
• Updating ZAT
• Using ZAT
• ZAT server limitations

Windows 10 users: Zendesk recommends using Ubuntu for Windows 10 as your apps development environment. Ubuntu is an open-source Linux operating system you can install in Windows 10 from the Microsoft Store. For installation instructions, see Setting up a Bash shell in Windows 10.

See the known issues if you run into any problems installing or using the tools.

If you're just starting out building apps, see Building your first Zendesk app, a five-part tutorial series that teaches you how to build an app from start to finish.

Using the command line

ZAT is a command-line application. You type commands at the command line to accomplish different tasks. Example:

$ zat new

This section describes how to open the default command line interface of each operating system.

Working in macOS

In macOS, you can run ZAT commands using Terminal, which is a Bash shell.

To open Terminal

• Double-click the Terminal application in your Applications/Utilities folder.

Working in Ubuntu for Windows 10

In Ubuntu for Windows 10, use the default Bash shell to run ZAT commands.

To open the Bash shell

1. Open the Windows Start Menu, type cmd in the search box, press Enter to open the command prompt.
2. Run the following command at the command prompt :

   c:\> bash

   The bash shell opens after a moment.

   Example:

   

Installing Ruby

ZAT is a Ruby gem -- a self-contained package of Ruby code that extends Ruby. You don't need to know Ruby to use the tools but you do need to install Ruby to install the gem.

ZAT supports Ruby 2.1 or later on macOS and Ubuntu, and Ruby 2.3 only on Windows.

Ruby may already be installed on your system. Open your command-line interface and run the following command:

$ ruby -v

You should see something like the following response:

If you get an error, Ruby is not installed. If the result is a Ruby version earlier than 2.1, you'll need to update it. If the result is Ruby 2.1 or better, you don't need to do anything. Skip to Installing the ZAT gem.

Important: Zendesk can't provide support for third party technologies like package managers and Ruby installers. If you run into trouble, try searching for the error message in Google. User forums provide the answers to most Ruby questions.

Installing Ruby in macOS

Ruby is included with all modern versions of macOS (10.9 and later). If you have Ruby 2.1 or later, you can skip this section and go to Installing ZAT.

If you need to update Ruby, see Managing Ruby versions.

Installing Ruby in Ubuntu for Windows 10

Ruby is included with Ubuntu for Windows 10. If you have Ruby 2.1 or later, you can skip this section and go to Installing ZAT.

If you need to update Ruby, see Managing Ruby versions.

Installing Ruby in Windows

ZAT only supports Ruby 2.3 for Windows because Ruby 2.4 and later has a dependency issue that prevents ZAT from working. Earlier versions of Ruby are not supported. As a result, consider using Ubuntu for Windows 10 as your development environment. For installation instructions, see Setting up a Bash shell in Windows 10.

If you decide to use Ruby 2.3 for Windows, make sure to install the Ruby Development Kit (DevKit) after installing Ruby. See the downloads page on the RubyInstaller site.

Installing ZAT

Note: If you're using macOS or Ubuntu and any of the following commands complains that you don't have write permissions for a directory, start the command with sudo to request admin privileges, then enter the password for your system when prompted. Example: $ sudo gem install rake.

First, install rake, a build automation tool, with the following command in your command-line interface:

$ gem install rake

Next, install ZAT with the following command:

$ gem install zendesk_apps_tools

The ZAT gem and a number of supporting gems are installed, along with related documentation.

Updating ZAT

Zendesk updates ZAT from time to time. To get the latest version, run the following command:

$ gem update zendesk_apps_tools

Using ZAT

The ZAT tools let you do the following:

• Create starter files for a new app
• Test your app locally in a browser
• Validate your app
• Packaging your app for upload to Zendesk Support

Creating starter files for a new app

You can automatically create basic starter files and folders for a new app.

To create the files

1. In the command-line interface, navigate to the folder where you want the app files to be saved in a subfolder.

   Use the cd command (for change directory) to navigate to a child folder. Example:

   $ cd zendesk_app_projects

   To back up one directory, use cd followed by a space and two periods. Example:

   cd ..

2. Run the following command:

   $ zat new

   The command creates a set of starter files to use with the Zendesk Apps framework v2 (ZAF v2). To learn more, see the ZAF v2 documentation.

   Alternatively, you can start an app with the Zendesk app scaffold with the --scaffold option:

   $ zat new --scaffold

   See the app scaffold readme on Github.

   Note: The app scaffold is for advanced web developers. Zendesk can't provide support for third-party technologies used in the scaffold, nor can Zendesk debug custom scaffold configurations or code.

3. At the prompts, enter your name and email, the app's name, the URL of the file to be iframed (if any), and a folder name for the app.

   ZAF v2 apps are iframe apps. If you don't specify the URL to an iframe file, ZAT will create a basic HTML file that you can use in an iframe.

   The tool creates and lists the files. The window should look as follows in macOS:

   

Testing your app locally in a browser

You can start a local HTTP server and run your app locally. This ability is essential for testing and debugging your app. You don't have to package and upload the app to Zendesk Support first.

This feature is supported in Chrome and Firefox, but not Safari 9 or later. To test your app locally, ZAT runs a local http server and loads the app in the Zendesk Support https page. This results in mixed content. Chrome and Firefox block mixed content but provide a way to turn off the blocking. Starting with version 9, Safari also blocks mixed content but doesn't provide a way to turn off blocking.

Some features may not work locally. See ZAT server limitations.

To test your app locally

1. In the command-line interface, navigate to the folder containing the app files.
2. Start the local HTTP server with the following command:

   $ zat server

   If you get an error, make sure you navigate to your app's folder using the command line. You can start the server from a different folder by specifying the relative path to the files:

   $ zat server --path /tmp/test-app

   After a moment, a status message appears informing you that the server has started. Example:

   

   Note: The command prompt is unavailable until you shut down the server later.
3. In your favorite browser, navigate to any ticket in Zendesk Support. The URL should look something like this:

   https://subdomain.zendesk.com/agent/tickets/321

4. Append ?zat=true to the ticket URL, and reload the page.

   The URL should look like this:

   https://subdomain.zendesk.com/agent/tickets/321?zat=true

   Tip: Bookmark the modified URL for easy access in the future. You might also want to create a dummy ticket for app testing.

5. If you're using Chrome or Firefox and now see a shield icon in the Address bar, click the shield icon and agree to load an unsafe script (Chrome) or to disable protection on the page (Firefox). If you don't do this, the browser will block your app from being loaded into Zendesk Support.

   

   In Firefox, the shield icon is located on the left side of the Address bar.

6. Click the Reload Apps icon in the upper-right side of the Apps panel to load your local app into the panel.

   

   Even if the app appears in a Zendesk Support page, it's actually running locally on your machine.

   Note: If nothing happens, check for a shield icon in the Address bar. See step 5.
7. Work iteratively to develop and test features in your app. For example, make some changes to your app's source code, save the changes, then click Reload Apps on the ticket page to test the changes.

   

8. When you're done for the day, press Control+C to shut down the local server.

Validating your app

When you're finished developing your app, you should run validation tests to catch any problems before uploading it to Zendesk Support. The ZAT validation tool runs the same tests that are run when an app is uploaded to the Zendesk App Market.

To validate your app

1. Run the following command in the folder containing the app files:

   $ zat validate

   If using the App scaffold, run the command in the final build folder, which may be dist/ or the root folder depending on the folder structure. You can also specify the path to the final build folder with the -p option. Example: $ zat validate -p ./dist

2. When prompted, enter the URL of the Zendesk Support instance where you plan to install the app. The command doesn't actually install the app. Specify http instead of https in the URL. Example: http://yoursubdomain.zendesk.com.
3. Fix any problems reported by the tool.

Packaging your app for upload to Zendesk Support

When you're ready to upload your app to your instance of Zendesk Support, use the ZAT tool to package the app for uploading.

1. Run the following command in the folder containing the app files:

   $ zat package

2. When prompted, enter the URL of the Zendesk Support instance where you plan to install the app. The command doesn't actually upload and install the app. Also, specify http instead of https in the URL.

   Example: http://yoursubdomain.zendesk.com.

   The ZAT tool packages the app and saves it in a tmp folder. Example:

   

3. Grab the zip file (app-20130110164906.zip in the example) and upload it to Zendesk Support. For instructions, see Uploading.
4. To clean up the tmp folder, run the following command:

   $ zat clean

ZAT server limitations

A few things don't work when running an app locally on the ZAT server:

• secure settings - the ZAT server won't render the settings
• requirements - the requirements aren't installed, so the framework's requirement() method won't work either

To get around these limitations, you can install the app as a private app and then use the zat update command to make updates to the installed app. See Updating an installed app.

For other limitations, see also Zendesk app tools - Known issues.