About the Wix Automations Action Service Plugin
The Action Provider service plugin (formerly SPI) allows you to implement an action that site contributors can add to automations on their sites. This means you can take actions in your service in response to events that happen on Wix sites or in the business manager. For example, in response to a trigger, your service can send an email, generate an invoice, or update another Wix service using its APIs.
The Action service plugin lets you do the following:
- Validate the input values to the action and return an error to the user if they are invalid.
- Display the limits you enforce on the number of actions a user can perform.
Before you begin
- Keep in mind that once you publish an app with a custom action, there are limitations to the changes you can make to the input schema you define when configuring your action. Learn more about editing a published input schema.
- Wix does not validate breaking changes to an input schema that uses composition. To ensure the user does not make errors when configuring an action that uses composition in its schema, we recommend performing the validation on your end.
Terminology
- Input schema: A JSON Schema object that defines the fields that Wix needs to pass to your Action service plugin endpoints. Learn more about the input schema here.
- UI schema: The JSON schema that defines the UI for your action configuration in the user's site dashboard.
How to set up an action
To configure your action in your app's dashboard:
-
Select Automations from the left menu, then select Create New > Action.
-
Give your action a name. This is displayed to users when they add the action in the Automations UI.
Notes:
- Your action key is generated automatically from the action name. Once you save your action you cannot change the action key.
- The action key is not displayed to users.
-
Add a short description explaining what your action does. The description is displayed to users when they select your action. This is an optional field.
-
Choose whether to hide the action, so it doesn't appear as an individual action on a user site. You should do this if the action is part of a pre-installed automation.
-
Under Action's service plugin endpoints, enter your base provider URI and select the service plugin endpoints you intend to implement.
-
Configure your input schema.
-
Optionally, configure your action's UI.
-
Click Save at the top of the page in order to save your action.
-
Next, you need to test your action to make sure everything's working. You can install your app on a free Premium development site to test it.
Once you create the test site, return to your app's dashboard and click Test Your App > Dashboard. Select the test site you installed your app on earlier. Use this site to make sure your action is working.
-
When you have tested your app and are ready to publish your new action, submit your app for review. A member of our team will check the changes and approve the latest version.
Once our team has approved your app, it will be published and available for users to install on their sites. When a user installs your app, your actions become available for their automations, as shown here:
Validate Configuration
This endpoint is used to validate the user's action configuration.
Wix calls this endpoint when a site contributor configures an automation with your action, and when they select the automation from the Your automations list in the Automations dashboard. Wix uses the returned response to display an error message to a site contributor if the action is invalid.
Implementing this endpoint is optional. To implement it, select the endpoint under Action's service plugin Endpoints when editing your action in the app dashboard. If you don't implement this endpoint, Wix assumes that the action is always valid.
As an example, a user configures an action called “Send gift card”, where a gift card is identified by a unique UUID. After some period of time the user deletes the gift card, making the action’s mapping with the current UUID invalid. Validate Configuration checks the validity of the action’s input values, and returns an error to the user if one or more of the values is not valid.
Get Quota Info
This endpoint retrieves quota information for an action.
Wix calls this endpoint when a site contributor opens the Manage your automations quotas modal in the Automations dashboard. The response from this endpoint is displayed in the modal. The data is displayed based on the response body format. Learn more about quota display options.
Implementing this endpoint is optional. To implement it, select the endpoint under Action's service plugin Endpoints when editing your action in the app dashboard.
Notes:
- Wix doesn't enforce action quota limits, it only displays them to the user. Enforcing quota limits is the action provider's responsibility.
Invoke
This endpoint is used to invoke an action provider's action.
Wix calls this endpoint when an automation using the provider's action is triggered. The request body includes all the data needed to execute the action including the final values of any dynamic parameters.
There is no need to validate the data in the request body against the JSON schema defined when the action was configured. Wix validates the data before calling this endpoint.