Manage marketing definitions programmatically

Current version: 8.2

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:

  1. Add the following project references:

    • Sitecore.Kernel

    • Sitecore.Marketing

    • Sitecore.Marketing.Core

  2. 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:

    RequestResponse
            // 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:

  1. Adapt the following code sample:

    RequestResponse
    // 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>();
            }
  2. 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:

    RequestResponse
    //// 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:

    RequestResponse
    // 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>();
            }

Do you have some feedback for us?

If you have suggestions for improving this article,