About Actions

An action is an automation’s response when it is triggered. Wix provides site owners with a number of premade actions, such as sending or receiving an email, sending a push notification, or updating data in a Google sheet. Users can also add extra actions to their site when they install Wix apps.

As an app developer, you can create your own actions and provide them to users as part of your app. Wix offers a service plugin (formerly SPI) so you can manage your app’s actions once they’re activated on users’ sites.

How do actions work?

When an event is reported to Wix, it triggers an automation. The automation then forwards the data it receives from that trigger to the action. The action uses the data to carry out the requested logic.

For example, let’s say a site owner creates an automation that sends a welcome email to a new member. In this case, the trigger is the new member signup. As part of the trigger payload, the new member’s email gets forwarded to the action. The action uses the email address it receives to send the welcome email.

There are two schemas you can use to define your action:

• The action input schema defines the data an action expects to receive. The input schema also creates a default action configuration UI.
• The UI schema lets you customize the action configuration UI further and mark fields as dynamic.

Overview of the input schema

The input schema defines the data required by the action. When you create the schema in your app's dashboard, a matching action configuration UI is also created. The action configuration UI is what a user sees when they configure your action in the site dashboard.

As an example, consider the simple schema below:

The action configuration UI for this schema looks like this:

The configuration UI provides various fields that make it easy for users to set input data. As the developer, you can also make fields required and add field descriptions (tooltips) to enhance the user experience.

There are two types of values that your action can accept as input:

• Static: The values in these fields stay the same every time the automation is triggered, unless the user edits the automation.
• Dynamic: The values in these fields are taken from the trigger payload, and therefore change each time the automation is triggered.

Static values

When a user installs and configures your action on their site, they want certain fields to remain the same no matter what data the payload contains. For example, if a site owner uses your action to send SMS notifications about sales on their online store, they may want to include a general link to the store in the message. That link shouldn’t change.

You can define a static string field in your schema to hold the link. When a user installs your app, they will need to enter a value in that field. Then, each time the automation fires and sends an SMS, the same link will be sent in every message.

It is also possible to pass a link (and other static values) through the trigger payload. However, because you don’t know which triggers your action will be used with, it is better to give users the option to fill out the link themselves in the action configuration.

Dynamic values

For some values, it is expected and necessary that they change depending on the payload data sent by the trigger. In that case, you can set up dynamic fields in your action input schema to accept values from the payload.

A simple example is contact information. Because a different site visitor triggers an automation each time, contact information changes every time the automation runs. This information is collected when the event is reported and included in the trigger payload. Therefore, a site owner can take contact information, such as a phone number, from the payload as a dynamic value.

Understanding input mapping

Users control what values they set when they configure your action on their site. For example, if you create a dynamic string field in the action UI, users can map any string value in the trigger payload to that field. One user may choose to fill the field with the contact name from the trigger payload. A different user may fill the field with a product summary.

The way input values are mapped to each field in the action UI is called input mapping. Input mapping is specific to each site. The input mapping that a user creates on their site doesn’t impact the input schema at all.

To understand the relationship between the input schema and input mapping, you can think of the input schema as a blank template that defines the field types needed by the action. The input mapping is the practical implementation, which fills in those blank fields with any values, as long as the values have the correct type (for example, a string must go in a string field, a number in a number field).

The example below illustrates the concept of input mapping. Let’s say you create an action for sites that connect businesses to possible customers. The action notifies a business listed on a site when a site visitor has requested their services. The input schema looks like this:

The businessContact and customerContact fields are dynamic, and their values are taken from the payload of whatever trigger the site owner selects. The requestingSite and daysToAccept fields are both static fields that the site owner sets manually.

Two different sites are using your action. Site 1 is a site called connectWork.com, that connects people to “gig” workers for various jobs. Site 2 is called supportLocalPlanners.com, and connects visitors with local businesses that can plan and organize events. The graphic below shows the action input mapping for each site:

Each site has mapped different values to the action configuration. For example, to the dynamic customerContact field, the owner of Site 1 has chosen to map the customer’s email from the trigger payload. The owner of Site 2 instead chose to map the customer’s phone number to the same field. Each site also filled the static fields with different values; for example, Site 1 gives the business only 1 day to accept a customer request, while Site 2 gives the business 2 days.

Every site that uses the action can have a different input mapping, but this does not affect the input schema you create as the app developer. When a new site installs your app and sets up the action, the site owner sees a blank action configuration matching your schemas, and creates their own input mapping.

For more information on the structure of the input schema, see About the Action Input Schema.

Overview of the UI schema

When a site owner uses your action in an automation on their site, they may need to configure the action settings. Wix provides a user interface to make configuration easier for users.

A basic UI is defined automatically as you create the action input schema, but to add more advanced functionality, you can define a second schema when you create your action in your app's dashboard. This is the UI schema. In the app dashboard, it's displayed directly below the input schema. Unlike the input schema however, it's not a JSON schema.

The UI schema gives you extra options for a field such as adding a placeholder or making the field read-only. It also provides type-specific options. For example, you can turn a boolean field into a checkbox, instead of a toggle, or turn a number field into a slider instead of a simple field.

The UI schema also lets you mark a field as dynamic, so that it can accept values from the trigger payload. There is no way to make a field dynamic using the input schema; you must do this through the UI schema.

It’s important to note that you cannot add new fields with the UI schema. You can only add functionality to fields that already exist in the input schema.

Overview of the output schema

After an action executes, it can output data to the automation’s next steps. You define the action’s output with an output schema.

Like the input schema, the output schema is a JSON schema that you configure when you add your action in the app dashboard. Unlike the input schema, however, the output schema is optional. You can choose to define an output schema for your action if you need it to return data.

The action receives a payload from previous steps in the automation. The output schema may enrich this payload by adding new data to the payload. When the action completes, it returns any fields defined in the output schema. These fields are appended to the payload data. For example, when the Add a Coupon action returns, it enriches the payload with the new coupon code it creates.

Subsequent steps in the automation flow can then use this enriched data. A condition following Add a Coupon, for example, might check if the new contact has opted in to receive marketing communications. If they have, the condition can then pass the action output data to the Send an email action, which uses the coupon code as a dynamic value.

The output schema uses the same annotations as the trigger payload schema.

Implement service plugin methods

The Action service plugin offers methods that you can implement as an action provider to make your actions more robust and easily managed, on both a user’s site and your end.

Wix makes each method call at specific times in an action’s lifecycle. It sends the method parameters to a URI that you define when you set up the action in your app's dashboard. It expects you to return your data in the form of the response object defined in the method reference.

Currently there are two action service plugin endpoints that you can implement for your action:

• Validate Configuration: Wix calls this when a user first configures your action on their site, and again whenever they select an automation containing your action. When the endpoint is called, Wix sends you the current action configuration. You can perform your own logic to determine if the action configuration is valid. In the response object, you must indicate if it is valid or not and return specific errors if not.

  An example of this is if a user is storing coupons on your server, and offering those coupons to first-time site visitors. They define the coupon ID to fetch from your server in their action. If that coupon ID has expired or been deleted, then an action using it is no longer valid. You can check this in your server-side logic and return an error to the user indicating that they need to change the coupon ID used in the action.

• Get Quota Info: You may provide limited resources to a user (for example, if you provide SMS messaging and your users can send only 100 messages per month). If you implement this endpoint, Wix calls it whenever a user checks their quota information. It will send you the action key and expects an object in return containing the quota info, including how much of the resource has been used (for example, 50 out of 100 SMS messages). Wix then displays the data you return in the user’s dashboard.

What’s next

• Learn how to add an action to your app in the app dashboard.
• Learn more about the action input schema.
• Learn more about the UI schema.