Sitecore 9: Marketing Automation API - enrolling contacts
In the previous posts we learned how to create custom action types. We created custom activity type and deployed it to Marketing Automation engine and Sitecore Marketing Automation UI. In order to use Marketing Automation Engine developers and marketers need to understand how contacts are enrolled in automation plans and get familiar with the corresponding API. In this post, we will learn how to enroll contact to automation plan programmatically using Operations API and how to use Marketing Automation Reporting API.
Sitecore documentation provides a great starting point to understand a number of scenarios when contact is enrolled in Automation plan.
Option 1: XdbContactEventWatcher xConnect service plugin detects contacts and interactions submitted to xConnect and creates a work item for Automation Pool. A number of pool workers are waiting to process each work item according to priority. Any interaction or change to the contact and its facets submitted using XConnectClient will be processed to marketing automation this way.
Option 2: A live event is registered using Marketing Automation Operations API. Both marketers and developers can make use of this feature. Developers can use Marketing Operations API to register a live event and set a higher priority for an individual event to be processed. Marketers can use Sitecore 9 newly introduced Is Live Event property of the event, goal and outcome definition item.
This feature is used by the Sitecore tracker to submit events to the Marketing Automation Engine before the session has ended and event data has been submitted to the Collection database. This way marketers can ensure events are evaluated in Marketing Automation plans immediately during the ongoing interaction.
Option 3: Finally contact can be enrolled in Automation plan programmatically again using Marketing Automation Operations API. Let's take a closer look at how developers can make use of it.
Let’s create a simple marketing automation plan where we will want to enroll contact directly to the Custom listener action bypassing the plan entry condition.
The following code snippet illustrates how to enroll contact to the specific activity.
private static void AddContactToPlan()
{
AutomationOperationsClient operationsClient = GetAutomationOperationsClient();
var contactXconnectId = Guid.Parse("{7861dfd4-b578-0000-0000-052854642e00}");
var planId = Guid.Parse("{4a85ddac-cc2f-47b1-a9d5-8972b3409b24}");
var request = new EnrollmentRequest(contactXconnectId, planId); // Contact ID, Plan ID
request.Priority = 1; // Optional
request.ActivityId = Guid.Parse("{c01b8533-f524-b384-5614-346f0b6a7544}"); // Optional
request.CustomValues.Add("test", "test"); // Optional
BatchEnrollmentRequestResult result = operationsClient.EnrollInPlanDirect(new[] { request });
}
So, what exactly ActivityId is? An automation plan contains a collection of activities. Activities are saved as a JSON on the plan definition item. Each activity in a plan defines legal paths from itself to the next activity.
Given that we know Custom Listener ActivityTypeID we can quickly find corresponding ActivityID that makes use of Custom Listener ActivityTypeID.
Alternatively, you can inspect Marketing Automation UI to find the underlying ActivityId.
In the above code snippet, we use AutomationOperationsClient.
If you run your code in the Sitecore context you can use the following code snippet to get its instance.
var operationsClient =
ServiceLocator.ServiceProvider.GetService<IAutomationOperationsClient>(();
However, if you are accessing Operations API outside of Sitecore you will need to instantiate operations client in a different way.
string XconnectUrl = ConfigurationManager.AppSettings["xconnect.url"];
ILogger<AutomationOperationsClient>( logger = LoggerFactory.CreateLogger<AutomationOperationsClient>();
var result = new AutomationOperationsClient(new Uri(XconnectUrl), null, null, logger);
Be sure to set web request certificate modifier in production environment.
We can immediately see enrollment request results in the Marketing Automation plan report and can even view contacts in the selected activity.
If you decide to enroll the same contact to another activity, such request will be registered OK, but enrollment processing will not work, and you will find the following error in AutomationEngine log: Failed to create activity enrollment Status code: "EnrollmentAlreadyExists".
When enrollment request is received by xConnect a new record will be created in AutomationPool table of the MarketingAutomation database, Automation Engine background worker will attempt to process new work item and update ActivityEnrollments table to save enrollment state. Statistics tables will also be updated to include information about such enrollment for reporting purposes.
Contact AutomationPlanEnrollmentCache facet will also be updated to include the information about activity and plan contact is enrolled. The following image illustrates the value of the FacetData field for the corresponding FacetKey in the ContactFacet table of the Collection database.
Note that custom values submitted along with enrollment request are saved here and you can make use of it in automation conditions, and any further business logic.
You can enroll contact in multiple automation plans and also remove the contact from automation plans using purge request.
In a similar way, you can instantiate Automation Reporting client and make use of Reporting API. All code snippets are available in the GitHub repository.
Fly high with Sitecore 9.
Read more on marketing automation and Sitecore 9:
- Creating Activity Type backend logic and definition item
- Deploying Activity Type to Sitecore UI and Marketing Automation engine
- Creating Activity Type UI and Editor
- Custom Marketing Automation Action - Introduction
- Marketing Automation - Repeated and concurrent contact enrollments
Do you need help with your Sitecore project?
