Automation plans

Accessing the AutomationPlanDefinitionManager

The AutomationPlanDefinitionManager is available from the Sitecore DI container. It is preferable to include a parameter of type DefinitionManagerBase<IAutomationPlanDefinition, AutomationPlanDefinitionRecord> in the constructor of your class and pull your class from the container, allowing the container to resolve the instance for you:

RequestResponse

public MyClass(DefinitionManagerBase<IAutomationPlanDefinition, AutomationPlanDefinitionRecord> planDefinitionManager)
{
        ...
}

If you cannot use the container to construct your class, you can use the service locator. This class is also available in the Sitecore DI container:

RequestResponse

using Sitecore.DependencyInjection;
using Sitecore.Marketing.Definitions;

ServiceLocator.ServiceProvider.GetDefinitionManagerFactory().GetDefinitionManager<IAutomationPlanDefinition>();

Defining an automation plan

An Automation Plan is defined using types from the Sitecore.Marketing.Definitions.AutomationPlans.Model namespace. Unlike many other definitions which are almost simple POCOs, Automation Plans are more complex, containing collection properties.

Plan definition

The automation plan is represented by a definition item in Sitecore. The following example demonstrates how to define a basic plan.

RequestResponse

var manager = ServiceLocator.ServiceProvider.GetDefinitionManagerFactory().GetDefinitionManager<IAutomationPlanDefinition>();

Guid planId = Guid.NewGuid();

AutomationPlanDefinition plan = new AutomationPlanDefinition(planId, "Plan item name" CultureInfo.InvariantCulture, "Yuletide Gnome Campaign Plan", DateTime.UtcNow, "sitecore\\emma")
{
        ReentryMode = AutomationPlanReentryMode.Multiple,
        ContextKeyFactoryType = "MyFactory, MyAssembly", // Only needed if ReentryMode is set to Multiple
        Description = "A campaign plan about festive garden gnomes.",
        EndDate = new DateTime(2005, 12, 12),
};

Keep the following in mind:

ContextKeyFactoryType is only mandatory if ReentryMode is set to AutomationPlanReentryMode.Multiple

Activities

An automation plan contains a collection of activities. Activities are saved as a JSON on the plan item itself - not as individual sub-items. Each activity in a plan defines legal paths from itself to the next activity. Contacts traverse a plan by moving from activity to activity along the legal paths.

Keep the following in mind when defining activities:

Activity IDs must be unique within an automation plan
You must define a EntryActivityId - this is the ID of the AutomationActivityDefinition that contacts should start in
If an activity only contains a single path it will often be referred to as the Default path
Each ActivityTypeId should match the ID of an activity type configured in the Marketing Automation Engine
The order in which activities are added does not matter - the order in which a contact can traverse a plan is determined by the legal paths each activity defines

The following plan has three activities. firstActivity defines two paths - one that sends the contact to emailActivity (the default), and another that sends the contact to snailmailActivity.

RequestResponse

using Sitecore.Marketing.Definitions.AutomationPlans.Model;
using System;
using Sitecore.DependencyInjection;
using Sitecore.Marketing.Definitions;
using System.Globalization;

namespace Documentation
{
        public class AutomationPlans
        {
                public void Example()
                {
                        var manager = ServiceLocator.ServiceProvider.GetDefinitionManagerFactory().GetDefinitionManager<IAutomationPlanDefinition>();

                        Guid planId = Guid.NewGuid();

                        Guid entryActivityGuid = Guid.NewGuid();
                        Guid secondActivityGuid = Guid.NewGuid();

                        AutomationPlanDefinition plan = new AutomationPlanDefinition(planId, "Plan item name", CultureInfo.InvariantCulture, "Yuletide Gnome Campaign Plan", DateTime.UtcNow, "sitecore\\emma")
                        {
                                ReentryMode = AutomationPlanReentryMode.Multiple,
                                ContextKeyFactoryType = "MyFactory, MyAssembly", // Only needed if ReentryMode is set to Multiple
                                Description = "A campaign plan about festive garden gnomes.",
                                EndDate = new DateTime(2005, 12, 12),
                                EntryActivityId = entryActivityGuid
                        };

                        // Email activity type
                        // THIS IS THE ACTIVITY TYPE DESCRIPTOR ID
                        Guid secondActivityTypeGuid = Guid.Parse("62632708-110a-46ad-995d-6a4a709e90d4");

                        var emailActivity = new AutomationActivityDefinition
                        {
                                Id = secondActivityGuid, // ID of this instance
                                ActivityTypeId = secondActivityTypeGuid,
                        };

                        // Snail mail activity
                        // THIS IS THE ACTIVITY TYPE DESCRIPTOR ID
                        Guid thirdActivityTypeGuid = Guid.Parse("A2632708-F10a-46ad-995d-6a4a709e90d4");

                        var snailmailActivity = new AutomationActivityDefinition
                        {
                                Id = secondActivityGuid, // ID of this instance
                                ActivityTypeId = secondActivityTypeGuid,
                        };

                        // Entry activity
                        // THIS IS THE ACTIVITY TYPE DESCRIPTOR ID
                        Guid activityTypeGuid = Guid.Parse("56632708-510a-46fd-995d-6a4a709e90d4");

                        var firstActivity = new AutomationActivityDefinition
                        {
                                Id = entryActivityGuid, // ID of this instance
                                ActivityTypeId = activityTypeGuid,
                                Paths =
                                {
                                        {  "default", emailActivity.Id },
                                        { "snailMail", snailmailActivity.Id }

                                }
                        };

                        plan.AddActivity(emailActivity);
                        plan.AddActivity(emailActivity);
                        plan.AddActivity(firstActivity);
                }
        }
}

Activity types

Each activity references an activity type. Activity types determine the logic that is executed when a contact is enrolled in an activity. Activity types are classes that are deployed to the automation engine alongside some configuration. Each activity type also has an activity type descriptor item that includes all the things Emma will need - such as the activity type name, description, and the parameters that the activity accepts.

The ID of the activity type descriptor item is what you should use as your ActivityTypeId. Find out more about activity types and how to create them

Note

A single activity type can be used multiple times within the same plan or across multiple plans.

Activity parameters

Activity types can define parameters that you set per instance of an activity. Parameters are represented by simple properties in the activity type class and matching items under the descriptor item:

The example below assumes that the class associated with activity type ID {56632708-510a-46fd-995d-6a4a709e90d4} has a FromAddress property. When this plan is executed, the specified value will be used:

RequestResponse

var snailmailActivity = new AutomationActivityDefinition
{
        Id = Guid.NewGuid(), // ID of this instance
        ActivityTypeId = Guid.Parse("56632708-510a-46fd-995d-6a4a709e90d4"), // Activity type descriptor ID
        Parameters =
        {
                { "FromAddress", "1234 Sitecore, Sitecore World, Denmark" }
        }
};

Saving an Automation Plan

Once you have defined a plan you may save it by calling the SaveAsync() method on the definition manager.

RequestResponse

AutomationPlanDefinition plan = CreatePlan();

AutomationPlanDefinitionManager manager = ServiceLocator.ServiceProvider.GetDefinitionManagerFactory().GetDefinitionManager<IAutomationPlanDefinition>();

manager.SaveAsync(plan);

You can also optionally activate the plan during save by passing true to the second parameter of the SaveAsync() method:

RequestResponse

manager.SaveAsync(plan, true);

Update an existing Automation Plan

To update an existing plan definition, just call the save method again.

RequestResponse

AutomationPlanDefinition plan = CreatePlan();
AutomationPlanDefinitionManager manager = ServiceLocator.ServiceProvider.GetDefinitionManagerFactory().GetDefinitionManager<IAutomationPlanDefinition>();

// Save plan so it exists
manager.SaveAsync(plan);

// Make updates to plan
plan.ReentryMode = ReentryMode.None;

// To update, simply call save again.
manager.SaveAsync(plan);

A more common scenario would be to first retrieve a plan (see below), make updates to the model then call save with the updated plan.

Activate an Automation Plan

Plans must be activated before they are available for use outside of management, such as being “published” out to the Reference Data Service.

Plans can be activated when they’re saved by passing true to the activate (second) parameter of the SaveAsync() method:

RequestResponse

manager.SaveAsync(plan, true);

Plans can also be activated without calling save, using the ActivateAsync() method:

RequestResponse

manager.ActivateAsync(planId);

The ActivateAsync() method takes the ID of the plan and does not require the plan definition model.

Delete an Automation Plan

To delete a plan, use the Delete() method on the manager. Individual cultures cannot be deleted from the definition, only the entire definition. The culture provided to the method call should be either null (default value) or CultureInfo.InvariantCulture.

RequestResponse

manager.Delete(planId);

Retrieve an Automation Plan

A single plan can be retrieved by its ID using one of the Get() methods on the manager.

RequestResponse

IAutomationPlanDefinition planId = Constants.MyPlanId; // Ensure this is the ID of an existing plan

// Get by ID and culture. Will get the latest active version
IAutomationPlanDefinition plan = manager.Get(planId, new CultureInfo("da"));

// Get by ID and culture. Will get the latest version, including if the version is inactive
IAutomationPlanDefinition plan = manager.Get(planId, new CultureInfo("da"), true);

// Get a specific version by ID, culture and version number
IAutomationPlanDefinition plan = manager.Get(planId, new CultureInfo("da"), 3);

Retrieve an automation plan by its alias

You can also retrieve an automation plan by its alias:

RequestResponse

CultureInfo planCulture = new CultureInfo("fr-fr");
var planDefinitionByAlias = definitionManager.GetByAlias("My alias", planCulture);

Retrieve All Automation Plans

The GetAll() method can be used to get all plans from the manager. As there may be a large number of definitions, this method supports paging. The return value is a single page of results.

RequestResponse

// Get All with defaults which will be first page, page size 20, latest active versions only
ResultSet<DefinitionResult<IAutomationPlanDefinition>> plans = manager.GetAll(new CultureInfo("da"), new RetrievalParameters<IAutomationPlanDefinition, string>());

// Get page 2
ResultSet<DefinitionResult<IAutomationPlanDefinition>> page2Plans = manager.GetAll(new CultureInfo("da"), new RetrievalParameters<IAutomationPlanDefinition, string>(pageNumber: 2));

// Include inactive versions
ResultSet<DefinitionResult<IAutomationPlanDefinition>> page1AllPlans = manager.GetAll(new CultureInfo("da"), new RetrievalParameters<IAutomationPlanDefinition, string>(), true);

To access the results, use the DataPage property of the result.

RequestResponse

IAutomationPlanDefinition plan = page1AllPlans.DataPage.ElementAt(0);

The result also includes properties to expose the total number of definitions and the current page index and page size.

RequestResponse

long totalDefinitionCount = page1AllPlans.Total;
int pageNumber = page1AllPlans.PageNumber;
int pageSize = page1AllPlans.Count;