Walkthrough: Setting up a Marketing Automation action in Data Exchange Framework

Abstract

Example of how to set up a Marketing Automation (MA) action.

This walkthrough shows you an example of how to set up a Marketing Automation (MA) action. It describes how to:

The tenant is a container for the settings that need to be configured for the service. To create a tenant:

  1. In Sitecore, open the Content Editor and navigate to /sitecore/system/Data Exchange.

  2. On the Folder tab, click Empty Data Exchange Tenant to create a new tenant.

  3. Select the created tenant and click on the Data Exchange SDK tab in the top menu bar.

  4. Click on Upgrade Tenant. In the Instruction Set field, click the Tenant Service option.

  5. Make a note of the tenant ID. Add the tenant ID, host, and credentials in the <tenant service>\App_Config\ConnectionStrings.config file, in the connection string called Sitecore. For example:

    <connectionStrings>
        <add name="sitecore" connectionString="database=master;tenant id={841B0E94-4348-494D-B32D-CA5E94F26ACC};host=my-sitecore;password=b;user name=sitecore\admin;timeout=20" />
    </connectionStrings>
  6. On your Sitecore Content Management and Marketing Automation Service servers, in the App_Config\connectionstring.config file, make sure you have a connection string for the tenant web service associated with the tenant. For example:

    <xmlversion="1.0" encoding="utf-8">
    <connectionStrings>
        <add name="my-tenant" connectionString="https://my-tenant.service"/>
    </connectionStrings>

    This table shows where you must add the connection string:

When an MA event triggers the Data Exchange Framework Action Plugin for MA it sends a request to the Tenant Service, which extracts the message body from the request. The contact is serialized as a JSON object.

You must create a value accessor that can access the first identifier in the serialized xConnect contact.

  1. Navigate to <tenant>/Data Access/Value Readers/Common.

  2. On the Folder tab, click JToken Value from JObject Value Reader to create an item. Name it Identifier JToken from Contact JObject.

  3. In the Convertible Type field, select String. In the Json Path field, enter $.Identifiers[1].Identifier.

    Settings for Identifier JToken from Contact JObject.
  4. Save the changes.

  5. Navigate to <tenant>/Data Access/Value Accessors/Common.

  6. On the Folder tab, click Value Accessor to create an Identifier Value Accessor.

  7. In the Value Reader field, click the Identifier JToken from Contact JObject object that you created.

  8. Save the changes.

To create a pipeline:

  1. Navigate to your <tenant>/Pipelines.

  2. On the Folder tab, click Pipeline to create a new item. Name it, for example, MA Action Testing Pipeline.

  3. Select the pipeline. On the Folder tab, click Write to Log Pipeline Step to create a new pipeline step.

  4. Select the new pipeline step and configure the Identifier Value Accesor value accessor you created previously.

    Accessors for pipeline step.
  5. Save the changes.

To create the necessary value readers:

  1. Navigate to <tenant>/Data Access/Value Readers/Common/.

  2. On the Folder tab, click JObject from HttpRequest Content Value Reader to create a new item. Name it, for example, JObject from HttpRequest Content.

  3. In <tenant>/Data Access/Value Readers/Common/, on the Folder tab, click Raw Value Reader to create a new item. Name it, for example, Raw Value Reader.

  4. In <tenant>/Data Access/Value Readers/Common/, on the Folder tab, click Synchronization Settings Plugin Value Reader to create a new item. Name it, for example, Synchronization Settings Plugin Value Reader.

  5. In the Storage Location field, click Source. Save the changes.

    Settings for Value Reader.

To create a context builder:

  1. Navigate to <your tenant>/Tenant Service Settings/Pipeline Context Builders.

  2. On the Folder tab, click Pipeline Context Plugin Builder to create a new item.

  3. Set the Value Transformer field to JObject from HttpRequest Content.

  4. Set the Plugin Readers field to Synchronization Settings Plugin Value Reader.

  5. Save the changes.

To create an endpoint:

  1. Navigate to <your tenant>/Tenant Service Endpoints.

  2. On the Folder tab, click Pipeline Tenant Service Endpoint to create a new item. Name it, for example, MA Action Endpoint.

  3. Configure the endpoint with the parameters in this table:

    Parameter

    Content

    Request Value Reader

    Value Readers/Common/Raw Value Reader

    Pipeline Context Builder

    Pipeline Context Builders/Pipeline Context Plugin Builder

    Pipeline

    Pipelines/MA Action Testing Pipeline

  4. Select the Enabled checkbox. Save the changes.

In order to activate the Marketing Automation, you must connect the tenant service to an engagement plan.

Note

This section assumes that you are familiar with Marketing Automation and Engagement Plans.

To create a connection:

  1. On your CM Instance, open the <sitename>\App_Config\Sitecore\MarketingAutomation\Sitecore.DataExchange.MarketingAutomation.Client.config file. Add the name of the Tenant Service in the <tenantServiceConnectionRepository>/<tenantServices> node. For example:

    <dataExchange>
        <tenantServices>
            <marketingAutomation>
                <tenantServiceConnectionRepository type="Sitecore.DataExchange.MarketingAutomation.Activity.Repositories.TenantServiceConnectionRepository, Sitecore.DataExchange.MarketingAutomation.Activity">
                    <tenantServices hint="list:AddService">
                       <tenantService>my-sitecore</tenantService>            
                    </tenantServices>
                </tenantServiceConnectionRepository>
            </marketingAutomation>
        </tenantServices>
    </dataExchange>
  2. In Sitecore, in Launchpad, open the Marketing Automation application.

  3. Create a new campaign. You can also use an existing campagin, if you already have one. Configure the start point to trigger the campaign when a customer visits a specific page or when a general PageView event happens.

  4. From the toolbox, drag and drop a Trigger DEF Sync Process marketing action to the campaign.

    Add marketing action to campaign.
  5. Click the Trigger DEF Sync Process action. In the first dropdown menu, select a tenant service from the list of available services. In the second dropdown menu, select MA Action Service.

    Configure Trigger DEF Sync Process action.

    Note

    You can configure the list of available Tenant Services in the Sitecore.DataExchange.MarketingAutomation.Client.config configuration file.

  6. To test the service, navigate to the published Sitecore site in a browser, enroll a contact to the new campaign, and wait until the client session ends. Open the latest Tenant Service log file. If the service is working, it contains a message with a contact identifier, for example:

    2019-09-05 10:49:06.538 +08:00 [Information] 10:49 AM : 6638f579-5e10-47c9-bef6-3bf2d2a1a240