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. Starting with macOS Catalina (macOS 10.15), Terminal uses the Z shell (zsh) as the default 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 :
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.
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
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:
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:
cd ..
- 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.
- 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-app
Note: 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:
https://subdomain.zendesk.com/agent/tickets/321
- 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.
- If you're using the Chrome browser, the content of your app may be blocked. Click the lock icon on the left side of the address bar and select Site settings. On the Settings page, scroll to the Insecure Content section and select Allow.
Click the lock icon in the address bar:
Select Site Settings > Privacy and Security, then select Allow from the Insecure content menu:Note: Firefox doesn't block app content but Safari does and has no option to disable blocking. You must use Chrome or Firefox to work with the local zat server..
- 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
-p
option. Example:$ 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.
Example: http://yoursubdomain.zendesk.com.
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.
23 Comments
Is it possible to pass the parameters in the "zat server" command, or even better, could the server be configured to read from an config file?
Yes. From version 1.20.0 it will automatically read from a settings.yml file in your current working directory. Or you pass it a file with the -c option.
When I'm running zat server, is it also supposed to stop me from affecting the zendesk tickets themselves? For example, say my app has a button that changes the ticket status to "pending" and add a "we'll get back to you" canned comment. If I click that button while ?zat=true, then will it change that ticket in real life?
Hi Mzhu,
Any changes made while '?zat=true' runs will be changed just like in real life. We recommend making a test account, populating it with test data, and experimenting on that. If you have any questions about how to set up a testing account, just let me know. Also, what are you making?
Angie
To use the gem install macOS Mojave requires installing the XCode tools:
You might want to add that to the install steps/
If you are familiar with docker, you can use the following docker image that simplifies the setup:
"zat": "docker run --rm -v `pwd`:/data --publish 4567:4567 bertrandgressier/zat-docker serve --unattended --bind=0.0.0.0"
Had a horrible time with installing this on MacOS the trick is to install with the following:
sudo gem install zendesk_apps_tools -- --use-system-libraries
the documentation on this page should add those options switches.
Here are the things I had to do to get ZAT working on Windows using Ubuntu and Ruby 2.5.1+
After all that success!
Developing our ZenDesk application in Windows 10, ASP.NET. Is it possible to still test this using ZAT, which would run the emulator "host", but still have the application running pages on the Windows 10 box? Need access to real tickets while developing and developing a full featured app in Linux is not realistic for our needs.
So... can ZAT run in the Ubuntu shell, but access a site on the actual Windows 10 machine?
Hi Kevin-
Check out this post on how to open a browser in your host system from the Linux subsystem.
I've successfully created a test app and I am able to view it in my zendesk subdomain. How does my Zendesk instance subdomain.zendesk.com know where to find the iframe ? If I were to run ZAT server on another machine, how do I configure Zendesk to look for the iframe from that server?
Hi Michael. 'zat server' is for development only. It allows you to quickly change an app's source on a specific development machine and try out those changes from that same machine. This avoids having to re-upload the app to your test instance every time there's a source code change (nice when you're changing and trying things out quickly).
When it's ready for production, you would run 'zat package' and go into your account's Admin > Apps/Manage page and select 'Upload private app' (and select the .zip file from the app project's ./tmp folder).
For non-private/public marketplace apps, there's another process for that: https://developer.zendesk.com/apps/docs/publish/partner_program_intro
Hope this helps clarify things a bit.
This was a fresh install on Windows 10, It gave me errors when running
I executed
problem was solved.
I was trying to install zendesk_apps_tools in windows 10 linux subsystem with errors concerning missing packages...
After some reading to my logs and installing the below it worked like a charm:
The packages were missing from my default installation in ubuntu windows
Hi. Newbie to ZAT and struggling to get my browser/chrome to pickup my local app.
ZAT (3.7.1) is running and web server started/listening
Ruby (2.5.1p57) installed and running
chome security settings set
But when I run our sandbox zendesk site with "?zat=true" my app never gets displayed.
I'm able to manually install and run it without issue.
Any advice?
Hi Todd Holtmann -- Chrome changed relatively recently on how it handles "insecure" content. Since when running 'zat server' content is being pulled from a locally running server, you'll need to "Allow insecure content".
You can quickly set what's needed by going to:
1. chrome://settings/content/insecureContent
2. Then using adding under "Allow": [*.]zendesk.com to cover all subdomains (if you're developing under more than one)
See this community thread, which has more details: https://develop.zendesk.com/hc/en-us/community/posts/360004253088-Mixed-Content-using-ZAT-Chrome#community_comment_360010124294
Adding to what Argyris Gerogiannis said, it now seems you also have to install zlib1g-dev to get it to work on Ubuntu. Its taken me hours to find this out, hopefully ZenDesk will update the documentation.
Charles Nadeau,
I can´t install ZAT on MacOs (Big Sur). I am getting this error:
Building native extensions. This could take a while...
ERROR: Error installing zendesk_apps_tools:
ERROR: Failed to build gem native extension.
current directory: /Library/Ruby/Gems/2.6.0/gems/thin-1.7.2/ext/thin_parser
/System/Library/Frameworks/Ruby.framework/Versions/2.6/usr/bin/ruby -I /System/Library/Frameworks/Ruby.framework/Versions/2.6/usr/lib/ruby/2.6.0 -r ./siteconf20201127-3041-15b0xeb.rb extconf.rb
/System/Library/Frameworks/Ruby.framework/Versions/2.6/usr/lib/ruby/2.6.0/universal-darwin20/rbconfig.rb:229: warning: Insecure world writable dir /Applications/XAMPP/xamppfiles in PATH, mode 040777
checking for main() in -lc... yes
creating Makefile
[.....]
I tried this:
sudo gem install thin -- --with-cflags="-Wno-error=implicit-function-declaration"
But it didn´t work.
Do you know how to fix it? I have been Googling it for a while, and could not find anything useful.
Thanks a lot :)
Hi Cesar. Try this modified command, which contains a specific version number for the "thin" gem:
And just for reference, while this other post references Catalina, some here in the community have said it got them working:
Fix for ZAT Tools not running under macOS Catalina
On a side note, for my Ruby environment, I used rbenv to manage my different Ruby versions. The instructions here for setting up an environment that uses rbenv should still work on Big Sur: System prep for app developers
Hi Gary Kester I know this doesn't help with your Ruby woes, but you might like to try the new node.js based CLI - https://github.com/zendesk/zcli
I found it much easier to get going on Windows. It's still in beta I think, but it seems to work pretty well.
Hi @.... I managed to get it all up and running using ZCLI instead of ZAT which I installed on a separate pc.
I had to figure a few things but got there eventually.
Some points to note:
At this point, I've managed to create a custom application and load it into Zendesk that my support team is busy testing.
Regards,
Gary
I'm running into a brick wall with instaling ZAT tools on a Mac (Catalina 10.15.7 (19H2)). I have Ruby installed (ruby 2.6.3p62 (2019-04-16 revision 67580) [universal.x86_64-darwin19]) but when I try to install zat, I keep getting a makefile error. I have reviewed the log, installed XCode and Homebrew (based on advice from various forums)...and generally I have been down rabbit holes all over the web trying to resolve this, but so far no joy. I would appreciate any help! I am feeling quite stuck.

Gary Kester that's great to hear. I'll forward this to the product team with your earlier issue, just to keep them up-to-date.
Marci Abraham — This has come up recently with some other users and looks like it has to do with Big Sur/XCode changes. Try the below (but as mentioned in a previous comment above, the 'zcli' option is the better long term approach as this will be the only tool available after 'zat' is end-of-lifed down the road).
OPTION 1:
Does a line appear after the above output look like this? Have you looked into this file and it says something about openssl? This is a compile-time issue. There's a dependency that isn't being met with the current macOS and/or openssl features installed.
It's not clear what exactly is missing at this point in your environment, but if you can resolve the dependencies mentioned in the mkmf.log, that may get things working.
OPTION 2:
Relying on the macOS, natively installed version of Ruby limits your ability to change versions easily. I don't know if you use package manager "Homebrew" and Ruby version manager "rbenv", but they can make setup and changes a lot easier. To see an alternative environment setup approach that uses these tools, see System prep for app developers.
Part of those steps are installing and using Homebrew and rbenv. These will let you move away from the default version of Ruby that comes with macOS (2.6, which is a couple of years old) and move to a newer version easily, such as 2.7.2. Using this environment may also end up resolving these build dependencies.
OPTION 3:
As mentioned above, 'zat' is going to be deprecated and at some point and end-of-lifed (possibly within the next year). If you want to get ahead of the curve, you can switch to 'zcli' — the new command line tool to build ZAF apps. See https://developer.zendesk.com/apps/docs/developer-guide/zcli
Despite it being "beta", it is close to a shipping state (i.e. stable) and will probably be generally available in Q1 of 2021. It's set of dependencies are different than the 'zat' tool's and will avoid errors such as the one you're running into.
So those are a few things to consider. If any of them *do* get you going, please post back here and share what worked!
Please sign in to leave a comment.