Custom automation steps

using Microsoft.Extensions.Logging;
using System.Threading;
using System.Threading.Tasks;

using CMS.Automation;
using CMS.ContactManagement;
using Kentico.Xperience.Admin.Base;

using Acme.Automation;

[assembly: RegisterAutomationAction<AuditLogAction>(
    identifier: AuditLogAction.IDENTIFIER,
    displayName: "Log to audit system",
    Description = "Logs an audit event to an external logging service.",
    IconName = Icons.BoxCogwheel)]

namespace Acme.Automation;

public class AuditLogAction : AutomationAction
{
    public const string IDENTIFIER = "Acme.AuditLog";

    private readonly ILogger<AuditLogAction> logger;

    public AuditLogAction(ILogger<AuditLogAction> logger)
    {
        this.logger = logger;
    }

    public override async Task Execute(AutomationProcessContext context, CancellationToken cancellationToken)
    {
        // Gets the processed contact
        ContactInfo contact = await context.GetProcessedObject(cancellationToken);

        // Gets the display name of the current automation process
        var processName = context.Process.DisplayName;

        // Logs an audit event
        // Assumes the application contains an external logging provider that receives events from "Acme" namespaces
        logger.LogInformation("Contact '{ContactFirstName} {ContactLastName}' reached the audit step in process '{ProcessName}'.",
    contact.ContactFirstName, contact.ContactLastName, processName);
    }
}

using System.Threading;
using System.Threading.Tasks;

using CMS.Automation;
using CMS.ContactManagement;
using CMS.EmailEngine;

using Kentico.Xperience.Admin.Base;
using Kentico.Xperience.Admin.Base.FormAnnotations;

using Acme.Automation;

[assembly: RegisterAutomationAction<EmailNotificationAction>(
    identifier: EmailNotificationAction.IDENTIFIER,
    displayName: "Send email notification",
    Description = "Sends an email with a specified subject and body to a designated recipient.",
    IconName = Icons.MessageMicro)]

namespace Acme.Automation;

public class EmailNotificationActionProperties : IAutomationActionProperties
{
    // Text input for entering the recipient email address
    [TextInputComponent(Label = "Recipient email", Order = 10)]
    // Validation rule to enforce valid email address format
    [EmailValidationRule]
    // The value for this property is required
    [RequiredValidationRule]
    public string RecipientEmail { get; set; }

    // Text input for entering the notification email subject
    // Default value set to "Automation notification"
    [TextInputComponent(Label = "Subject", Order = 20)]
    // The value for this property is required
    [RequiredValidationRule]
    public string Subject { get; set; } = "Automation notification";

    // Rich text editor for entering the notification email body
    [RichTextEditorComponent(Label = "Message body", Order = 30)]
    public string Body { get; set; }
}

public class EmailNotificationAction : AutomationAction<EmailNotificationActionProperties>
{
    public const string IDENTIFIER = "Acme.SendEmailNotification";

    private readonly IEmailService emailService;

    public EmailNotificationAction(IEmailService emailService)
    {
        this.emailService = emailService;
    }

    public override async Task Execute(
        EmailNotificationActionProperties properties,
        AutomationProcessContext context,
        CancellationToken cancellationToken)
    {
        if (string.IsNullOrEmpty(properties.RecipientEmail) || string.IsNullOrEmpty(properties.Subject))
        {
            return;
        }

        // Gets the processed contact
        ContactInfo contact = await context.GetProcessedObject(cancellationToken);

        var body = $"{properties.Body}" +
                   $"<hr>" +
                   $"<h3>Contact details</h3>" +
                   $"Name: {contact.ContactFirstName} {contact.ContactLastName}<br>" +
                   $"Email: {contact.ContactEmail}";

        // Sends the email message
        var message = new EmailMessage
        {
            From = "automation@localhost.local",
            Recipients = properties.RecipientEmail,
            Subject = properties.Subject,
            Body = body
        };

        await emailService.SendEmail(message);
    }
}

using CMS.Automation;
using Kentico.Xperience.Admin.Base;

[assembly: RegisterAutomationAction<SyncContactToCrmAction>(
    identifier: SyncContactToCrmAction.IDENTIFIER,
    displayName: "Sync contact to CRM",
    IconName = Icons.ArrowRightTopSquare,
    Description = "Pushes the current contact's data to the external CRM.")]

using System.Threading;
using System.Threading.Tasks;

using CMS.Automation;
using CMS.ContactManagement;

using Kentico.Xperience.Admin.Base;

using Acme.Automation;

[assembly: RegisterAutomationCondition<HasActiveSubscriptionCondition>(
    identifier: HasActiveSubscriptionCondition.IDENTIFIER,
    displayName: "Has active subscription",
    Description = "Branches based on whether the contact has an active subscription in the billing system.",
    IconName = Icons.CheckCircle)]

namespace Acme.Automation;

public class HasActiveSubscriptionCondition : AutomationCondition
{
    public const string IDENTIFIER = "Acme.HasActiveSubscriptionCondition";

    // Represents a custom service that checks subscription status in an external billing system
    private readonly ISubscriptionService subscriptionService;

    public HasActiveSubscriptionCondition(ISubscriptionService subscriptionService)
    {
        this.subscriptionService = subscriptionService;
    }

    public override async Task<bool> Evaluate(AutomationProcessContext context, CancellationToken cancellationToken)
    {
        // Gets the processed contact
        ContactInfo contact = await context.GetProcessedObject(cancellationToken);

        // Returns true/false to send the contact to the corresponding process branch
        return await subscriptionService.HasActiveSubscription(contact.ContactEmail, cancellationToken);
    }
}

using Microsoft.Extensions.Logging;
using System.Threading;
using System.Threading.Tasks;

using CMS.Automation;

using Kentico.Xperience.Admin.Base;
using Kentico.Xperience.Admin.Base.FormAnnotations;

using Acme.Automation;

[assembly: RegisterAutomationCondition<ScoreThresholdCondition>(
    identifier: ScoreThresholdCondition.IDENTIFIER,
    displayName: "Contact score reaches threshold",
    Description = "Branches based on whether the contact's score reaches a configured threshold.",
    IconName = Icons.StarFull)]

namespace Acme.Automation;

public class ScoreThresholdConditionProperties : IAutomationConditionProperties
{
    // Number input for entering the score threshold
    [NumberInputComponent(Label = "Score threshold", Order = 10)]
    // The threshold cannot be negative
    [MinimumIntegerValueValidationRule(0)]
    public int Threshold { get; set; } = 50;
}

public class ScoreThresholdCondition : AutomationCondition<ScoreThresholdConditionProperties>
{
    public const string IDENTIFIER = "Acme.ScoreThresholdCondition";

    private readonly ILogger<ScoreThresholdCondition> logger;

    public ScoreThresholdCondition(ILogger<ScoreThresholdCondition> logger)
    {
        this.logger = logger;
    }

    public override async Task<bool> Evaluate(
        ScoreThresholdConditionProperties properties,
        AutomationProcessContext context,
        CancellationToken cancellationToken)
    {
        // Gets the contact score stored earlier in the process by a preceding scoring action.
        // 'ContactScoreData' is a shared process data class that implements IAutomationProcessData
        // (see the 'Example - Two-step data sharing' section).
        ContactScoreData scoreData = await context.GetProcessData<ContactScoreData>(cancellationToken);

        // Follows the false branch when no score has been stored yet, for example when the
        // process is missing the preceding step that calculates and stores the score.
        if (scoreData is null)
        {
            logger.LogWarning("No score data found in the process context.");
            return false;
        }

        // Follows the true branch when the stored score reaches the configured threshold
        return scoreData.Score >= properties.Threshold;
    }
}

using CMS.Automation;
using Kentico.Xperience.Admin.Base;

[assembly: RegisterAutomationCondition<HasActiveSubscriptionCondition>(
    identifier: HasActiveSubscriptionCondition.IDENTIFIER,
    displayName: "Has active subscription",
    IconName = Icons.CheckCircle,
    Description = "Branches based on whether the contact has an active subscription.")]

using Kentico.Xperience.Admin.Base.FormAnnotations;

// ...

// Default value set to "Automation notification"
[TextInputComponent(Label = "Subject", Order = 20)]
public string Subject { get; set; } = "Automation notification";

using Kentico.Xperience.Admin.Base.FormAnnotations;

// ...

// Sets a custom label for the "Step name" property
[TextInputComponent(Label = "Notification step title")]
public string StepDisplayName { get; set; }

using System.Collections.Generic;
using System.Threading.Tasks;

using Kentico.Xperience.Admin.Base.FormAnnotations;

public class CrmSystemOptionsProvider : IDropDownOptionsProvider
{
    public Task<IEnumerable<DropDownOptionItem>> GetOptionItems() =>
        Task.FromResult<IEnumerable<DropDownOptionItem>>(
        [
            new DropDownOptionItem { Value = "crm1", Text = "CRM 1" },
            new DropDownOptionItem { Value = "crm2", Text = "CRM 2" },
            new DropDownOptionItem { 
                Value = "crm3",
                Text = "CRM 3",
                Tooltip = "Requires CRM connector configuration. Consult your administrator before use."
            }
        ]);
}

using Kentico.Xperience.Admin.Base.FormAnnotations;

// ...

[DropDownComponent(
    Label = "CRM system",
    DataProviderType = typeof(CrmSystemOptionsProvider),
    Order = 10)]
public string CrmSystem { get; set; }

using CMS.Automation;

using Kentico.Xperience.Admin.Base.FormAnnotations;

[FormCategory(Label = "General", Order = 10)]
[FormCategory(Label = "Advanced", Order = 110, Collapsible = true, IsCollapsed = true)]
public class CrmSyncActionProperties : IAutomationActionProperties
{
    // General category

    // Drop-down selector with predefined options
    [DropDownComponent(Label = "CRM System",
        Options = "crm1;CRM 1\ncrm2;CRM 2\ncrm3;CRM 3",
        Order = 11)]
    [RequiredValidationRule]
    public string CrmSystem { get; set; } = "crm1";

    // Checkbox property enabled by default
    [CheckBoxComponent(Label = "Update existing records", Order = 21)]
    public bool UpdateExisting { get; set; } = true;

    // Advanced category

    // Number input with a default value that allows values between 1 and 10
    [NumberInputComponent(Label = "Retry attempts", Order = 111)]
    [MinimumIntegerValueValidationRule(1)]
    [MaximumIntegerValueValidationRule(10)]
    public int RetryAttempts { get; set; } = 3;

    // Note rich text editor visible if 'Update existing records' is enabled
    [RichTextEditorComponent(Label = "Notes", Order = 121)]
    [VisibleIfTrue(nameof(UpdateExisting))]
    public string Notes { get; set; }
}

using CMS.Automation;
using CMS.ContactManagement;

// ...

public override async Task Execute(AutomationProcessContext context, CancellationToken cancellationToken)
{
    // Returns the processed ContactInfo
    ContactInfo contact = await context.GetProcessedObject(cancellationToken);

    // Accesses contact properties
    string contactName = contact.ContactDescriptiveName;
    int contactId = contact.ContactID;

    // ...
}

using CMS.Automation;

// ...

public override async Task Execute(AutomationProcessContext context, CancellationToken cancellationToken)
{
    // Gets the display name of the current automation process
    string processName = context.Process.DisplayName;

    // ...
}

using CMS.Automation;

using Acme.Automation;

// ...

public override async Task Execute(AutomationProcessContext context, CancellationToken cancellationToken)
{
    // Gets the identifier of the trigger that started the process
    string triggerIdentifier = await context.GetTriggerIdentifier(cancellationToken);

    // Only proceeds when the process was started by a specific custom trigger
    if (!string.Equals(triggerIdentifier, PurchaseCompletedTrigger.IDENTIFIER))
    {
        return;
    }

    // Gets the custom trigger's typed data
    PurchaseData purchaseData = await context.GetTriggerData<PurchaseTriggerData>(cancellationToken);
    if (purchaseData is null)
    {
        return;
    }

    // Custom logic that uses the trigger data
    var total = purchaseData.TotalAmount;

    // ...
}

using System.Threading;
using System.Threading.Tasks;

using CMS.Automation;
using CMS.DataEngine;
using CMS.Helpers;
using CMS.OnlineForms;
using Kentico.Xperience.Admin.Base;

using Acme.Automation;

[assembly: RegisterAutomationAction<ProcessFormSubmissionAction>(
    identifier: ProcessFormSubmissionAction.IDENTIFIER,
    displayName: "Process form submission",
    Description = "Processes the data submitted by the form submission trigger.",
    IconName = Icons.Form)]

namespace Acme.Automation;

public class ProcessFormSubmissionAction : AutomationAction
{
    public const string IDENTIFIER = "Acme.ProcessFormSubmission";

    private readonly IInfoProvider<BizFormInfo> bizFormInfoProvider;
    private readonly IProgressiveCache progressiveCache;

    public ProcessFormSubmissionAction(
        IInfoProvider<BizFormInfo> bizFormInfoProvider,
        IProgressiveCache progressiveCache)
    {
        this.bizFormInfoProvider = bizFormInfoProvider;
        this.progressiveCache = progressiveCache;
    }

    public override async Task Execute(AutomationProcessContext context, CancellationToken cancellationToken)
    {
        // Only proceeds when the process was triggered by a form submission
        if (!await context.TriggeredByFormSubmission(cancellationToken))
        {
            return;
        }

        // Gets the trigger data captured when the form was submitted
        FormSubmissionTriggerData formData = await context.GetTriggerData<FormSubmissionTriggerData>(cancellationToken);
        if (formData is null)
        {
            return;
        }

        // Loads the submitted form record (cached)
        BizFormItem formItem = await GetFormItem(formData, cancellationToken);
        if (formItem is null)
        {
            return;
        }

        // Processes the submitted form record, e.g. reads its field values
        string email = formItem.GetStringValue("UserEmail", string.Empty);

        // ... custom logic
    }

    // Loads the submitted form record and caches it under a cache key unique to the submitted form and record
    private async Task<BizFormItem> GetFormItem(FormSubmissionTriggerData formData, CancellationToken cancellationToken)
    {
        return await progressiveCache.LoadAsync(async (cacheSettings, cancellationToken) =>
        {
            // Gets the form definition and resolves its class name
            BizFormInfo formInfo = await bizFormInfoProvider.GetAsync(formData.BizFormId, cancellationToken);
            if (formInfo is null)
            {
                // Does not cache when the form definition no longer exists
                cacheSettings.Cached = false;
                return null;
            }

            string formClassName = DataClassInfoProvider.GetDataClassInfo(formInfo.FormClassID).ClassName;

            // Loads the submitted form record by its ID
            BizFormItem formItem = BizFormItemProvider.GetItem(formData.BizFormItemId, formClassName);

            // Does not cache a missing record
            cacheSettings.Cached = formItem != null;

            return formItem;
        },
        // Unique cache key based on the submitted form and record IDs
        new CacheSettings(
            cacheMinutes: 10,
            IDENTIFIER, nameof(GetFormItem), formData.BizFormId, formData.BizFormItemId),
        cancellationToken);
    }
}

using System;

using CMS.Automation;

public class ContactScoreData : IAutomationProcessData
{
    public static string Identifier => "Acme.ContactScoreData";

    public int Score { get; set; }

    public DateTime ScoredAt { get; set; }
}

using System;
using System.Threading;
using System.Threading.Tasks;

using CMS.Automation;
using CMS.ContactManagement;
using Kentico.Xperience.Admin.Base;

using Acme.Automation;

[assembly: RegisterAutomationAction<ScoreContactAction>(
    identifier: ScoreContactAction.IDENTIFIER,
    displayName: "Score contact",
    Description = "Calculates and stores a score for the contact.",
    IconName = Icons.StarFull)]

namespace Acme.Automation;

public class ScoreContactAction : AutomationAction
{
    public const string IDENTIFIER = "Acme.ScoreContact";

    // Represents a custom service that calculates a score for a contact based on its activities and properties
    private readonly IContactScoringService scoringService;

    public ScoreContactAction(IContactScoringService scoringService)
    {
        this.scoringService = scoringService;
    }

    public override async Task Execute(AutomationProcessContext context, CancellationToken cancellationToken)
    {
        ContactInfo contact = await context.GetProcessedObject(cancellationToken);

        int score = await scoringService.CalculateScoreAsync(contact, cancellationToken);

        // Stores the score for downstream steps
        await context.SetProcessData(new ContactScoreData
        {
            Score = score,
            ScoredAt = DateTime.UtcNow
        }, cancellationToken);
    }
}

using System.Threading;
using System.Threading.Tasks;

using CMS.Automation;
using CMS.ContactManagement;
using Kentico.Xperience.Admin.Base;

using Microsoft.Extensions.Logging;

using Acme.Automation;

[assembly: RegisterAutomationAction<NotifyByScoreAction>(
    identifier: NotifyByScoreAction.IDENTIFIER,
    displayName: "Notify based on score",
    Description = "Notifies the sales team if the processed contact surpasses a score threshold.",
    IconName = Icons.ArrowSend)]

namespace Acme.Automation;

public class NotifyByScoreAction : AutomationAction
{
    private const int HIGH_SCORE_THRESHOLD = 80;

    // Represents a custom service that sends notifications to the sales team
    private readonly INotificationService notificationService;

    private readonly ILogger<NotifyByScoreAction> logger;

    public NotifyByScoreAction(ILogger<NotifyByScoreAction> logger, INotificationService notificationService)
    {
        this.logger = logger;
        this.notificationService = notificationService;
    }

    public override async Task Execute(AutomationProcessContext context, CancellationToken cancellationToken)
    {
        // Gets the contact score calculated by previous steps from the process data
        ContactScoreData scoreData = await context.GetProcessData<ContactScoreData>(cancellationToken);

        if (scoreData is null)
        {
            logger.LogWarning("No score data found in the process context.");
            return;
        }

        ContactInfo contact = await context.GetProcessedObject(cancellationToken);

        if (scoreData.Score >= HIGH_SCORE_THRESHOLD)
        {
            // High-scoring contact - notify the sales team
            await notificationService.NotifySalesTeamAsync(contact, scoreData.Score, cancellationToken);
            logger.LogInformation("High-scoring contact {ContactName} (score: {Score}) routed to sales.",
                contact.ContactDescriptiveName, scoreData.Score);
        }
        else
        {
            logger.LogInformation("Contact {ContactName} scored {Score}, below threshold.",
                contact.ContactDescriptiveName, scoreData.Score);
        }
    }
}

using CMS.Automation;
using CMS.ContactManagement;

using Microsoft.Extensions.Logging;
using System.Net.Http;
using System.Threading;
using System.Threading.Tasks;

public class MyAction(ILogger<MyAction> logger, 
                      IExternalAPI externalApi) : AutomationAction()
{    
    public override async Task Execute(AutomationProcessContext context, CancellationToken cancellationToken)
    {
        try
        {
            await externalApi.CallAsync(cancellationToken);
        }
        catch (HttpRequestException ex) when (!cancellationToken.IsCancellationRequested)
        {
            logger.LogError(ex, "External API call failed for contact with ID: {ContactId}.",
                (await context.GetProcessedObject(cancellationToken)).ContactID);
        }

        // Remaining Execute code continues
    }
}

using Microsoft.Extensions.Logging;
using System.Threading;
using System.Threading.Tasks;

using CMS.Automation;
using CMS.Helpers;

public class MyAction : AutomationAction
{
    private readonly ILogger<MyAction> logger;
    private readonly ICrmClient crmClient;
    private readonly IProgressiveCache cache;

    public MyAction(ILogger<MyAction> logger, ICrmClient crmClient, IProgressiveCache cache)
    {
        this.logger = logger;
        this.crmClient = crmClient;
        this.cache = cache;
    }

    public override async Task Execute(AutomationProcessContext context, CancellationToken cancellationToken)
    {
        // All injected services are available
        // ...
    }
}