Definition managers

Goals

Version:

Goal definitions are managed by the Sitecore.Marketing.Definitions.Goals.GoalDefinitionManager class.

Note

Goals are specialized events. IGoalDefinition inherits IEventDefinition.

Accessing the GoalDefinitionManager

The GoalDefinitionManager is available from the Sitecore DI container. It is preferable to include a parameter of type DefinitionManagerBase<IGoalDefinition, GoalDefinitionRecord> 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<IGoalDefinition, GoalDefinitionRecord> goalDefinitionManager)
{
        ...
}

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;


namespace Documentation
{
        public class DefineAGoal
        {
                public void Example()
                {
                        var goalDefinitionManager = ServiceLocator.ServiceProvider.GetDefinitionManagerFactory().GetDefinitionManager<Sitecore.Marketing.Definitions.Goals.IGoalDefinition>();
                }
        }
}

Defining a goal

A goal is defined using types from the Sitecore.Marketing.Definitions.Goals.Model namespace.

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

namespace Documentation
{
        public class DefineAGoal
        {
                public void Example()
                {
                        var goalDefinitionManager = ServiceLocator.ServiceProvider.GetDefinitionManagerFactory().GetDefinitionManager<Sitecore.Marketing.Definitions.Goals.IGoalDefinition>();

                        Guid goalId = Guid.NewGuid(); // Goal ID
                        CultureInfo goalCulture = new CultureInfo("es"); // Goal culture
                        string goalName = "Newly created goal"; // Goal name
                        DateTime creationDate = DateTime.UtcNow; // Goal creation date
                        string createdBy = "sitecore\admin"; // Goal creator

                        Sitecore.Marketing.Definitions.Goals.GoalDefinition goal = new Sitecore.Marketing.Definitions.Goals.GoalDefinition(goalId, "Goal item name", goalCulture, goalName, creationDate, createdBy);

                        goal.ShowInXfileAsLatestEvent = true;
                        goal.ShowInXfileEventsList = true;
                        goal.EngagementValuePoints = 20;

                        goal.IsSystem = false; // Note: This property might be removed
                        goal.IsLiveEvent = false;
                }
        }
}

Live events

The IsLiveEvent property is part of the base EventDefinition class and is used by Marketing Automation to determine if an event should be processed immediately rather than on session end. Read more about live event processing.

Saving a goal

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

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

namespace Documentation
{
        public class SaveAGoal
        {
                public void Example()
                {
                        var goalDefinitionManager = ServiceLocator.ServiceProvider.GetDefinitionManagerFactory().GetDefinitionManager<Sitecore.Marketing.Definitions.Goals.IGoalDefinition>();

                        Guid goalId = Guid.NewGuid(); // Goal ID
                        CultureInfo goalCulture = new CultureInfo("es"); // Goal culture
                        string goalName = "Download Brochure"; // Goal name
                        DateTime creationDate = DateTime.UtcNow; // Goal creation date
                        string createdBy = "sitecore\admin"; // Goal creator

                        Sitecore.Marketing.Definitions.Goals.GoalDefinition goal = new Sitecore.Marketing.Definitions.Goals.GoalDefinition(goalId, "Goal item name", goalCulture, goalName, creationDate, createdBy);

                        goalDefinitionManager.SaveAsync(goal);
                }
        }
}

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

manager.SaveAsync(goal, true);

Activating a goal

Goals must be activated before they are available for use outside of management. Goals can be activated when they’re saved by passing true to the activate (second) parameter of the SaveAsync() method:

manager.SaveAsync(goal, true);

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

manager.ActivateAsync(goalId);

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

Deleting a goal

To delete a goal, 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(goalId);

Retrieve a goal

A single goal can be retrieved by it’s ID using one of the Get() methods on the manager.

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

namespace Documentation
{
        public class GetAGoal
        {
                public void Example()
                {
                        var goalDefinitionManager = ServiceLocator.ServiceProvider.GetDefinitionManagerFactory().GetDefinitionManager<Sitecore.Marketing.Definitions.Goals.IGoalDefinition>();

                        Guid goalId = Guid.NewGuid(); // Ensure this is the ID of an existing goal

                        // Get by ID and culture. Will get the latest active version
                        Sitecore.Marketing.Definitions.Goals.IGoalDefinition goalOne = goalDefinitionManager.Get(goalId, new CultureInfo("da"));

                        // Get by ID and culture. Will get the latest version, including if the version is inactive
                        Sitecore.Marketing.Definitions.Goals.IGoalDefinition goalWithInactive = manager.Get(goalId, new CultureInfo("da"), true);
                }
        }
}

Retrieve a goal by its alias

You can also retrieve a goal by its alias:

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

Update an existing goal

To update an existing goal definition, retrieve the goal by ID, edit the goal

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

namespace Documentation
{
        public class UpdateAGoal
        {
                public void Example()
                {
                        var goalDefinitionManager = ServiceLocator.ServiceProvider.GetDefinitionManagerFactory().GetDefinitionManager<Sitecore.Marketing.Definitions.Goals.IGoalDefinition>();

                        Guid goalId = Guid.NewGuid(); // Ensure this is the ID of an existing goal

                        // Get by ID and culture. Will get the latest active version
                        Sitecore.Marketing.Definitions.Goals.IGoalDefinition goal = goalDefinitionManager.Get(goalId, new CultureInfo("da"));

                        // Make updates to goal
                        goal.Name = "Updated name";

                        // Save to update
                        goalDefinitionManager.SaveAsync(goal);
                }
        }
}

Retrieving all goals

The GetAll() method can be used to get all goals 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.

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

namespace Documentation
{
        public class GetAllGoals
        {
                public void Example()
                {
                        var goalDefinitionManager = ServiceLocator.ServiceProvider.GetDefinitionManagerFactory().GetDefinitionManager<Sitecore.Marketing.Definitions.Goals.IGoalDefinition>();

                        // Get All with defaults which will be first page, page size 20, latest active versions only
                        Sitecore.Marketing.Core.ResultSet<DefinitionResult<Sitecore.Marketing.Definitions.Goals.IGoalDefinition>> goals = goalDefinitionManager.GetAll(new CultureInfo("da"), new RetrievalParameters<Sitecore.Marketing.Definitions.Goals.IGoalDefinition, string>());

                        // Get page 2
                        Sitecore.Marketing.Core.ResultSet<DefinitionResult<Sitecore.Marketing.Definitions.Goals.IGoalDefinition>> page2Goals = goalDefinitionManager.GetAll(new CultureInfo("da"), new RetrievalParameters<Sitecore.Marketing.Definitions.Goals.IGoalDefinition, string>(pageNumber: 2));

                        // Include inactive versions
                        Sitecore.Marketing.Core.ResultSet<DefinitionResult<Sitecore.Marketing.Definitions.Goals.IGoalDefinition>> page1Goals = goalDefinitionManager.GetAll(new CultureInfo("da"), new RetrievalParameters<Sitecore.Marketing.Definitions.Goals.IGoalDefinition, string>(), true);
                }
        }
}

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

IGoalDefinition goal = page1Goals.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 = page1Goals.Total;
int pageNumber = page1Goals.PageNumber;
int pageSize = page1Goals.Count;

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