Add an Automations Trigger Extension

To add a trigger extension to your app, follow the procedure below.

Before you begin

Before getting started, make sure that you implement your app using OAuth with app instance authentication. This is required because only your app can report and cancel your trigger's events.

Step 1 | Set up the trigger

In this step, you'll configure the trigger name and key.

1. In your app's Automations page, click Create New > Trigger. The New Trigger page opens.

   

2. Set your Trigger name. The trigger name will be displayed to users, so create a name that indicates what the trigger does.

   To keep your trigger name user-friendly and consistent with other triggers, we recommend following these best practices:

   • Use passive voice.
   • Keep the name singular.
   • Use sentence case, and don't end with a period.
   • Make sure it can't be confused with another app or trigger. For example, "Reservation made" can mean several different types of reservations, so "Guest reserves a table" is a less ambiguous name.

   Some examples of good trigger names are:

   • Invoice sent
   • Form submitted
   • Member approved

3. Create a Trigger key. This identifies your trigger when you report and cancel events. It won't be visible to users.

   Using the suggested <app_name>-<trigger_name> format, choose a trigger key that's meaningful to you. After you publish your app, the trigger key can't be changed.

   The trigger key must conform to these requirements:

   • Starts with a letter or number.
   • Contains only lowercase letters, numbers, hyphens, and underscores.
   • Isn't the same as another trigger key in your app.

   

Step 2 | Configure the payload schema

You specify the expected payload for your trigger using JSON schema. When users create their automations, the trigger payload is used to present the available trigger options (such as whether the user can schedule the automation) and action options (such as allowing the user to set a trigger payload property as a variable in an action).

In this step, you'll create the payload schema. Before you continue, you'll need a sample of the expected payload as a JSON object. The JSON object will be used to create the initial version of your payload schema, which you can build out from there.

At the end of this step, you'll have a fully configured payload schema.

1. To create the initial draft of a schema from your sample payload data, click Create Schema from Payload.

   

2. In the Convert a payload to a schema modal, paste your sample JSON object, and click Convert to Schema. The modal closes and your schema is generated in the main textbox.

   

3. Click Process Schema to ensure the schema fields can be used by the rest of the configuration.

4. To further configure your schema, click Manage Schema Properties.

5. In the Manage schema properties modal, configure each field's Display name and Required? setting.

   

6. When you're finished, click Update Schema. The modal closes and your schema is updated in the main textbox.

Your schema now contains all the fields in your sample JSON, the display names are set, and the relevant fields are marked as required. In the next steps, you'll continue to refine and finalize the schema.

Step 3 | Review and fix the schema

In the previous step, you generated a JSON schema from a sample payload. However, the payload schema may not be a true representation of the schema you intended. For example, data types and string formats are inferred from data you provided in the sample payload, but some of those details could be incorrect.

In this step, review the generated payload schema and revise as needed. For a complete payload schema spec, see Payload Schema. Continue when you're happy with your schema.

Step 4 | Connect schema properties

In this step, you'll specify if there are schema properties that can be connected to Wix functionality.

Connecting schema properties is optional, but recommended if it's relevant to your payload.

The available options are:

• Whether a GUID-formatted field is a contact ID.
• Whether a date-time-formatted field contains a scheduled date and time.

Both options are limited to one field each.

Connect a property to a contact ID

This option is available only for fields where the type is "string" and the format is "uuid". This option is required for your users to be able to configure an action to send an email to a contact.

For more about what it means to connect a property to a contact ID, see Contact ID property.

To connect a property to a contact ID:

1. Click Connect a property to a ContactID. A list containing the available fields is displayed.

   

2. Select the relevant field from the list. The "identityType": "contact" key-value pair is added to the connected field in the schema.

Allow scheduled events with predefined date & time

This option is available only for fields where the type is "string" and the format is "date-time".

For more about what it means to allow scheduled events, see Scheduled event property.

To specify a scheduled event field:

1. Click Allow scheduled events with predefined date & time. A list containing the available fields is displayed.

   

2. Select the relevant field from the list. The "futureDate": true key-value pair is added to the scheduled event field in the schema.

Step 5 | Add filter fields to the trigger

This step is optional. You can configure your trigger to display filter fields. This allows users to set their automations to run only if certain conditions are met.

To get started, click Create Filter Field, select the filter field type you want to add, and fill in the required information. The information needed for each type of filter field is different, so see Filter Fields for the full list of options.

When you're finished configuring your filter field, click Apply to save your settings.

Step 6 | Provide translations for trigger text

This step is optional. You can provide translations for some written elements of your trigger into different languages to make it more accessible to audiences in other languages.

1. Go to Translations in your app's dashboard.
2. Click Add Language to open the Add languages modal.
3. Select the languages you want to provide, and click Add.
4. Find the triggers whose strings you want to translate, and click Translate. The translation editing page is displayed.
5. Enter the translation for each string, and then click Save.
6. Activate each trigger whose translations you want visible for users.

Step 7 | Test the trigger

In this step you'll install your trigger on a test site, create a test automation, and report a test event. Note that, because only the app that created the trigger can report its events, you must run the test call from your servers using an OAuth token.

To test your trigger:

1. If you haven't saved your trigger already, click Save & Close to save it now.

2. Install your app on a test site.

3. Create an automation. Make sure the automation uses these settings:

   • Trigger: Use your new trigger and configure accordingly.

   • Action: Use Send an email, and use these settings:

     • When editing the email template, click Add Dynamic Value in the left pane to include placeholders for your payload properties.

     • In Set recipients, select Include additional recipients, select Add Recipients > Collaborator roles, and then select Owner. Click Save to return to the automation configuration screen.

       

4. To save your automation, complete all the required information and click Activate.

5. Create or refresh an OAuth access token for the test site, depending on the OAuth method you used.

6. Send a test payload to Report Event.

If you completed this task successfully, you'll receive an email populated with the payload values.