Marketing Automation Operations API

Abstract

How to use the Marketing Automation Operations API to execute specific operations such as enrolling contacts, registering events, or seeding contacts into a plan.

The Marketing Automation Operations API makes it possible to execute specific operations from outside the Marketing Automation Engine.

Accessing the Automation Operations API

Use the service locator to access IAutomationOperationsClient in a Sitecore context:

using Sitecore.DependencyInjection;
using Microsoft.Extensions.DependencyInjection;
using System;
using Sitecore.Xdb.MarketingAutomation.OperationsClient;
using Sitecore.Xdb.MarketingAutomation.Core.Requests;
using Sitecore.Xdb.MarketingAutomation.Core.Results;
using System.Collections.Generic;

namespace Documentation
{
    public class EnrollContact
    {
        public async void Example()
        {
            try
            {
                var operationsClient = ServiceLocator.ServiceProvider.GetService<IAutomationOperationsClient>();
            }
        }
    }
}

Operation results

Each operation accepts a collection of requests. The results of each operation invocation is a batch result. The batch result includes a property to indicate whether the entire batch was successful or whether one or more requests failed. It also holds the individual results for each request:

BatchRequestResult
        Success : bool // Indicates whether the entire batch succeeded
        Results : IReadOnlyCollection<TRequestResult> // The results of the request

The type of the result is determined by the operation.

Each individual operation result includes (at minimum) a property indicating whether the operation performed for the request was successful, and the original request. Providing the original request allows linking up the result to the request made from the client.

RequestResult
        Success : bool // Indicates whether the result is success
        Request : TRequest // The request the result is for

Operation priority

The Priority property of the request objects determine the processing priority of the request for operations that log the request into the work pool.

Note

The RegisterLiveEvent operation is the only operation which bypasses the pool. Priority is ignored for this operation.

Operations

Enroll contact in plan

Enrolls the provided contact directly into a plan and optionally directly into an activity within the plan. All operations on the operations client are asynchronous and batch requests, even if it is a batch of one.

Note

If the activity is missing from the request, the contact will be put into the entry activity of the plan.

Enrolling a contact in a single plan

The following example demonstrates how to enroll a contact in a single plan.

using Sitecore.DependencyInjection;
using Microsoft.Extensions.DependencyInjection;
using System;
using Sitecore.Xdb.MarketingAutomation.OperationsClient;
using Sitecore.Xdb.MarketingAutomation.Core.Requests;
using Sitecore.Xdb.MarketingAutomation.Core.Results;

namespace Documentation
{
    public class EnrollContact
    {
        public async void Example()
        {
            try
            {
                var operationsClient = ServiceLocator.ServiceProvider.GetService<IAutomationOperationsClient>();

                                    var contactXconnectId = Guid.Parse("{E7B756A1-3769-46F1-AE17-7B3A198F9290}");
                                    var planId = Guid.Parse("{19FDD3A5-DBC2-4947-BEB4-69732ADEB0D8}");
                var request = new EnrollmentRequest(contactXconnectId, planId); // Contact ID, Plan ID

                request.Priority = 1; // Optional
                request.ActivityId = Guid.Parse("{C5B87651-EE70-4684-BDD9-0B464B79476D}"); // Optional
                request.CustomValues.Add("test", "test"); // Optional

                BatchEnrollmentRequestResult result = await operationsClient.EnrollInPlanDirectAsync(new[]
                {
                                            request
                });
            }
            catch (Exception ex)
            {

            }
        }
    }
}

Enrolling a contact in multiple plans

The following example demonstrates how to enroll a contact in multiple plans at the same time.

using Sitecore.DependencyInjection;
using Microsoft.Extensions.DependencyInjection;
using System;
using Sitecore.Xdb.MarketingAutomation.OperationsClient;
using Sitecore.Xdb.MarketingAutomation.Core.Requests;
using Sitecore.Xdb.MarketingAutomation.Core.Results;

namespace Documentation
{
    public class EnrollContact
    {
        public async void Example()
        {
            try
            {
                var operationsClient = ServiceLocator.ServiceProvider.GetService<IAutomationOperationsClient>();

                                    var contactXconnectId = Guid.Parse("{E7B756A1-3769-46F1-AE17-7B3A198F9290}");
                                    var planId = Guid.Parse("{19FDD3A5-DBC2-4947-BEB4-69732ADEB0D8}");
                var request = new EnrollmentRequest(contactXconnectId, planId); // Contact ID, Plan ID

                request.Priority = 1;
                request.ActivityId = Guid.Parse("{C5B87651-EE70-4684-BDD9-0B464B79476D}"); // Optional
                request.CustomValues.Add("test", "test");

                                    var plan2Id = Guid.Parse("{8F5BCFED-606D-46BF-A5CD-6801AC07DC3F}");
                var secondRequest = new EnrollmentRequest(contactXconnectId, plan2Id); // Contact ID, Plan ID

                secondRequest.Priority = 9;
                secondRequest.ActivityId = Guid.Parse("{3DB8A71A-37D6-4BC7-9F48-980B176A2C43}");
                secondRequest.CustomValues.Add("test", "test");

                BatchEnrollmentRequestResult result = await operationsClient.EnrollInPlanDirectAsync(new[]
                {
                                            request,
                                            secondRequest
                });
            }
                            catch (Exception ex)
            {

            }
        }
    }
}

Enrollment request results

The following example demonstrates how to get the result of an entire batch of enrollment requests, and how to get additional information about each individual enrollment request.

using Sitecore.DependencyInjection;
using Microsoft.Extensions.DependencyInjection;
using System;
using Sitecore.Xdb.MarketingAutomation.OperationsClient;
using Sitecore.Xdb.MarketingAutomation.Core.Requests;
using Sitecore.Xdb.MarketingAutomation.Core.Results;
using System.Collections.Generic;

namespace Documentation
{
    public class EnrollContactResult
    {
        public async void Example()
        {
            try
            {
                var operationsClient = ServiceLocator.ServiceProvider.GetService<IAutomationOperationsClient>();

                BatchEnrollmentRequestResult result = await operationsClient.EnrollInPlanDirectAsync(new[]
                {
                    new EnrollmentRequest(Guid.NewGuid(), Guid.NewGuid())
                });

                IReadOnlyCollection<EnrollmentRequestResult> batchResults = result.Results;
                bool batchSucceeded = result.Success;

                foreach (EnrollmentRequestResult requestResult in result.Results)
                {
                    bool requestSucceeded = requestResult.Success;
                    EnrollmentRequest originalRequest = requestResult.Request;
                }
            }
            catch (Exception ex)
            {
                // Handle exception
            }

        }
    }
}

Register live event

The Operations API allows you to submit an event to the Marketing Automation Engine before that event has been submitted to xConnect. This feature is used by the tracker to submit events to the Marketing Automation Engine before the session has ended and event data has been submitted to xConnect.

Register a single live event

The following example demonstrates how to register a single live event:

using Sitecore.DependencyInjection;
using Microsoft.Extensions.DependencyInjection;
using System;
using Sitecore.Xdb.MarketingAutomation.OperationsClient;
using Sitecore.Xdb.MarketingAutomation.Core.Requests;
using Sitecore.Xdb.MarketingAutomation.Core.Results;
using Sitecore.XConnect;
using Sitecore.Xdb.MarketingAutomation.Core.Collections;
using Sitecore.Xdb.MarketingAutomation.Core.Pool;
using Sitecore.XConnect.Collection.Model;

namespace Documentation
{
    public class LiveEvent
    {
        public async void Example()
        {
            try
            {
                var operationsClient = ServiceLocator.ServiceProvider.GetService<IAutomationOperationsClient>();

                // Sample contact and interaction
                var contact = new Contact();
                Guid channelId = Guid.Parse("{E99C8E17-3C9C-4B10-AC69-6B1BAFAE0711}");
                string userAgent = "Sample User Agent";
                var interaction = new Interaction(new ContactReference(contact.Id.Value), InteractionInitiator.Brand, channelId, userAgent);

                // Sample event
                interaction.Events.Add(new SearchEvent(DateTime.UtcNow) { Keywords = "sitecore" });

                // Automation custom values
                var customValues = new CustomValuesDictionary() { { "test", "test" } };

                var liveEvent = new LiveEventData(contact.Id.Value, interaction, customValues);
                var liveEventRequest = new LiveEventRequest(contact.Id.Value, liveEvent) { Priority = 200 };

                // Live event submitted BEFORE INTERACTION IS SUBMITTED
                // This means that the Automation Engine can respond to an event before it is available in xConnect
                BatchLiveEventRequestResult result = await operationsClient.RegisterLiveEventAsync(new[]
                {
                    liveEventRequest
                });
            }
            catch (Exception ex)
            {
                // Handle exception
            }
        }
    }
}

Live event request results

The BatchLiveEventRequestResult makes a list of affected enrollments available via the UpdatedEnrollments property.

var contact = new Contact();
Guid channelId = Guid.Parse("{E99C8E17-3C9C-4B10-AC69-6B1BAFAE0711}");
string userAgent = "Sample User Agent";
var interaction = new Interaction(new ContactReference(contact.Id.Value), InteractionInitiator.Brand, channelId, userAgent);
var customValues = new CustomValuesDictionary() { { "test", "tst" } };

var eventData = new EventData(contact, interaction, customValues);

var liveEventRequest = new LiveEventRequest(contact.Id.Value, eventData);

BatchLiveEventRequestResult result = await operationsClient.RegisterLiveEventAsync(new[]
{
    liveEventRequest
});

IReadOnlyCollection<LiveEventRequestResult> batchResults = result.Results;
bool batchSucceeded = result.Success;

foreach (LiveEventRequestResult requestResult in result.Results)
{
    bool requestSucceeded = requestResult.Success;
    LiveEventRequest originalRequest = requestResult.Request;

    // Get list of enrollments updated by event
    IEnumerable<ActivityEnrollment> enrollments = requestResult.UpdatedEnrollments;

    // Get first activity enrollment
    var firstEnrollment = enrollments.FirstOrDefault();

    // Activity enrollment properties
    var attemptsToEnroll = firstEnrollment.Attempts;
    var entryDate = firstEnrollment.EntryDate;
    var timeoutDate = firstEnrollment.TimeoutDate;
}

Purge contact from plan

You can use the Operations API to remove a contact from a specific plan or from all plans.

Purge contact from specific plan

The following example demonstrates how to purge a contact from a specific plan:

using Sitecore.DependencyInjection;
using Microsoft.Extensions.DependencyInjection;
using System;
using Sitecore.Xdb.MarketingAutomation.OperationsClient;
using Sitecore.Xdb.MarketingAutomation.Core.Requests;
using System.Collections.Generic;

namespace Documentation
{
    public class SinglePlanPurge
    {
        public async void Example()
        {
            try
            {
                var operationsClient = ServiceLocator.ServiceProvider.GetService<IAutomationOperationsClient>();

                var contactId = Guid.Parse("{B65CB77F-0338-49C1-B6AF-1360C9560A17}");
                var planId = Guid.Parse("{3F894AC4-926F-4B26-A001-BEAB955C40F8}");

                var purgeRequest = new List<PurgeFromPlanRequest> { new PurgeFromPlanRequest(contactId, planId) };

                var result = await operationsClient.PurgeFromPlanAsync(purgeRequest);
            }
            catch (Exception ex)
            {
                // Handle exception
            }
        }
    }
}

Purge contact from all plans

The following example demonstrates how to purge a contact from all plans:

Warning

All work items currently in the pool for the contact will be also be removed.

using Sitecore.DependencyInjection;
using Microsoft.Extensions.DependencyInjection;
using System;
using Sitecore.Xdb.MarketingAutomation.OperationsClient;
using Sitecore.Xdb.MarketingAutomation.Core.Requests;
using System.Collections.Generic;

namespace Documentation
{
    public class AllPlanPurge
    {
        public async void Example()
        {
            try
            {
                var operationsClient = ServiceLocator.ServiceProvider.GetService<IAutomationOperationsClient>();

                var contactId = Guid.Parse("{B65CB77F-0338-49C1-B6AF-1360C9560A17}");
                var purgeRequest = new List<PurgeFromAllPlansRequest> { new PurgeFromAllPlansRequest(contactId) };

                var result = await operationsClient.PurgeFromAllPlansAsync(purgeRequest);
            }
            catch (Exception ex)
            {
                // Handle exception
            }
        }
    }
}