About Actions

An action is an automation’s response after it is triggered. Wix provides site owners with a number of built-in actions, such as Send a push notification or Update Google sheets.

Wix apps may add extra actions to a user’s site. 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 so you can manage your app’s actions once they’re installed 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 payload 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.

Action configuration

When you create an action for your app, in addition to basic configuration like name, key, and description, you need to define the action’s input and output. There are 3 schemas you can use to do this:

• The action input schema defines the input data to the action and creates a default action configuration UI.
• The UI schema lets you customize the action configuration UI further and mark fields as dynamic.
• The output schema defines the action’s output data.

The input schema is the only schema you're required to create, but configuring the UI and output schema enriches your action and makes it more dynamic.

The input schema

The input schema is a JSON schema that defines the data an action expects to receive. When creating an action extension, you’re required to configure this schema.

Each piece of data that the action expects is defined as a schema property with one of the following types:

• String
• Number
• Integer
• Boolean
• Object
• Array

These properties are also used to define an action configuration UI. The user sees this UI when they configure your action in the site dashboard. The configuration UI provides fields that make it easy for users to set input data.

For example, let’s say you create an action that books private events. Such an action requires the following information: the event name, number of guests, event type, and whether catering is needed. The input schema for your action might look something like this:

The above schema defines each of the fields that your action needs. When the action runs as part of an automation, it will receive the value for each field in one of two ways:

• As a dynamic value taken from the payload the action receives.
• As a static value supplied by the site owner.

Read more about the difference between these two types of values in the Static vs. Dynamic values section.

The input schema also generates an action configuration UI based on the fields you define in the schema. The example above generates a UI like this:

A user sees a similar UI when they configure your action on their site.

You can learn more about the technical specifications of configuring your input schema in The Action Input Schema.

The UI schema

The UI schema is an optional, non-JSON schema that serves to enhance the input schema you define. It allows you to do two important things:

• Add more advanced functionality to your action’s configuration UI.
• Mark fields as dynamic.

Wix automatically generates a basic action configuration UI from your input schema. In the input schema, you can make some minor enhancements to this UI, such as marking fields as required by adding them to the required array, or adding a tooltip to a field with the description key. However, your ability to significantly change the basic UI from the input schema is limited.

With the UI schema, you can apply a much wider range of enhancements to the UI. The UI schema provides 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 Action UI Library displays all the possible options for each field type, and provides a playground for you to test out different features.

The UI schema also lets you mark fields as dynamic. By default, fields defined in the input schema are static and can only accept input from the site owner. 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.

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 output schema may enrich the payload passed to the action by adding data to the payload. For example, when the Add a Coupon action returns, it adds a new coupon code to the payload.

Subsequent steps in the automation flow can then use this 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 technical specifications for the output schema are the same as the trigger payload schema.

Static vs. dynamic values

Your action can accept two different types of values as input:

• Static: The values in these fields stay the same every time the automation is triggered, unless the user edits the automation. This is the default for all fields in the input schema.
• Dynamic: The values in these fields are taken from the trigger payload, and therefore change each time the automation is triggered. Fields are set as dynamic in the UI schema.

Static values

When a user installs and configures your action on their site, they may 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 string field in your input schema to hold the link. This field is static by default and expects user input. When a user installs your app and configures your action on their site, they must enter a value in that field. Then, each time the automation runs and sends an SMS, the same link is sent in every message.

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 use the UI schema to mark fields in your input schema as dynamic. These dynamic fields can then 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 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.

What’s next

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