Setting up new apps

Creating the app files

You can create app files with the Zendesk App Tools (ZAT), the App Scaffold, or manually.

Using ZAT

You can create a basic set of files for your app with the Zendesk App Tools (ZAT). If you haven't installed the tools yet, see Installing and using the Zendesk Apps Tools.

Run the following command to create the files:

$ zat new

The tool prompts you for information to populate the app's manifest.json file. See Manifest reference. The tool also asks you if you want to enter an iframe URI. If you leave the URI blank, ZAT will create a basic HTML page for you identical to this example on Github.

Using the App Scaffold

For more substantial apps, you can use the App Scaffold on Github as a starting point. It already includes Bootstrap, jQuery, Underscore, and Handlebars. The only caveat is that the libraries may be slightly out of date, but you can easily upgrade them to the latest versions.

Using the Zendesk Garden styles

Zendesk Garden is designed to be a common baseline of styles and components between all Zendesk products. If you want your app to match the Zendesk product look and feel, use the Zendesk Garden stylesheet by including a link tag in your HTML page pointing to the latest version of the Zendesk Garden CSS:

<link rel="stylesheet" href="https://assets.zendesk.com/apps/sdk-assets/css/1/zendesk_garden.css" type="text/css">

Further information about the CSS classes in Zendesk Garden is available from garden.zendesk.com or the demo app. Versioning format of the url follows that of the ZAF SDK.

Note: Currently, React Components are not available to apps.

File requirements

The following folder structure and files must be included in an app to install the app successfully in a Zendesk product:

assets/
  logo.png
  logo-small.png
translations/
  en.json
manifest.json

Everything else is optional. For example, you can host the rest of the app on a remote app server, including the HTML files to be iframed into the Zendesk product.

The following are brief descriptions of the required files:

  • manifest.json - Describes and configures the app. See Manifest reference.

  • translations/{locale}.json - A translation file. The value of {locale} is specified by the defaultLocale property in manifest.json. For example, if "defaultLocale" is "en", then make sure a file named en.json exists in the translations folder. See Internationalization.

  • assets/logo-small.png - Small icon displayed in the header of the app. You can still upload and install the app without it, but a default image will appear in the interface. See App icons for the image specifications.

  • assets/logo.png - Large icon displayed in the Zendesk admin pages for managing apps. You can still upload and install the app without it but a broken image icon will appear in the interface. See App icons and Top bar and nav bar icon for the image specifications.

  • assets/icon_*_bar.svg - Every nav_bar or top_bar app requires a icon_nav_bar.svg or icon_top_bar.svg file respectively. See App icons for the image specifications.

If you plan on making the app available in the Zendesk Apps Marketplace (as opposed to creating a private app to run only in your Zendesk account), additional branding assets may be required. See Branding.

Setting the app location

You must declare where you want the app to appear in the product interface with the location property in manifest.json.

For example, in Zendesk Support you can place the app in the panel on the right side of the ticket in the agent interface. The framework calls this location the ticket_sidebar (or the new_ticket_sidebar in the case of the new ticket page).

"location": {
  "support": {
    "ticket_sidebar": "assets/iframe.html"
  }
},

For available locations, see:

Some framework APIs are only available to apps in certain locations. For example, only apps appearing on the ticket page can get and set ticket properties, and listen for changes to the ticket.

If you want the app to appear in multiple locations in the product, add the locations to the product object:

  "location": {
    "support": {
      "ticket_sidebar": "assets/iframe.html",
      "new_ticket_sidebar": "assets/iframe.html?location=new_ticket_sidebar",
      "nav_bar": "https://dashboard.myapp.com/nav_bar",
      "top_bar": "https://dashboard.myapp.com/top_bar"
    }
  },

You must specify an object rather than a string to use certain advanced features that are enabled on a per-location basis. Set the location properties in the object.

Example:

  "location": {
    "support": {
      "background": {
        "url": "assets/iframe.html"
      },
      "ticket_sidebar": {
        "autoLoad": false
      }
    }
  },

For available location properties, see the manifest location reference.

The URL paths can be absolute if pointing to an external page, or relative if pointing to a html file in the assets folder.

Note: Use https for all remote, production-ready URL paths. You can use http during development.

Defining installation settings

You can define settings you want product admins to set for the app during or after installing the app. While settings are completely optional, they're simple to set up and use. The framework even auto-generates a settings page for you.

Settings are defined by the parameters property in the manifest file. The property consists of a list of JSON objects representing the settings you want the admin to set.

Example:

"parameters": [
  {
    "name": "subdomain",
    "type": "text",
    "required": true,
    "secure": false,
    "default": "yoursubdomain"
  },
  {
    "name": "token",
    "type": "text",
    "required": true,
    "secure": true
  },
  {
    "name": "useSSL",
    "type": "checkbox"
  }
]

You can retrieve the setting values in your app with client.metadata():

var client = ZAFClient.init();
client.metadata().then(function(metadata) {
  console.log(metadata.settings);
});

You can also use settings to customize the manifest.json file on a per installation basis. To specify a setting value in the manifest, use double curly brackets. Example:

...
"domainWhitelist": ["www.teachmyapi.com", "{{setting.subdomain}}.herokuapp.com"],

For more information about domainWhitelist, see Using secure settings.

Setting properties

Each object in the parameters list represents a setting and can have the following properties:

name

The name of the setting.

"name": "subdomain",

Because you use this value in your app code, make sure you name it appropriately.

required

A boolean value that determines if the user must define the setting or not to install the app. Optional.

"required": true,
default

Specifies a default value to enter for the setting if the user doesn't specify one. Optional.

"default": "yoursubdomain",

The default value is used to populate the parameter form field when the admin installs or updates the app. However, it will not take effect for existing parameters where a value has already been set. Don't use the default value as a fallback value. If your app needs a fallback value, implement it in the app.

secure

Use the optional "secure" property when you don't want users to see sensitive information in the parameters when making HTTP requests. Since a lot of apps make HTTP requests to get or set information, any agent can view this data in their browser if the setting is not secure.

"secure": true,

For details, see Using secure settings.

type

Specifies the control to use on the auto-generated settings page for the user.

"type": "text",

The framework generates an HTML settings page for users installing the app. The following controls are available:

Type Control
text A single-line input field
password A masked single-line input field
checkbox A single checkbox
url A single-line input field, validated for correct URL syntax
number A single-line input field, validated to include only numbers
multiline A multi-line textarea. User input is limited to 64Kb
hidden A parameter never shown to the user on the settings page
Creating a settings page for users

Users need some kind of user interface to enter the settings when installing the app or to edit the settings after installing the app. The framework generates an HTML settings page based on the settings defined in the manifest file. Setting type controls on the page are rendered in the same order as the settings in the manifest file. Example:

settings

Asterisks indicate required fields.

The maximum length of any setting is 64kB. Exceeding this limit will result in an error.

You can define the setting labels displayed on the generated settings page. The labels and help text in the example above are extracted from the translation file. To translate parameters and add help text, add a parameters property to the app object in your translations files as follows:

{
  "app": {
    "parameters": {
      "subdomain" : { "label": "Subdomain" },
      "token"     : { "label": "Token" },
      "useSSL"    : { "label": "Use SSL?", "helpText": "Use SSL for a secure connection." }
    }
  }
}
Updating settings

Sometimes you want to change and save a setting from within the app. You can do it with the following REST API endpoint:

PUT /api/v2/apps/installations/{id}.json

For more information, see Update an App Installation in the REST API docs.

Note that only admins can update settings, not agents.

Defining test settings

When testing your app locally, you might need to specify some installation settings. Because you haven't installed the app yet, the settings don't exist yet. If you start the local server with zat server, ZAT will ask interactively for the values of all the settings specified in the manifest.json file. However, you might prefer to specify the settings in a JSON or YAML file.

  1. Create a JSON or YAML file with your settings. The keys in the file should be the same as in your manifest file.
  2. Start the server with zat server -c [$CONFIG_FILE], where $CONFIG_FILE is the name of your JSON or YAML file. The default filename is settings.yml. You don't need to specify it in the command if your file uses that name.

If manifest.json contains the following settings:

"parameters": [
  {
    "name": "mySetting"
  },
  ...
],

Then you can specify the settings in a file as follows:

./settings.json

{
  "mySetting": "test value"
}

or

./settings.yml

mySetting: test value

With the first file, you'd start the server with zat server -c settings.json. With the second file, you'd start it with zat server -c.

Specifying app requirements

If your app depends on another Zendesk Support resource such as a ticket field or a target to work properly, you can declare the dependency in a file named requirements.json in your app's root directory. When an administrator installs your app, the resource will be created automatically in the account.

You can also create a requirements-only app that does nothing but install one or more resources in Zendesk Support instances.

You can specify any of the following resources as requirements: ticket fields, user fields, triggers, views, macros, automations, targets, and channel integrations.

Declaring requirements
  1. Include a file called requirements.json in your app's root directory. This is where the manifest.json file is stored.

  2. Declare the requirements in the file as a JSON object. For each resource type you require, specify an object with resource identifiers of your choice as keys, and values containing the settings for that resource type:

The following example declares two targets and two ticket fields as requirements. These are created when the app is installed. Each requirement has an identifier, such as “a_basecamp_target” and “number_of_issues”.

{
  "targets": {
    "a_basecamp_target": {
      "title": "A sample Target",
      "type": "basecamp_target",
      "active": true,
      "target_url": "http://mytarget.com",
      "token": "123456",
      "project_id": "99999",
      "resource": "todo"
    },

    "an_email_target": {
      "title": "A sample email Target",
      "type": "email_target",
      "email": "foo@bar.com",
      "subject": "Hello, from this target!"
    }
  },

  "ticket_fields": {
    "support_description": {
      "type": "text",
      "title": "Support description"
    },

    "number_of_issues": {
      "type": "integer",
      "title": "Number of issues"
    }
  }
}

Each resource is specified as a valid request to the Zendesk REST API. See Create Target and Create Ticket Fields in the API docs.

Using settings

Requirements can depend on the values of settings entered by admins when they install the app. For example, if you wanted the email address for an email target to be specified by whoever installs the app (as a setting called “email_to_notify”), your requirements.json would look like this:

{
  "targets": {
    "an_email_target": {
      "title": "Send notification email",
      "type": "email_target",
      "email": "{{setting.email_to_notify}}",
      "subject": "Hey, something's happened!"
    }
  }
}
Dependent requirements

If you include triggers, automations, or views in your requirements.json file and they depend on other resources that you're also requiring, you should reference them by name where the REST API references them by id. For example, if you require a trigger that depends on a custom target called "an_email_target", your requirements.json file might look like this:

{
  "triggers": {
    "email_on_ticket_solved": {
      "title": "Email on ticket solved Trigger",
      "all": [{
        "field": "status",
        "operator": "is",
        "value": "solved"
      }],
      "actions": [{
        "field": "notification_target",
        "value": ["an_email_target", "Ticket {{ticket.id}} has been updated."]
      }]
    }
  },

  "targets": {
    "an_email_target": {
      "title": "A sample email Target",
      "type": "email_target",
      "email": "foo@bar.com",
      "subject": "Hello, from this target!"
    }
  }
}

Alternatively, if you want a trigger's actions or conditions to reference the value of a custom field, use this syntax:

{
  "triggers": {
    "sample_trigger": {
      "title": "A Sample Trigger",
      "all": [{
        "field": "status",
        "operator": "is",
        "value": "solved"
      }],
      "actions": [{
        "field": "custom_fields_support_description",
        "value": "open"
      }]
    }
  },

  "ticket_fields": {
    "support_description": {
      "type": "text",
      "title": "Support description"
    }
  }
}
Accessing requirements from your app

You can access the requirements in your app with client.get('requirement:identifier'), where identifier is the identifier for the requirement. Example:

var client = ZAFClient.init();
client.get('requirement:number_of_issues').then(function(data) {
  console.dir(data);
});

The call returns an object containing a requirement_id and a requirement_type. For more information, see Core API - requirement.

Naming

Resources created by your app may have name conflicts with existing resources. For example, if there's already a ticket field with the title “Description” and your app tries to create another one, the installation of the app will fail. So make sure you namespace any unique fields in your resources.

Uninstalling or disabling the app

If an administrator uninstalls your app, the resources will also be deleted. Note: If the resource is a custom field, all data associated with the field will also be deleted, as it would for any other custom field. Data remains available in ticket audits.

Also, if they disable your app, most resources will be disabled. The only exception are channel integrations, which currently cannot be disabled and will remain active even when the app is disabled.

Resources installed by an app requirement cannot be modified or deleted manually.

Limits
  • Requirements aren't installed when running the app locally on the ZAT server. However, for testing purposes, 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.
  • Currently an app can only require up to 5,000 resources.
  • Available resources are ticket fields, user fields, triggers, views, macros, automations, and targets.
  • Requirements for a given installation cannot be modified:
    • by using the admin UI
    • by uploading a modified requirements.json.
  • Additional requirements added to the requirements.json will not be added to any existing installations
  • Uninstalling an app removes all of its requirements, including ticket fields.

Creating a requirements-only app

You can create an app whose only job is to create resources in a Zendesk Support instance. Resources include ticket fields, user fields, triggers, views, macros, automations, targets, and channel integrations. The resource is created when the app is installed. This kind of app is known as a requirements-only app. It doesn't display anything or do anything else.

To create a requirements-only app

  1. Create the starter files for a new app using the Zendesk apps tools (ZAT). For instructions, see Installing and using the Zendesk apps tools.

  2. Open the app's newly created manifest.json file and make the following changes:

    • Add "requirementsOnly": true to the manifest properties. The property isn't included by default.
    • Add "singleInstall": true to the manifest properties. Each Zendesk Support account can only have one active installation of a requirements-only app at a time
    • Delete the "locations" property
    • Delete the "frameworkVersion" property. Requirements-only apps don't specify a framework version

    Example:

    {
      "name": "Omniwear Instagram Channel",
      "author": {
        "name": "Omniwear",
        "email": "support@omniwear.com",
        "url": ""
      },
      "defaultLocale": "en",
      "private": false,
      "version": "1.0",
      "singleInstall": true,
      "requirementsOnly": true
    }
    
  3. Create a file named requirements.json in your app's root directory, which is where the manifest.json file is located.

  4. Specify the resources to create in the requirements.json file. For details, see Specifying app requirements.