Add an Action to your App

As a developer, you can provide actions to Wix users when they install your app. Follow this article to learn how to set up an action in the app dashboard.

Before you begin

You need to have an app already created in the Custom Apps page.

Step 1 | Set up the action

Start by creating an action for your app in the Dev Center.

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

  2. At the top of the page, click Create New > Action. This opens the New Action page.

    On the left of the page is some basic setup required to publish your action. 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. In the Action details section, give your action a name. The name is displayed to users when they go to select an action for their automation.

    It’s important to give your action a clear name, so that users understand what it does. 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 birthday card
    • Create appointment for guest
    • Request tour booking

  4. Give your action a key. Wix uses the action key when it makes calls to your URI. It is not visible to users.

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

    Wix suggests a default 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 after they select your action in their dashboard.

Step 2 | Choose service plugin endpoints to implement

You’re required to implement the Invoke endpoint in your server code. Invoke executes your action logic.

In addition to Invoke, you have the option to implement other service plugin endpoints that perform logic on your app’s end when Wix calls them. Choose the endpoints you want to implement in the Service plugin endpoints section of the New Action page:

  1. Whether or not you implement optional service plugin endpoints, you’re required to provide a valid service plugin URI, so that Wix knows where to call Invoke. Wix looks for the Invoke endpoint under the relative route <your base uri>/v1/invoke.

    Implement any additional service plugin endpoints in a similar manner. 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 to test it. Test values that you enter in the preview aren’t saved and don’t affect the UI that Wix users see on their site.

  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 do the following:

  • Extend the functionality of the basic UI generated by the input schema.
  • Mark fields as dynamic.

To create a UI 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 Action UI library.

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

    Copy

  3. If you want to define your action's output, continue to Step 5 to create the output schema. Otherwise, click Save & Close to save your action and exit, and skip to Step 6 to test the action on a site.

Step 5 | Configure the output schema (optional)

Create a JSON schema that defines the data your action outputs. You can skip this step if your action doesn’t output any data.

  1. Click the toggle on the section labeled Configure an output schema to open it.

  2. Click on Generate from Sample Data. In the modal that opens, enter sample data that you expect your action to output. When you have entered all your data, click Convert to Schema. Wix generates a JSON schema based on the data you entered.

  3. Review the generated schema and add or edit fields as needed. Use the Format Schema button at the bottom of the section to format your schema nicely.

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 to open the Automations Builder. In the panel on the left, select any trigger from the options presented.

  5. Below the trigger, click the + symbol and select Action. This opens the action panel on the left. Locate your action in the list.

  6. Select the action to see the UI you created with your input and UI schemas. 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?