In this article, we explain in more detail how to create and configure automations using the Create Automation method. We'll go through the different configuration options for the full automation as well as its trigger and actions.
When configuring the trigger for your automation, specify the trigger key and the ID of the app that created the trigger. For example, if you use the "Subscribed to site" trigger, specify the following app ID and trigger key:
You can also include any of the optional configuration described below.
Use the filters array to apply filter fields to your trigger. Filter fields allow you to filter which triggers activate an automation. For example, you may want your automation to trigger only if a certain form is submitted.
Filter expressions have an AND relation. This means that all filter expressions must evaluate to true for a given payload in order for the automation to run. An example of an added filter might look like this:
Important: Before specifying any filters, you must first define them in the app dashboard as filter fields for the trigger. You can't create new filter fields with the API call.
Scheduled events let you schedule the trigger to activate before the event occurs. For example, this allows you to send a reminder email three days prior to a training session.
Important: Before scheduling a trigger, you must first configure it as a scheduled event in the app dashboard.
Add the time offset value in preScheduledEventOffsetExpression. This is the amount of time by which to offset the time of the automation execution from the event. Note that this field expects a string, which can be hard-coded or a stored in variable specified in the payload.
For example, if you want the automation to run 5 days before the date of the event, you can configure your trigger in the following way:
You can also use a variable, such as timeOffset, to specify the value of the offset expression:
Note: You can only use negative offsets from the event date (before the event). To schedule triggers to run after the event, use delay actions.
Rate limits restrict the number of times a trigger activates. For example, you might want to send a site visitor a chat message only once, the first time they navigate to a page on your site, rather than every time they navigate to a new page.
To set a rate limit, you must define 4 parameters:
maxActivationsExpression: The maximum number of times the trigger should activate.durationExpression: How long the rate limit should be active before expiring.durationTimeUnit: The time unit in which to specify the rate limit duration.uniqueIdentifierExpression: Identifier used by the rate limiter to count activations.The maxActivationsExpression and durationExpression parameters are both strings that can accept either a hard-coded value or a variable specified in the payload. For example, you can set maxActivationsExpression to 1 or to the value of a variable such as maxActivations.
The uniqueIdentifierExpression can be any string created by any operator or payload field. The string can be a contactID but is not limited to that.
The following example limits the number of activations over a 10-hour period to the value stored in the maxActivations variable. The rate limiter uses the contact ID (for example, of the site visitor who triggers the automation) to count the activations:
Actions are the steps that execute after a trigger activates.
When setting up an automation, you must define a map of all possible actions in the automation flow. Every action must be defined in key
pairs:Here's an example of an action map (some configuration details are removed for conciseness):
You must add at least 1 action ID to the rootActionIds array. The trigger activates these actions in parallel. Each root action can be followed by additional subsequent actions, if any are defined.
Note: You can currently only specify 1 root action.
The action namespace is a human-readable name that distinguishes it from other actions of the same type. If an action outputs data, it is included under its namespace in the payload sent to subsequent actions in the automation flow.
You can provide the action namespace, or let Wix automatically generate one for you in the "<ACTION_KEY>-<INDEX_OF_ACTION>" format.
Here's an example of a trigger payload:
The trigger is followed by an action with the namespace "action_1", that outputs the following data:
The payload sent to the step that follows the action looks like this:
The output of any subsequent actions in the automation flow is concatenated to the payload. For example, given the following automation configuration:
The payload available to Action C looks like this:
All the fields in the JSON above are available to Action C to map to its own input fields. Action C can select which action output to use by choosing action_b1.message or action_b2.message.
You can provide the namespace, or let Wix automatically generate one for you in an "<ACTION_KEY>-<INDEX_OF_ACTION>".
Actions are steps in the automation flow. Each action has a specific type that determines its behavior. When configuring an action, you must specify both its type and its corresponding information object, as shown in the table below:
| Action type | Description | Information object |
|---|---|---|
APP_DEFINED | An action created by an app. Available in the Automations Builder to users. | appDefinedInfo |
CONDITION | A condition that determines which action runs next. | conditionInfo |
DELAY | A period of time that forces the automation to wait before executing the next step. | delayInfo |
RATE_LIMIT | A rate-limiter stops the automation flow if the subsequent action reaches its maximum allowed executions. | rateLimitInfo |
When the action type is APP_DEFINED, include the appDefinedInfo object. You need the ID of the app that created the action, and the action's key. Both are defined in the app dashboard.
You also need to define the action's input mapping, which is the implementation of its input schema defined in the app dashboard.
Here's an example of an input mapping object:
You can configure your automation to skip the app-defined action if certain conditions are met. You can list up to 10 such conditions in the skipConditionOrExpressionGroups array. Conditions can be hard-coded or stored in variables specified in the payload, such as true or boolFieldFromPayload. A condition can also be expressed as a function.
The last parameter in appDefinedInfo is postActionIds. This is similar to the rootActionIds array, but instead of specifying actions that run in parallel after the trigger occurs, it specifying actions that run after the app-defined action.
Here's a complete example of an appDefinedInfo object:
When the action type is CONDITION, include the conditionInfo object.
Specify your conditions in the orExpressionGroups array. Conditions can be hard-coded, variables from a payload, or expressions. Examples: true, boolFieldFromPayload, or a function expression.
The action evaluates to true if at least one condition in the orExpressionGroups array evaluates to true.
Use the truePostActionIds array to specify the IDs of actions that run when the condition evaluates to true. Similarly, use the falsePostActionIds array to specify the IDs of actions that run when the condition evaluates to false.
Here's an example of a conditionInfo object:
When the action type is DELAY, use offsetExpression and offsetTimeUnit to specify the amount of time the automation waits before the following step. The wait time starts when the current action completes.
To define the wait time from a specific date, specify a value for dueDateEpochExpression in milliseconds passed since the Unix Epoch (1 January, 1970 UTC), such as 18238348023423, someEpochFromPayloadField, or contact.birthdate.
Example:
This delays the execution of the next step for 5 days from the time the action completes.
Example with a specified date:
This delays the execution of the next step for 5 days from the contact's birth date as specified in the payload.
The final parameter of delayInfo is the postActionIds array. Use it to specify the IDs of any actions you want to run in parallel after the delay ends.
When the action type is RATE_LIMIT, define the rateLimitInfo object.
Use maxActivationsExpression to define the maximum number of times the step in the automation flow can run. Its value can be hard-coded or stored in a variable. Examples: 1, maximumValue.
Use rateLimitDurationExpression to define how long the rate limit remains active before it expires. Its value can be hard-coded or stored in a variable. Examples: 10, durationValue. rateLimitDurationTimeUnit defines the time unit.
uniqueIdentifierExpression provides an ID that the rate limiter can use to count the number of times the action has run. An example of a unique identifier is contact.id specified in the payload.
To run actions after the rate-limit action, specify their IDs in the postActionIds array.
Here's an example of the a rate-limiter action:
In this example, the number of times a step in the flow can run is limited to 5, counted based on a particular contact ID. This limit lasts 10 weeks and runs 3 actions after it completes.
You can control the general settings of the automation when it's added to a site. These settings are found in automation.settings and include hiding the automation, making it read-only, and disabling users' ability to delete and deactivate the automation.
In addition, the automation.settings.actionSettings object contains settings that apply specifically to actions. These settings let you make specific actions permanent and read-only, or prevent users from adding delays and conditions to the automation
Here's a full example of the settings object:
By default, all boolean settings in automation.settings are false and all arrays are empty. This means that, unless you define otherwise, any automation you create, as well as its actions, are viewable, editable, and deletable.