Automation plans
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 ifReentryMode
is set toAutomationPlanReentryMode.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.
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 theAutomationActivityDefinition
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
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;