Add an Action to your App

As a developer, you can act as an action provider for Wix site owners by adding actions to your app. Follow this article to learn how to set up an action in your app's dashboard.

Before you begin

You need to have a custom app already created in your Wix Studio workspace.

Step 1 | Set up the action

Start by creating an action for your app in your app's dashboard.

  1. From your app’s dashboard, go to Automations.

  2. At the top of the page, click Create New > Action. You’ll see a page that looks like this:

    On the left of the page is some basic setup required to publish your action. You’ll handle this in the next step.

    On the right, you’ll see an action preview section. This shows a preview of the options that will appear on a user’s site dashboard when they set up your action. The preview updates automatically as you configure your action.

  3. Give your action a name. The name will be displayed to the user when they go to select an action for their automation.

    To keep your action name user-friendly and consistent with other actions, we recommend following these best practices:

    • Use active voice.
    • Keep the name singular.
    • Use sentence case, and don't end with a period.
    • Make sure it can’t be confused with another action. For example, the action name “Send an email” is already in use, so name your action instead something like “Send a confirmation email”.

    Some examples of good action names are:

    • Send a card
    • Create appointment
    • Request booking

  4. Give your action a key. Wix will use the action key when it makes calls to your URI (if you choose to implement service plugin methods). It is not visible to users.

    Once you save your action, you can’t edit the action key.

    By default, Wix creates the key based on your app’s name and the action name. The default key takes the following format: <app_name>-<action_name>. We recommend sticking with this format, but you can edit the action key as long as it meets the following standards:

    • Starts with a letter or number.
    • Contains only lowercase letters, numbers, hyphens, and underscores.
    • Isn't the same as another action key in your app.

  5. Optionally, add a description of your action that explains what it does. This is displayed to users when they select your action in their dashboard.

Step 2 | Choose service plugin endpoints to implement

You have the option to implement action service plugin (formerly SPI) endpoints that perform logic on your app’s end when Wix calls into your app URI. Mark any service plugin endpoints that you’ve implemented in the Action’s service plugin endpoints section.

  1. Whether or not you implement service plugin endpoints, you are required to provide a valid service plugin URI. Once you save your action, you cannot edit the URI.

    If you do implement any of the endpoints, give your app’s base URI. Then implement the endpoint under the relative route. For example, implement Validate Configuration under <your base uri>/v1/validate-configuration.

  2. Select whichever endpoints you plan to implement.

Step 3 | Configure the input schema

Create a JSON schema that defines the inputs your action can receive from the user or the trigger payload.

  1. In the section labeled Configure the input schema, click Generate from Sample Data.

  2. In the modal that opens, enter sample data that you expect to be passed to your action. When you have entered all your data, click Convert to Schema.

    Wix generates an input schema for you from the data you enter.

  3. Review the generated schema and add or edit any fields you need to.

    By default, all the fields you add in the generator are added to the required array. Manually remove any fields that you don’t want marked as required in the action configuration UI.

    Use the Format Schema button at the bottom of the section to format the JSON if needed.

  4. Notice that a field appears in the action preview every time you add a property to the input schema properties object. You can interact directly with the action preview and enter values into the fields that appear.

  5. If you want to create extra functionality in your action UI, continue to Step 4 to build the UI schema. Otherwise, click Save & Close to save your action, and skip to Step 6 to test the action on a site.

Step 4 | Configure the UI schema (optional)

The UI schema allows you to extend the functionality of the basic UI generated by the input schema.

  1. In the section labeled User Interface, add a key-value schema.

    To add extra features to a field in the action configuration UI, add a key to the UI schema that matches the field’s key in the input schema. Create a new object as its value. For example, if you have a number field age in your input schema, create a field with a matching key in the UI schema:

    Copy

    Add the properties inside the object value. You can learn more about the properties available to each data type in the UI schema Storybook.

  2. To make a field dynamic, use the dynamicValuesOptions field, and set enabled to true:

    Copy

  3. To define your action's output, continue to Step 5. Otherwise, click Save & Close to save your action and exit.

Step 5 | Configure the output schema (optional)

The output schema is a JSON schema that defines the fields that your action outputs. These fields are appended to the payload and passed to subsequent steps in the automation.

  1. Expand the section labeled Output schema.

  2. Click Generate from Sample Data. In the modal that opens, enter a sample payload that represents your action's output. Click Convert to Schema to generate the JSON schema.

  3. Add any other properties or annotations that the schema requires.

You now have a configured action that is ready to test on a site in the next step.

Step 6 | Test your action on a site

Test your action on a free development site to see how the UI appears on a user’s site.

  1. On the main Automations page in your app, click Test Your App, and select Dashboard. Select the site you want to test your action on. This takes you to the site’s App Market page.

  2. Click Add to Site. In the window that pops up, click Agree & Add to give the app permissions for your site.

    Once the app is installed successfully, you can close the window and return to the App Market page.

  3. On the App Market page, click Open. This takes you to your app in the site dashboard.

  4. In the dashboard, go to Automations and click New Automation > Start from Scratch. Select any trigger from the options presented.

  5. Scroll down to Choose an action and locate the action by its name.

  6. Select the action. Below the action options, the UI you created with your input and UI schemas is displayed. You can test the UI by entering values into the fields. The fields perform validation and will give you an error if you enter an invalid value.

  7. To test the automation further, click Activate and try it out on your published site.

You’ve now created an action as part of your app.

Did this help?