Specifying app requirements

An app may depend on one or more Zendesk resources, such as ticket fields or targets, to work properly. When you create an app, you can declare these resources as requirements. When an admin installs the app, Zendesk creates the app's required resources in the admin's account. App requirements only work with Support and Sell apps.

Declaring app requirements

You declare requirements in a requirements.json file in the app's root directory.

To declare app requirements

1. In the app's root directory, create a file named requirements.json.

2. In your text editor, open requirements.json. In the file, create a root-level JSON object.

   Each property in the object represents a resource type. You can declare resources of that type using a custom property key and a related resource schema. For supported properties and resource schemas, see Supported resource types.

   For example, the following requirements.json file declares a target, a webhook, and two ticket fields as requirements. Each resource has a custom property key, such as an_email_target or number_of_issues.

   {
     "targets": {
       "an_email_target": {
         "title": "An example email target",
         "type": "email_target",
         "email": "[email protected]",
         "subject": "Hello, from this target!"
       }
     },
     "webhooks": {
       "an_example_webhook": {
         "authentication": {
           "add_position": "header",
           "data": {
             "password": "hello_123",
             "username": "john_smith"
           },
           "type": "basic_auth"
         },
         "endpoint": "https://example.com/status/200",
         "http_method": "GET",
         "name": "An example webhook",
         "request_format": "json",
         "status": "active",
         "subscriptions": ["conditional_ticket_events"],
         "signing_secret": {
           "algorithm": "SHA256",
           "secret": "abcdefghijklmnopqrstuvwxyz"
         }
       }
     },
     "ticket_fields": {
       "support_description": {
         "type": "text",
         "title": "Support description"
       },
       "number_of_issues": {
         "type": "integer",
         "title": "Number of issues"
       }
     }
   }

Supported resource types

requirements.json supports the following top-level properties and resource schemas.

Resource type property	Resource schema
automations	POST payload for the automations API endpoint
channel_integrations	See Channel installer app
custom_objects	See Custom object app requirements
macros	POST payload for the macros API endpoint
organization_fields	POST payload for the organization_fields API endpoint
targets	POST payload for the targets API endpoint
ticket_fields	POST payload for the ticket_fields API endpoint
triggers	POST payload for the triggers API endpoint
user_fields	POST payload for the user_fields API endpoint
view	POST payload for the views API endpoint
webhooks	POST payload for the webhooks API endpoint

Legacy custom object app requirements

You can use the custom_objects property to declare legacy custom object types and legacy custom object relationship types as requirements. The property supports two related child properties: custom_object_types and custom_object_relationship_types.

Legacy custom object type requirements

To declare legacy custom object types, use the custom_object_types property. The property accepts an array of JSON objects. These objects use the same structure as the legacy custom object type resource but omit the data key. You can require up to 50 legacy custom object types per app.

Example:

{
  "custom_objects": {
    "custom_object_types": [
      {
        "key": "app_event_logs",
        "schema": {
          "properties": {
            "location": {
              "type": "string",
              "description": "Location"
            },
            "event": {
              "type": "string",
              "description": "Event"
            }
          },
          "required": ["location", "event"]
        }
      }
    ]
  }
}

Legacy custom object relationship type requirements

To declare legacy custom object relationship types, use the custom_object_relationship_types property. The property accepts an array of JSON objects. These objects use the same structure as the legacy relationship type resource but omit the data key.

Example:

{
  "custom_objects": {
    "custom_object_relationship_types": [
      {
        "key": "ticket_has_many_app_event_logs",
        "source": "zen:ticket",
        "target": ["app_event_logs"]
      }
    ],
    "custom_object_types": [
      {
        "key": "app_event_logs",
        "schema": {
          "properties": {
            "location": {
              "type": "string",
              "description": "Location"
            },
            "event": {
              "type": "string",
              "description": "Event"
            }
          },
          "required": ["location", "event"]
        }
      }
    ]
  }
}

Avoiding conflicts

When assigning custom property keys to resources in requirements.json, ensure you use a unique namespace. If an app's requirements conflict with existing resources on an account, the app will fail to install.

For example, an app requires a ticket field with a title of "Description" in requirements.json. If an account already has a ticket field with a title of "Description", attempts to install the app on the account will fail.

Passing installation setting values in app requirements

You can use the {{setting.SETTING_NAME}} syntax to pass an installation setting value in requirements.json. In most cases, an admin specifies this setting value during app installation.

For example, the following manifest.json file creates an installation setting named email_to_notify. To install the app, an admin must specify a value for this setting.

{
  ...
  "parameters": [
    {
      "name": "email_to_notify",
      "type": "text",
      "required": true
    },
    ...
  ]
}

The following requirements.json file declares a required email target. The target uses the value of the email_to_notify setting in one of its properties.

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

Dependent app requirements

Some required resources, such as triggers or views, may depend on other resources in requirements.json. In these cases, use the resource's property key wherever the equivalent API payload would use the resource's id.

For example, the following requirements.json file declares an email target and a trigger. The trigger references the email target's property key.

{
  "targets": {
    "an_email_target": {
      "title": "A sample email Target",
      "type": "email_target",
      "email": "[email protected]",
      "subject": "Hello, from this target!"
    }
  },
  "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."]
        }
      ]
    }
  }
}

Creating a requirements-only app

A requirements-only app is an app that only creates required resources in an account. The app doesn't do anything else. You can only install a requirements-only app as a Support app.

To create a requirements-only app

1. Create the starter files for a new app. See Creating starter files for a Zendesk app.

2. In your text editor, open the app's manifest.json file and make the following changes:

   • Add the "requirementsOnly": true property.
   • Add the "singleInstall": true property. An account can only have one active installation of a requirements-only app at a time
   • Delete the location property
   • Delete the frameworkVersion property. Requirements-only apps don't specify a framework version.

   Example:

   {
     "name": "Example app",
     "author": {
       "name": "John Doe",
       "email": "[email protected]"
     },
     "defaultLocale": "en",
     "private": false,
     "version": "1.0",
     "requirementsOnly": true,
     "singleInstall": true
   }

3. In the app's root directory, create a requirements.json file. In the file, specify the resources to create. For details, see Declaring app requirements.

Updating or deleting requirements

You can change an app's requirements.json file to update or delete certain types of resources created by the app.

Resource type	Updatable	Deletable
automations	Yes	Yes
channel integrations	No	No
custom object types	Yes	Yes
custom object relationship types	No	Yes
macros	Yes	Yes
organization fields	No	No
targets	Yes	Yes
ticket fields	No	No
triggers	Yes	Yes
user fields	No	No
views	Yes	Yes
webhooks	Yes	Yes

To update requirements for a private app, upload the new version of the app to your account. This new version should contain your updated requirements.json file. To update a private app using ZCLI, see Updating a private Zendesk app.

To update requirements for a public app, first test your changes to ensure they won't negatively affect your app users. To do this, we recommend testing the app as a private app in a test account. If your changes work as expected, resubmit the public app for approval.

Once an app is updated, its requirement changes can't be reverted. It may take up to five minutes for an app to update.

The following requirements.json examples update required user field resources.

From

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

To

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

Accessing requirements from an app

You can use the Zendesk Apps framework (ZAF) client's get() method to access app requirements in a Support or Sell app. To access a requirement, call client.get('requirement:IDENTIFIER'). Replace IDENTIFIER with the property key for the resource in requirements.json.

Example:

const client = ZAFClient.init();
client.get("requirement:number_of_issues").then((data) => {
  console.log(data);
});

For more information, see the requirement object in the ZAF Core API documentation.

Uninstalling or disabling the app

If an admin disables an app, Zendesk disables any resources in the app's requirements.json file, excluding:

• Channel integrations
• Custom object types
• Custom object relationship types

If an admin uninstalls an app, Zendesk deletes any resources listed in the app's requirements.json file. If the resource is a custom field, Zendesk deletes the field itself and all data for the field. However, the data still remains available in ticket audits.

Limitations

• The ZCLI server can't create resources from requirements.json. Similarly, you can't access the requirement object using the ZCLI server.
• An app can't require more than 5,000 resources in requirements.json. An app can't require more than 50 custom object types.
• Chat apps don't support app requirements.