Manage marketing definitions programmatically

Version:

You can use the Marketing Operations API definition manager to manage your marketing definitions data, such as campaigns, goals, outcomes, funnels, and assets.

This topic includes code samples and describes how to:

Prepare Visual Studio

To manage marketing definitions programmatically, in your Microsoft Visual Studio project:

Add the following project references:
- Sitecore.Kernel
- Sitecore.Marketing
- Sitecore.Marketing.Core
Add the following namespaces:
- using System.Globalization;
- using Sitecore.Marketing.Definitions;
- using Sitecore.Marketing.Definitions.Campaigns;
- using Sitecore.Data;
- using Sitecore.Marketing.Core;

Retrieve a marketing definition

If you are creating custom applications that do not have direct access to the Sitecore client UI, you can use the Marketing Operations API to retrieve marketing definitions data programmatically. For example, to customize Sitecore applications, such as the Experience Profile (xFile) or Experience Analytics reports, or when creating mobile applications. By default, the xFile only displays some basic information about recently triggered campaigns and you can retrieve more data using the Marketing Operations API.

To retrieve a marketing definition item, for example, a campaign definition item name, description, and taxonomic classification, adapt the following code sample:

        // Get a campaign
        public void GetCampaignActivityExample(ID campaignActivityId, CultureInfo 
        campaignActivityCulture)
        {
            // Retrieve the definition manager associated with the ICampaignActivityDefinition
            var manager = GetDefinitionManager();
            // Call Get() to get concrete campaign by ID and culture
            var campaignActivityDefinition = manager.Get(campaignActivityId, 
            campaignActivityCulture);
            var name = campaignActivityDefinition.Name;
            var description = campaignActivityDefinition.Description;
            var classification = campaignActivityDefinition.Classifications;
            var startDate = campaignActivityDefinition.StartDate;
            var endDate = campaignActivityDefinition.EndDate;
            var lastModifiedDate = campaignActivityDefinition.LastModifiedDate;
            // GetAll() allows to get all campaigns with specified culture
            ResultSet<DefinitionResult<ICampaignActivityDefinition>> allCampaigns = 
            manager.GetAll(CultureInfo.InvariantCulture);
            long numberOfCampaigns = allCampaigns.Total;
            foreach (var campaign in allCampaigns.DataPage)
            {
                name = campaignActivityDefinition.Name;
                description = campaignActivityDefinition.Description;
                classification = campaignActivityDefinition.Classifications;
                startDate = campaignActivityDefinition.StartDate;
                endDate = campaignActivityDefinition.EndDate;
                lastModifiedDate = campaignActivityDefinition.LastModifiedDate;
            }
        }
        [NotNull]
        private static IDefinitionManager<ICampaignActivityDefinition> GetDefinitionManager()
        {
            return 
        DefinitionManagerFactory.Default.GetDefinitionManager<ICampaignActivityDefinition>();
        }

Note

The Get method of the definition manager returns null if the definition cannot be found. This can happen if the definition has been removed, or when the definition has not been pushed to the environment where the definition is being retrieved.

Create a marketing definition

If you are creating custom applications that do not have direct access to the Sitecore client UI, create a new campaign definition item using the Marketing Operations API marketing definition manager.

To create a marketing definition:

Adapt the following code sample:

// Create a campaign
        public async Task CreateCampaignActivityExample()
        {
            ID campaignActivityId = ID.NewID; // Campaign activity ID
            CultureInfo campaignActivityCulture = new CultureInfo("es"); // Campaign activity 
            culture
            string campaignName = "Newly created campaign"; // Campaign activity name
            DateTime creationDate = DateTime.UtcNow; // Campaign activity creation date
            string createdBy = "sitecore\admin"; // Campaign activity creator
            // Retrieve the definition manager associated with the ICampaignActivityDefinition
            var manager = GetDefinitionManager();
            // Call SaveAsync() method with the list of parameters to create, save and deploy the 
            definition
            Task saveTask = manager.SaveAsync(new CampaignActivityDefinition(campaignActivityId, 
            campaignActivityCulture, campaignName, creationDate, createdBy), activate: true);
            await saveTask; //potentially it's a long-running task as it may involve a number of 
            retries of deploy, publish, index update operations
        }
        [NotNull]
        private static IDefinitionManager<ICampaignActivityDefinition> GetDefinitionManager()
        {
            return    
        DefinitionManagerFactory.Default.GetDefinitionManager<ICampaignActivityDefinition>();
        }

To activate a marketing definition, set the last parameter of the SaveAsync method to true.

When you activate a marketing definition:
- The marketing definition is saved to the master database, published to the web database, and deployed to the reporting database.
- The search indexes are updated (this applies to campaigns, assets, and funnels).
Note

If you do not want to activate a marketing definition, set this parameter to false. The marketing definition is only saved to the master database.

This behavior is configurable and can be changed by modifying the campaign/definitionManager/config/activationFeed section in the Sitecore.Marketing.config file.

Search marketing definitions

You can use the Marketing Operations API to search for marketing definitions programmatically, for example, a campaign definition item. The search functionality only applies to campaigns, assets, and funnels.

To search marketing definitions, adapt the following code sample:

//// Search for a campaign
        public void SearchForCampaignActivityExample()
        {
            // Retrieve the definition manager associated with the ICampaignActivityDefinition
            var manager = GetDefinitionManager();
            // Search active campaigns by name
            ResultSet<DefinitionResult<ICampaignActivityDefinition>> searchResults = 
            manager.Search(
                new SearchParameters<ICampaignActivityDefinition, string>(
                    c => (c.Name == "My campaign") && c.IsActive,
                    c => c.Name,
                    1,
                    10));
            long totalResuls = searchResults.Total;
            ICampaignActivityDefinition campaignDefinition;
            foreach (var result in searchResults.DataPage)
            {
                campaignDefinition = result.Data;
            }
        }
        [NotNull]
        private static IDefinitionManager<ICampaignActivityDefinition> GetDefinitionManager()
        {
            return 
        DefinitionManagerFactory.Default.GetDefinitionManager<ICampaignActivityDefinition>();
        }

Delete a marketing definition

When you delete a marketing definition, for example, a campaign, it is deactivated and removed from the master, web, and reporting databases. It is also removed from the search indexes. This is the default behavior that applies to campaigns, assets, and funnels. You can configure this behavior by patching the <deleteCampaign> pipeline.

To delete a marketing definition item, adapt the following code sample:

// Delete campaign
        public void DeleteCampaignActivityExample(ID campaignActivityId)
        {
            // Retrieve the definition manager associated with the ICampaignActivityDefinition
            var manager = GetDefinitionManager();
            // Delete campaign activity
            manager.Delete(campaignActivityId);
        }
        [NotNull]
        private static IDefinitionManager<ICampaignActivityDefinition> GetDefinitionManager()
        {
            return 
        DefinitionManagerFactory.Default.GetDefinitionManager<ICampaignActivityDefinition>();
        }

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