Developing custom marketing automation actions

Xperience allows you to program your own action steps, which users can then incorporate into automation processes. 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

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.

   Copy

   
   
   
    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<Type> 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.

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.

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.
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.

     Getting action parameter values

     To access the values of action parameters in the code of your data provider class, call the GetStepParameter<Type> 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.
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). 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 in the system.

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.
     • 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 in your action steps.

5. Click Save.

6. If the action has any parameters, switch to the Parameters tabs and define the form fields through which users can configure the action.

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