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

Version: 8.0

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

Create a Data Exchange Framework tenant
Create a value accessor
Create a pipeline
Create value readers
Create a pipeline context builder
Create a Tenant Service Endpoint
Add a Trigger DEF Sync process to an Engagement Plan

Create a Data Exchange Framework tenant

The tenant is a container for the settings that must be configured for the service.

To create a tenant:

In Sitecore, open the Content Editor and navigate to /sitecore/system/Data Exchange.
On the Folder tab, click Empty Data Exchange Tenant to create a new tenant.
Select the created tenant. In the ribbon, in the Data Exchange SDK tab, in the Tenants group, click Upgrade Tenant.
In the Upgrade Tenant dialog, in the Instruction Set field, select Tenant Service.

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:

RequestResponse

<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>

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:

RequestResponse

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

Server	Topology	File
Content management	all	`App_Config\connectionstrings.config`
Marketing automation	XP0	`<SC_xConnect>\App_Data\jobs\continuous\AutomationEngine\App_config\connectionstrings.config`
Marketing automation	XP1	`<SC_marketingAutomation>\App_Data\jobs\continuous\AutomationEngine\App_config\connectionstrings.config`

For Sitecore scaled deployment (XP1), in the MA connectionstring.config file, add strings for xconnect.search and xconnect.search.certificate. You can copy the values from the CM connectionstrings.config file.

Create a value accessor

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.

To create a value accessor:

Navigate to <tenant>/Data Access/Value Readers/Common.
On the Folder tab, click JToken Value from JObject Value Reader to create an item. Name it Identifier JToken from Contact JObject.
In the Convertible Type field, select String. In the Json Path field, enter $.Identifiers[1].Identifier.
Save the changes.
Navigate to <tenant>/Data Access/Value Accessors/Common.
On the Folder tab, click Value Accessor to create an Identifier Value Accessor.
In the Value Reader field, click the Identifier JToken from Contact JObject object that you created.
Save the changes.

Create a pipeline

To create a pipeline:

Navigate to your <tenant>/Pipelines.
On the Folder tab, click Pipeline to create a new item. Name it, for example, MA Action Testing Pipeline.
Select the pipeline. On the Folder tab, click Write to Log Pipeline Step to create a new pipeline step.
Select the new pipeline step and configure the Identifier Value Accesor value accessor you created previously.
Save the changes.

Create value readers

To create the necessary value readers:

Navigate to <tenant>/Data Access/Value Readers/Common/.
On the Folder tab, click JObject from HttpRequest Content Value Reader to create a new item. Name it, for example, JObject from HttpRequest Content.
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.
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.
In the Storage Location field, click Source. Save the changes.

Create a pipeline context builder

To create a context builder:

Navigate to <your tenant>/Tenant Service Settings/Pipeline Context Builders.
On the Folder tab, click Pipeline Context Plugin Builder to create a new item.
Set the Value Transformer field to JObject from HttpRequest Content.
Set the Plugin Readers field to Synchronization Settings Plugin Value Reader.
Save the changes.

Create a Tenant Service Endpoint

To create an endpoint:

Navigate to <your tenant>/Tenant Service Endpoints.
On the Folder tab, click Pipeline Tenant Service Endpoint to create a new item. Name it, for example, MA Action Endpoint.

Configure the endpoint with the following parameters:

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

Select the Enabled check box. Save the changes.

Add a Trigger DEF Sync process to an Engagement Plan

To activate the Marketing Automation, you must connect the Tenant Service to an engagement plan.

Note

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

To create a connection:

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:

RequestResponse

<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>

On the Sitecore Launchpad, open the Marketing Automation application.
Create . You can also use an existing campaign, 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.
From the toolbox, drag a Trigger DEF Sync Process marketing action onto the campaign.
Click the Trigger DEF Sync Process action. In the Select a tenant service drop-down menu, select a Tenant Service from the list of available services. In the Select a tenant service endpoint drop-down menu, click MA Action Endpoint.

Note

You can configure the list of available Tenant Services in the Sitecore.DataExchange.MarketingAutomation.Client.config configuration file.
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:
RequestResponse
```
2019-09-05 10:49:06.538 +08:00 [Information] 10:49 AM : 6638f579-5e10-47c9-bef6-3bf2d2a1a240
```

Do you have some feedback for us?

If you have suggestions for improving this article,