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 arequirements.jsonfile in the app's root directory.

To declare app requirements

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

2. In your text editor, openrequirements.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, seeSupported resource types.

   For example, the followingrequirements.jsonfile declares a target, a webhook, and two ticket fields as requirements. Each resource has a custom property key, such asan_email_targetornumber_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.jsonsupports the following top-level properties and resource schemas.

Legacy custom object app requirements

You can use thecustom_objectsproperty to declarelegacy custom object typesandlegacy custom object relationship typesas requirements. The property supports two related child properties:custom_object_typesandcustom_object_relationship_types.

Legacy custom object type requirements

To declare legacy custom object types, use thecustom_object_typesproperty. The property accepts an array of JSON objects. These objects use the same structure as thelegacy custom object typeresource but omit thedatakey. 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

申报遗产定制对象关系类型, use thecustom_object_relationship_typesproperty. The property accepts an array of JSON objects. These objects use the same structure as thelegacy relationship typeresource but omit thedatakey.

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 inrequirements.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" inrequirements.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 aninstallation settingvalue inrequirements.json. In most cases, an admin specifies this setting value during app installation.

For example, the followingmanifest.jsonfile creates an installation setting namedemail_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 followingrequirements.jsonfile declares a required email target. The target uses the value of theemail_to_notifysetting 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 inrequirements.json. In these cases, use the resource's property key wherever the equivalent API payload would use the resource's id.

For example, the followingrequirements.jsonfile 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":“票解决触发邮件”,"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. SeeCreating starter files for a Zendesk app.

2. In your text editor, open the app'smanifest.jsonfile and make the following changes:

   • Add the"requirementsOnly": trueproperty.
   • Add the"singleInstall": trueproperty. An account can only have one active installation of a requirements-only app at a time
   • Delete thelocationproperty
   • Delete theframeworkVersionproperty. 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 arequirements.jsonfile. In the file, specify the resources to create. For details, seeDeclaring app requirements.

Updating or deleting requirements

You can change an app'srequirements.jsonfile to update or delete certain types of resources created by the app.

To update requirements for a private app, upload the new version of the app to your account. This new version should contain your updatedrequirements.jsonfile. To update a private app using ZCLI, seeUpdating 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 followingrequirements.jsonexamples 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

您可以使用(ZAF) clien亚博 Zendesk应用框架t'sget()method to access app requirements in a Support or Sell app. To access a requirement, callclient.get('requirement:IDENTIFIER'). ReplaceIDENTIFIERwith the property key for the resource inrequirements.json.

Example:

             

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

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

Uninstalling or disabling the app

If an admin disables an app, Zendesk disables any resources in the app'srequirements.jsonfile, excluding:

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

If an admin uninstalls an app, Zendesk deletes any resources listed in the app'srequirements.jsonfile. If the resource is a custom field, Zendesk deletes all data for the field. However, the data still remains available in ticket audits.

Limitations

• TheZCLI servercan't create resources fromrequirements.json. Similarly, you can't access therequirementobject using the ZCLI server.
• An app can't require more than 5,000 resources inrequirements.json. An app can't require more than 50 custom object types.
• Chat apps don't support app requirements.