Specifying Apps Requirements

Note: App requirements currently only work with Zendesk Support.

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, organization 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"
    }
  }
}

This also works for user fields and organization fields:

{
  "triggers": {
    "sample_trigger": {
      "title": "A Sample Trigger",
      "all": [{
        "field": "custom_fields_user_location",
        "operator": "is",
        "value": "Melbourne"
      },{
        "field": "custom_fields_org_location",
        "operator": "is",
        "value": "Melbourne"
      }],
      "actions": [{
        "field": "set_tags",
        "value": "Most Liveable City"
      }]
    }
  },

  "user_fields": {
    "user_location": {
      "type": "text",
      "title": "City"
    }
  },

  "organization_fields": {
    "org_location": {
      "type": "text",
      "title": "City"
    }
  },
}

Updating or deleting requirements

You can update or delete certain kinds of resources created by an app by making changes to the requirements.json file. After making the changes, upload the new version of the app, or resubmit it for approval if your app is public.

Important: When updating a public app, test the changes privately first. The changes can't be reverted once the app is updated. This can have negative consequences for your app users. Also, it might take up to 5 minutes for the app to update.

The following table lists the resources you can update or delete:

Resource Updatable Deletable
ticket fields No No
user fields No No
organization fields No No
triggers Yes Yes
views Yes Yes
macros Yes Yes
automations Yes Yes
targets Yes Yes
channel_integrations No No

The following example shows updates to requirements.json:

From javascript { "user_fields": { "user_city": { "type": "text", "title": "City" } } }

To javascript { "user_fields": { "user_city": { "type": "text", "title": "City" }, "user_address": { "type": "text", "title": "Address" } } }

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.log(data);
});

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

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.

If an administrator disables your app, most resources will be disabled. The only exception are channel integrations, which currently cannot be disabled and remain active even when the app is disabled.

Limitations
  • 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, organization fields, triggers, views, macros, automations, targets, and channel integrations.
  • Requirements for a given installation can be modified, except for ticket fields, user fields, organization fields.
  • 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
  }
  1. Create a file named requirements.json in your app's root directory, which is where the manifest.json file is located.

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

Demo apps

Start using apps requirements by learning from the following demo apps: