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:
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
- Open the Windows Start Menu, type cmd in the search box, press Enter to open the command prompt.
- Run the following command at the command prompt :
The bash shell opens after a moment.
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.
Installing Ruby in macOS
Installing Ruby in Ubuntu for Windows 10
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.
sudoto 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.
Zendesk updates ZAT from time to time. To get the latest version, run the following command:
$ gem update zendesk_apps_tools
The ZAT tools let you do the following:
Creating starter files for a new app
You can automatically create basic starter files and folders for a new app.
To create the files
- 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:
- 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
$ 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.
- 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
- In the command-line interface, navigate to the folder containing the app files.
- 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:
After a moment, a status message appears informing you that the server has started. Example:
$ zat server --path /tmp/test-appNote: The command prompt is unavailable until you shut down the server later.
- In your favorite browser, navigate to any ticket in Zendesk Support. The URL should look something like this:
- Append ?zat=true to the ticket URL, and reload the page.
The URL should look like this:
Tip: Bookmark the modified URL for easy access in the future. You might also want to create a dummy ticket for app testing.
- 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.
- 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.
- 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.
- 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
- 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
$ zat validate -p ./dist
- 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.
- 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.
- Run the following command in the folder containing the app files:
$ zat package
- 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.
The ZAT tool packages the app and saves it in a tmp folder. Example:
- Grab the zip file (app-20130110164906.zip in the example) and upload it to Zendesk Support. For instructions, see Uploading.
- 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.