Building your first Sell app - Part 1: Laying the groundwork

In this five-part tutorial series, you'll learn how to build a Zendesk Sell app from start to finish. The app you'll build is called Related Leads. This tutorial covers the first steps for setting up the app:

  1. What you'll need
  2. Planning the app
  3. Installing the Zendesk app tools
  4. Creating the app files

The other tutorials in the series teach you how to build and install the app:

Because the tutorials build on each other, tackle them in order and finish each tutorial before moving on to the next one.

To download the completed source code of the app in this tutorial, click related_leads.zip. You can review the code as you follow along or check your work.

Note: Zendesk provides this article for instructional purposes only. Zendesk does not provide support for the content. Please post any issue in the comments section below or in the Zendesk Apps framework (ZAF) community, or search for a solution online.

What you'll need

To build and upload a private app in Sell, you must have Zendesk Sell on the Professional plan or above. The Sell account must also be linked to a Zendesk Support account.

Planning the app

You should have a good idea of how your app will look and work before you start working on it. The Related Leads app will appear in the sidebar when viewing a deal card in Sell.

The app will display the following information about the organization associated with the deal:

  • The organization's name
  • A list of new leads for the organization

The app will also include a "Report bugs" link that lets the user report a bug to the app's author.

Here's a mockup of the user interface:

Mock up of the user interface

Installing the Zendesk app tools

In this section, you'll install the Zendesk app tools (ZAT). Among other tasks, you can use ZAT to:

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

Installing ZAT is a one-time task. Once installed, you can use ZAT for all your Zendesk app projects.

To install ZAT, follow the instructions in Installing and using the Zendesk apps tools. After you're done, return here to continue the tutorial.

If you've already installed ZAT, make sure you are using the latest version. To update ZAT, run the following command in your command-line interface (Command Prompt in Windows or Terminal in Mac OS X):

$ gem update zendesk_apps_tools

Creating the app files

After installing ZAT, you're ready to start building. The first step is to create the starter files for a new app called Related Leads in a folder called related_leads.

To create the app files

  1. In your 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. For example:

    $ cd projects
  2. Run the following ZAT command:

    $ zat new
  3. At the prompts, enter the following values:

    • Author's name - Your name
    • Author's email - Your email address
    • Author's URL - Your website URL, if you have one. This URL must start with http:// or https://. Press Enter to leave the URL blank.
    • App name - Related Leads
    • iFrame URI - Press Enter to leave this blank. You'll use the default local iframe file.
    • Directory name - related_leads
  4. ZAT creates and lists the subfolder and its files.

  5. Open your file browser and navigate to the files. The folder contains an assets and translations folder as well as a manifest.json and README.md file. You can add as many files as you need when you're building your app, but these files are all you need to start. Because it's an iframe app, you can host the app in the Zendesk server infrastructure or on a remote server using any technology stack you prefer. If you're only using client-side technologies, such as Handlebars, as you will be here, you can simply host it in your Zendesk account.

In the next tutorial, you'll learn more about the how your app's user interface (UI) displays in Sell. You'll create some placeholder HTML, add a footer, and add some styles to meet the design requirements specified in Planning the app above. Get started: Part 2: Designing the user interface.