Add an Automations Trigger Extension

A trigger is an event that causes an automation to run.

To make an event a trigger, you need to do two things:

• Add a trigger extension in the app dashboard. As part of this extension, you configure a payload schema and other settings for your trigger.

• In your app code, report the event to Wix Automations.

This article walks you through how to add and configure the trigger extension. Once you complete this process and publish your app, any user who installs your app will see this trigger in the Automations Builder on their site.

Before you begin

• Familiarize yourself with triggers.
• Make sure 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 create a new trigger and configure its name and key.

The trigger key identifies your trigger when you report and cancel events. It won't be visible to users but it is visible to you, so choose a key that's meaningful to you. After you publish your app, the trigger key can't be changed.

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

   

2. In the new page that opens, set your Trigger name.

   

   Users see the trigger name when they select a trigger for use on their site, so it’s important to give it a good name. This helps users understand what kind of events activate your trigger. 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 "Restaurant reservation made" is a less ambiguous name.

   Some examples of good trigger names are:

   • Customer registered for session

   • Interest form submitted

   • Gym member approved for discount

3. Create a Trigger key using the suggested <app_name>-<trigger_name> format.
   The trigger key must:

   • Start with a letter or number.

   • Contain only lowercase letters, numbers, hyphens, and underscores.

   • Not be the same as another trigger key in your app.

   

Step 2 | Configure the payload schema

Now that you've created your trigger, you need to create a payload schema for it. This step walks you through the process of generating your payload schema. For more in-depth information on the schema specifications, see The Payload Schema.

You’re required to create the schema because it tells Wix exactly what data it receives when your app reports the event. This impacts the actions available to users (for example, whether they can use contact-based actions or not). Wix also presents trigger settings to the user based on the payload properties, such as whether the user can schedule the trigger.

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 Generate from Sample Data.

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. This validates the schema changes and makes the schema fields available to the remaining trigger configuration.

4. To further configure your schema, click Manage Schema Properties and then click the Developer tab. The Manage schema properties modal provides you with a UI to configure certain settings for each property in your schema. This includes:

   • Display name: The display name is directly connected to the title key found in each property, and sets the field label that the user sees on in their dashboard. You have the choice to edit it here or in the schema.

   • Required: You can mark a field as required by checking the box. If you mark a field as required here, it will automatically be added to the required array.

   • Example: You can add or edit entries in the examples array of a property. The schema is updated automatically with your changes.

   • Description: You can write a description of the schema property here and the description key will be added to your schema, with the description you write as its string value. If you already have a description key, you can edit its value here.

     

5. When you're finished, click Update Schema. The modal closes and your schema is updated.

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 | Additional configuration

In this step, you'll add some additional configuration to your trigger. All the configuration options shown here are optional, and your trigger will work without them. However, it may have limited functionality that reduces its usefulness to users. You can read more about the different configuration options in About Triggers.

Add contact data to the payload

You can select one payload property to connect to a contact ID. This tells Wix to retrieve the contact ID and its associated data and attach it to the payload. If you don’t connect a contact ID, users won’t be able to use your trigger with contact-based actions like Send an email.

The payload property you connect must be of type "string" and have a “uuid” format.

To connect a property to a contact ID:

1. Under Contact enrichment & scheduled events, select Connect ContactID to enrich the trigger with contact details. A dropdown menu appears with a list of payload properties that meet the data type requirements and are available to connect.

   

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

Allow scheduled events with predefined date & time

By default, users can set an automation to run either immediately when an event is reported or after a delay. If you allow scheduled triggers, however, users also have the option to run the automation before the event. This is useful if your trigger will be used to send reminders for appointments or other scheduled events.

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

To specify a scheduled event field:

1. Under Contact enrichment & scheduled events, click Allow scheduled events with predefined date & time. A list containing the available fields is displayed.

   

2. Select the relevant field from the list. This adds the "futureDate": true key-value pair to the selected field in the schema.

Add filter fields to the trigger

Every time an event occurs in your service, your app reports it to Wix. However, a user who has applied your trigger might not want to run their automations on every single event occurrence. Adding filter fields to your payload properties allows users to filter reported events based on whether certain conditions are met.

When you create a filter field on a payload property, the user can set criteria for that property when they set up the trigger in their site dashboard. For example, a user might only want to run a Product purchased automation when a customer makes a purchase of more than $50. You can allow this by adding a filter field on a number property such as price.

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. In the app dashboard, navigate to Translations.

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. In the site dashboard, create an automation. Configure the automation as follows:

   • 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.