Build your first Support app - Part 1: Laying the groundwork

Have more questions? Submit a request


  • Patrick Thomas

    On Windows 10, in addition to 32-Bit Ruby 2.3.3, I had to install the Ruby Development Kit (for use with 32 Bit versions): download, make a "devkit" folder under the c:/RubyXX directory and expand it into there, simply to remember where it is.

    In that folder, run "ruby dk.rb init" and "ruby dk.rb install".

    For good measure, one should set the RUBYOPT environment variable to "-E utf-8".

    Only then could I gem-install the Zendesk apps tools.

    From then on, it worked well (except that reloading the App iframe within Zendesk does not work, always have to reload the entire page, but maybe I am overlooking something).

    Also, I don't use jQuery for templating but Vue.js instead, but thats just a matter of personal preference and curiosity.


  • Patrick Thomas

    Sorry, "not using handlebars" for templating. Also, not using jQuery at all.

  • Nicole - Community Manager

    Thanks for helping out, Patrick. Also, I see that this is your first post - welcome to the community!

  • Alex Rojo

    I'm following the tutorial but when I test under Chrome I get this message at Javascript Console:

    Uncaught ReferenceError: $ is not defined
    at main.js:1

  • Feather Osborn

    it seems obviously ridiculous that your link to the next step of the tutorial opens in a new tab. please explain the use case for that, in the context of a linear tutorial. wtf.

  • Joseph May

    Hi Feather-

    This is a contentious topic, as is evidenced by your comment. While I cannot speak for the choice made here, I will suggest you please consider bringing this discussion to our developer community at-large. I am willing to bet this is a design paradigm that would bring a lot of engagement from other developers. Community Discussions & highlights would be where I suggest beginning this topic.

    As I said, this subject can lead to both impassioned debate & fruitful discussion, and I hope to read your use case in our forums to better understand.

    Lastly, I wanted to share this Stack Exchange discussion I found to be the most helpful in terms of further reading (Plus all the links opened in the same window!).


  • Feather Osborn

    >if a link results in leaving the current focus of attention, it should open in a new tab. In contrast, if a link progresses the current locus of attention it should open in the current tab.


    there's also the fact that users can always opt in to opening a link in a new tab (ctl/cmd/middle click). barring extensions and scripts, there is no way to opt out of that behavior.

    perhaps more importantly, opening a linear tutorial's next step in a new tab also destroys your navigation history.

    the options become:

    - leave a half dozen tabs open to reference (that get mixed up with the actual worthwhile references linked throughout the tutorial, like the garden or api reference),

    - or...leave your scroll location on the current tab to get to the top (you can duplicate the tab first so you don't lose your current place, but that's one more tab to clean up later), scroll down until you see the table of contents, and select the previous tutorial from there (which also opens in a new tab [which at least makes sense in this case, but does add one more step to the process of referencing the last tutorial]). then you have to scroll back to the bottom (except you can't actually scroll all the way to the bottom. because comments. so that's an additional manual scroll party).

    the beauty of navigation history is that, not only will you retain your scroll location when you hit forward again, going back will place you at the end of the last tutorial, where you left off, which is the most probable use case for referencing the previous tutorial.


  • Rick Eagle

    I have followed the instructions in this article but may have done something wrong.  In the process of installing zendesk_apps_tools I recieve the following message.

    ERROR: Error installing zendesk_apps_tools:
    nokogiri requires Ruby version < 2.4, >= 1.9.2.

    What do I need to do in order to get past this error?  


  • Joseph May

    Hi Rick-

    May I ask what version of Nokogiri you are using? Nokogiri version 1.8.* ships with support for Ruby 2.4.* (on Windows). In any event I would suggest you

    gem update nokogiri

  • Rick Eagle

    Thank you Joseph.  I issued the command and received this response.   I am new to this so I am sure there is something I have missed.   

    C:\>gem update nokogiri
    Updating installed gems
    Nothing to update

  • Joseph May

    Thanks, Rick. What version is printing with

    nokogiri -v

  • Rick Eagle

    C:\>nokogiri -v
    'nokogiri' is not recognized as an internal or external command,
    operable program or batch file.


  • Rick Eagle

    If I check on Ruby I get this. 


    C:\>ruby -v
    ruby 2.4.2p198 (2017-09-14 revision 59899) [x64-mingw32]

  • Joseph May

    Hey Rick-

    Let's please make sure nokogiri is installed with

    gem install nokogiri

    After that, let's try to use the verbose flag to check the version:

    nokogiri --version

  • Rick Eagle

    Thanks Joseph.  Results of the install and version check

    C:\>gem install nokogiri
    Fetching: mini_portile2-2.3.0.gem (100%)
    Successfully installed mini_portile2-2.3.0
    Fetching: nokogiri-1.8.1-x64-mingw32.gem (100%)
    Nokogiri is built with the packaged libraries: libxml2-2.9.5, libxslt-1.1.30, zlib-1.2.11, libiconv-1.15.
    Successfully installed nokogiri-1.8.1-x64-mingw32
    Parsing documentation for mini_portile2-2.3.0
    Installing ri documentation for mini_portile2-2.3.0
    Parsing documentation for nokogiri-1.8.1-x64-mingw32
    Installing ri documentation for nokogiri-1.8.1-x64-mingw32
    Done installing documentation for mini_portile2, nokogiri after 9 seconds
    2 gems installed

    C:\>nokogiri --version
    # Nokogiri (1.8.1)
    warnings: []
    nokogiri: 1.8.1
    version: 2.4.2
    platform: x64-mingw32
    description: ruby 2.4.2p198 (2017-09-14 revision 59899) [x64-mingw32]
    engine: ruby
    binding: extension
    source: packaged
    libxml2_path: "/home/flavorjones/code/oss/nokogiri/ports/x86_64-w64-mingw32/libxml2/2.9.5"
    libxslt_path: "/home/flavorjones/code/oss/nokogiri/ports/x86_64-w64-mingw32/libxslt/1.1.30"
    libxml2_patches: []
    libxslt_patches: []
    compiled: 2.9.5
    loaded: 2.9.5

  • Joseph May

    Great, that's what we need. Can you try to

    gem install zendesk_apps_tools

    now? (Maybe restart your shell first, just for extra measure)

  • Rick Eagle

    Went through the process again.  Uninstalled Ruby, and MSYS2.  Rebooted, reran the Ruby installer for 2.4.2.   installed nokogiri, then the zendesk_apps_tools.  During the zendesk_apps_tools install, it failed with the message that indicates nokogiri at 1.81. is not compatible with Ruby 2.4.2.   Could that be the problem. 

    Fetching: nokogiri- (100%)
    ERROR: Error installing zendesk_apps_tools:
    nokogiri requires Ruby version < 2.4, >= 1.9.2.

  • Joseph May

    Hi Rick-

    You are correct. This is something I would actually suggest you report to nokogiri's developers on their GitHub repository -  this doesn't appear to be a new issue with versioning between OS's. If possible, please try installing an older version of Ruby (2.3.3 was the last minor (& patch) update for version 2).

  • Donatas Gostautas


    it is still impossible to install the ZAT on Ruby 2.4. due tothe Nokogiri dependancy and your tools using outdated version of it.

    Please update your GEM file to work with 1.8.2 version of Nokogiri or suggest a method to bypass this.

  • Joseph May

    Hi Donatas-

    I will bring this up in our meeting with the appropriate PM. As an alternative, I highly recommend looking into using the Windows Subsystem for Linux (WSL), which I have found circumvents many of the issues surrounding installing and managing Ruby versions. Here are three articles outlining the process:

    System prep for app developers 1: Setting up your command-line interface

    System prep for app developers 2: Managing Ruby versions

    System prep for app developers 3: Installing Node.js



  • Donatas Gostautas

    Hello, Joey,

    Thank you for your quick response as well as for sharing these links.

    I wasn't aware of being able to add Ubuntu like that within the Windows up until following the first guide and that is already a huge improvement for my workflow. I haven't gone through all of the steps yet, although considering that I'm using Ubuntu as a Sandbox + Virtual Environments with different version of Ruby, I'm sure I won't encounter any issues along the way.

    Hopefully, you'll update the ZAT dependencies as well.

  • Joseph May

    Thank you very much, Donatas, I am happy to hear that. I have a meeting with our PM later this week and I will bring up the dependency issue.

  • Donatas Gostautas

    Hello everyone,


    So I have managed to build the app and I would now like to package it and install it into my Zendesk. However, when validating/packaging I receive OpenSSL error:

    info Checking for new version of zendesk_apps_tools
    C:/Ruby23-x64/lib/ruby/2.3.0/net/http.rb:933:in `connect_nonblock': SSL_connect returned=1 errno=0 state=error: certificate verify failed (OpenSSL::SSL::SSLError)

    Anyone encountered such issue whilst validating their Zendesk applications?

  • Bryan Flynn

    Hi Donatas -- check out this article:

    It gives links explaining why the issue is happening as well as how to address it.

    Note that the Ubuntu-using-WSL option mentioned in earlier comments should not have this issue as it's typically a native Windows issue.

  • Vaibhav Agarwal

    Please use only Ruby 2.3 version because ZAT works only with that (I'm talking about Windows Platform here) and please before installation install Node Js. 

  • Dharmaprasad17

    I have followed the instructions in this article but may have done something wrong. In the process of installing zendesk_apps_tools I recieve the following message.

    $ sudo gem install rake
    $ sudo gem install zendesk_apps_tools
    Building native extensions. This could take a while...
    ERROR: Error installing zendesk_apps_tools:
    ERROR: Failed to build gem native extension.

    current directory: /var/lib/gems/2.5.0/gems/eventmachine-1.2.7/ext
    /usr/bin/ruby2.5 -r ./siteconf20180829-709-1bhhp7a.rb extconf.rb
    mkmf.rb can't find header files for ruby at /usr/lib/ruby/include/ruby.h

    extconf failed, exit code 1

    Gem files will remain installed in /var/lib/gems/2.5.0/gems/eventmachine-1.2.7 for inspection.
    Results logged to /var/lib/gems/2.5.0/extensions/x86_64-linux/2.5.0/eventmachine-1.2.7/gem_make.out


  • Bryan Flynn

    Dharmaprasad17, please try the approach detailed in System prep for app developers 1: Setting up your command-line interface for setting up your environment. It gives lots of details and makes for a more flexible development environment.

    For Windows users, it also gets around the Ruby2.3/Windows limitation and certificate issues mentioned earlier by using Windows Subsystem for Linux (WSL).


Please sign in to leave a comment.

Powered by Zendesk