---
title: Developing custom marketing automation actions
related:
  - https://docs.kentico.com/13/on-line-marketing-features/managing-your-on-line-marketing-features/marketing-automation.md
  - https://docs.kentico.com/13/on-line-marketing-features/managing-your-on-line-marketing-features/marketing-automation/working-with-the-automation-process-designer/adding-marketing-actions-to-automation-processes.md
  - https://docs.kentico.com/13/custom-development/extending-the-administration-interface/developing-form-controls/reference-field-editor.md
---

> Agent instructions:
> **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown.
>
> - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version.
> - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt).

> **Info:** **Enterprise license required**
>
> Features described on this page require the **Kentico Xperience Enterprise** license.

Xperience allows you to program your own [action steps](https://docs.kentico.com/13/on-line-marketing-features/managing-your-on-line-marketing-features/marketing-automation/working-with-the-automation-process-designer/adding-marketing-actions-to-automation-processes.md), which users can then incorporate into [automation processes](https://docs.kentico.com/13/on-line-marketing-features/managing-your-on-line-marketing-features/marketing-automation.md). You need to:

1. Write the action's code in a custom class.
2. (Optional) Develop another custom class for loading and displaying action information in the automation process designer.
3. Register the class as a new action in the system.

## Writing custom actions

> **Note:** **Note**: Add the custom action code to your Xperience administration project, not the MVC live site project (for more information, see [MVC development overview](https://docs.kentico.com/13/developing-websites/mvc-development-overview.md)).

1. Create a new class in your Xperience solution.

   - Add a new assembly (_Class Library_ project) to the solution and include the class there.

   - Add references to the required Xperience libraries (DLLs) for the assembly. You need at least the following libraries:

     - **CMS.Automation.dll**
     - **CMS.Base.dll**
     - **CMS.ContactManagement.dll**
     - **CMS.Core.dll**
     - **CMS.DataEngine.dll**
     - **CMS.WorkflowEngine.dll**

   - Remember to reference the custom assembly from the Xperience administration project (_CMSApp_).

2. Set the class to inherit from one of the following base classes:

   - **CMS.Automation.AutomationAction** – for general automation actions
   - **CMS.ContactManagement.ContactAutomationAction** – for actions that work with the contacts being handled by the process

3. Override the **Execute** method from the base class.

   ```csharp
   public override void Execute()
   {
   }
   ```

4. Write the code that you want the action to run into the _Execute_ method's body.

### Working with action parameters

Parameters allow users to modify the behavior of your custom action. Users can edit the values of parameters when configuring specific instances of the action step in the workflow designer. If you want your action step to use parameters, you need to define the parameters as fields when registering the action in the system.

To access the values of parameters in the code of your action class, call the **GetResolvedParameter** method provided by the base class. The method accepts the following arguments:

- **parameter name** – the exact **Field name** set for the parameter in the system.
- **default value** – the value returned if the parameter is empty for the given action step.

```csharp title="Example"
GetResolvedParameter<string>("MessageText", string.Empty);
```

## Displaying action information in the process designer

Marketing automation actions may optionally retrieve any kind of data and display the information through the resulting steps in the process designer interface. For example, the system's default _Send marketing email_ action step loads and displays the name of the related email, as well as available statistics gathered for the given email (number of sent emails, open and link click rate).

The information can be displayed when editing a marketing automation process in the designer on the _Process_ tab, either directly within the step box (as a step description) or on request after a user clicks the step information icon.

> **Info:** **Note**: The step information icon only becomes available after the given process has been started for at least one contact.

To allow your custom marketing automation actions to display information, you need to create and assign an additional "data provider" class:

1. Add a new class within the _Class Library_ project containing the related [action class](#writing-custom-actions).

2. Make the class inherit from the **AutomationActionDataProvider** base class (available in the _CMS.Automation_ namespace).

3. Override one or both of the following methods:

   - **GetStepDescription** – to display text directly within the action step box.
   - **GetStepInformation** – to retrieve and display data via the step information icon.

     > **Tip:** **Getting action parameter values**
     >
     > To access the values of action parameters in the code of your data provider class, call the **GetStepParameter** method available in the base class. The method accepts the following arguments:
     >
     > - **stepInfo** – an object representing the related action step. Get the object by calling the _GetStepInfo_ method with the step ID provided as an argument of the _GetStepDescription_ or _GetStepInformation_ methods.
     > - **parameter** – the exact **Field name** set for the parameter in the system.

   > **Note:** **Security recommendations**
   >
   > If you work with values that originate from user input, we strongly recommend protecting your step description or information content against potential security threats, such as [cross-site scripting (XSS)](https://en.wikipedia.org/wiki/Cross-site_scripting). For example, encode values using the **HTMLHelper** class and its **HTMLEncode** or **EncodeForHtmlAttribute** methods.

4. If you defined the _GetStepInformation_ method, also set the class's **DisplayInformationIcon** property to _true_ (we recommend adding a parameterless constructor for this purpose).

5. Select the class as the **Action data provider** when you [register related actions](#registering-actions-in-the-system) in the system.

```csharp title="Example"
using CMS.Automation;
using CMS.Helpers;
using CMS.WorkflowEngine;

public class CustomActionDataProvider : AutomationActionDataProvider
{
    public CustomActionDataProvider()
    {
        // Enables the information icon for process steps based on the action
        DisplayInformationIcon = true;
    }

    public override string GetStepDescription(int stepId)
    {
        // Gets an object representing the action step
        WorkflowStepInfo step = GetStepInfo(stepId);

        // Gets the value of a step parameter with the 'MessageText' Field name (of the 'Text' Data type)
        string parameterValue = GetStepParameterValue<string>(step, "MessageText");

        // Prepares the step description data and returns the result in the form of an HTML string
        // The returned HTML content is displayed within the step box in the process designer interface
        return $"Action parameter: {HTMLHelper.HTMLEncode(parameterValue)}";
    }

    public override string GetStepInformation(int stepId)
    {
        // Retrieves the required data and returns the result in the form of an HTML string
        // The returned HTML content is displayed when a user clicks the step information icon in the process designer interface
        var customValue = 42;
        return $"<div>Retrieved data: {customValue}</div>";
    }
}
```

The action data provider class can be used together with any number of custom actions. The data (returned HTML content) is displayed for the given actions in the process designer (on the _Process_ tab when editing a marketing automation process).

## Registering actions in the system

Once you create the class containing the required logic, you need to register the custom action:

1. Sign in to the Xperience administration interface and open the **Marketing automation** application.
2. Switch to the **Actions** tab.
3. Click **New action**.
4. Fill in the following fields:

   - **Display name** – the name of the action step used in the user interface.
   - **Action provider**
     - **Assembly name** – specify the name of the library containing the [action class](#writing-custom-actions).
     - **Class name** – specify the full name of the action class (including the namespace).
   - (Optional) **Action data provider** – specify the assembly and class name of the appropriate _AutomationActionDataProvider_ class if you want to [display custom information](#displaying-action-information-in-the-process-designer) in your action steps.
5. Click **Save**.
6. If the action has any parameters, switch to the **Parameters** tabs and define the [form fields](https://docs.kentico.com/13/custom-development/extending-the-administration-interface/developing-form-controls/assigning-form-controls-to-fields.md) through which users can configure the action.

Users can now place your custom action into the automation process designer.