Definition managers

Automation plans

Version:

Automation plan definitions are managed by the Sitecore.Marketing.Definitions.AutomationPlans.AutomationPlanDefinitionManager class.

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:

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:

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:

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

Plan entry schedule

You define a an enrollment schedule for a specific segment of contacts. For example, you might choose to enroll all new contacts in a plan for new users every hour.

The following example sets the PlanEntrySchedule property to a DailySchedule which runs at a specified time each day. The plan targets an existing contact segment with an ID of {2546482E-887A-4CAB-A403-AD9C326FFDA5}.

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

Guid planId = Guid.NewGuid();

AutomationPlanDefinition plan = new AutomationPlanDefinition(planId, "Plan item name" CultureInfo.InvariantCulture, "Welcome new user plan", DateTime.UtcNow, "sitecore\\emma")
{
        ReentryMode = AutomationPlanReentryMode.Multiple,
        ContextKeyFactoryType = "MyFactory, MyAssembly", // Only needed if ReentryMode is set to Multiple
        Description = "A campaign plan for brand new users.",
        EndDate = new DateTime(2040, 12, 12),
        PlanEntrySchedule = new List<Schedule> {                    
            new DailySchedule {                        
                TimeOfDay = new TimeSpan(1,0,0)
            },
        ScheduledContactListId = new Guid("2546482E-887A-4CAB-A403-AD9C326FFDA5");
};

There are four possible plan schedules:

DailySchedule - runs at a specific time each day.
WeeklySchedule - runs at a specific time on specific days of the week (such as Mondays and Fridays).
SameDayEachMonthSchedule - runs at a specific time on specific days of the month (such as the 1st and 22nd).
WeeklyDayEachMonthSchedule - runs once per month at a specific time on a specific day of the week (such as every 2nd Friday). Specify -1 to schedule enrollment for the last week of the month.

Note

You can assign multiple schedules to a single plan. However, the Marketing Automation user interface does not support editing multiple schedules - only deleting them.

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.

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:

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.

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:

manager.SaveAsync(plan, true);

Update an existing Automation Plan

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

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:

manager.SaveAsync(plan, true);

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

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.

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.

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:

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.

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

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.

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

If you have suggestions for improving this article, let us know!