Skip to main content

Walkthrough: Installing SFMC Behavioral Data Exchange in Docker with the Tenant Service

Abstract

How install Salesforce Marketing Exchange Behavioral Data Exchange in a Docker container environment with the Tenant service.

To use the Activity for Marketing Automation and Sitecore Sync functionality in Sitecore Connect for Salesforce Marketing Cloud Behavioral Data Exchange (SFMCBDE), you must deploy a Tenant Service.

This walkthrough describes how to:

  • Prepare the installation files for the Tenant Service.

  • Build the Docker images for the Tenant Service.

To prepare the files you need for the installation:

  1. Complete the steps in Walkthrough: Preparing to install SFMC Behavioral Data Exchange in a container environment.

  2. Download the SFMCBDE-TS container deployment package from the Sitecore download page. Extract it to your workstation with the folder structure intact.

  3. Navigate to the folder into which you extracted the package. Navigate to the TenantService.SFMCBDE folder for the Windows version and topology you are using, for example, TenantService.SFMCBDE\compose\ltsc2019\xp1.

  4. Open the .env-example file in an editor. Copy all the variables to the clipboard.

  5. Go to the Sitecore container deployment folder on your local machine. Go to the folder for the Windows version and topology you are using, for example, compose\ltsc2019\xp1.

  6. Open the .env file in an editor, and paste in the variables from the .env-example file. Update the variables according to your installation. Save the .env file.

    Note

    After you create the tenant in Sitecore, you can update the TENANT_SERVICE_CONFIG_EXECUTE_URL variable in the .env file with the Tenant Service endpoint ID. When you do this, you must then redeploy the Tenant Service.

  7. From the TenantService.SFMCBDE\compose\<version>\<topology> folder, copy the tenant-service.override.yml file to the Sitecore container deployment compose\<version>\<topology> folder (where the docker.compose.yml file is).

When you have prepared the installation files and the Docker image files for the SFMCBDE roles, you must add Docker files for each Tenant Service role, and build the Docker images.

To build the images:

  1. In the module\cm folder, in the Dockerfile file, before the invoke-XdtTransform.ps1 command, add the following instructions:

    # Copy transformation file to update Tenant Service name into Sitecore.DataExchange.MarketingAutomation.Client.config
    COPY --from=sfmcbde \module\xdttransform\cm\transforms\App_Config\Sitecore\MarketingAutomation C:\transforms\role\App_Config\Sitecore\MarketingAutomation
    
    # Copy transformation file to add Tenant Service host name into web.config access control allow
    COPY --from=sfmcbde \module\xdttransform\cm\transforms\Web.config.xdt C:\transforms\role\Web.config.xdt
  2. In the module folder, create these subfolders:

    • tenantservice

    • cd

    • id

  3. In each subfolder, create a new file and name it Dockerfile.

  4. In the tenantservice folder, create a new subfolder and name it Config. In the Config subfolder, create a new file and name it Update-ConfigJson.ps1.

  5. In the Update-ConfigJson.ps1 file, enter the following code, and then save the file:

    param(
        [Parameter(Mandatory = $true)][string]$executeUrl
    )
    $configJsonPath = "./sync-activity/config.json";
    $jsonDepth = 20
    Write-Host "Start Updating config.json with $executeUrl"
     
    $snapshot = (Get-Content $configJsonPath | ConvertFrom-Json )
    $snapshot.arguments.execute.url = $executeUrl
    $snapshot.configurationArguments.publish.url = $executeUrl
     
    $snapshot | ConvertTo-Json -Depth $jsonDepth  | set-content $configJsonPath
    Write-Host "Done Updating config.json"

    Note

    This script updates the config.json file in the Tenant Service. It is run by the Dockerfile file for the cm image.

  6. In the tenantservice folder, in the Dockerfile file, enter the following instructions:

    # escape=`
    ARG BASE_IMAGE
    ARG SFMCBDE_IMAGE
    ARG TOOLING_IMAGE
    
    FROM ${SFMCBDE_IMAGE} as sfmcbde
    FROM ${TOOLING_IMAGE} as tooling
    FROM ${BASE_IMAGE}
    
    SHELL ["powershell", "-Command", "$ErrorActionPreference = 'Stop'; $ProgressPreference = 'SilentlyContinue';"]
    
    #Add tools from sitecore-docker-tools-assets
    COPY --from=tooling \tools\ C:\tools\
    
    # Add SFMCBDE module files for Tenant Service
    COPY --from=sfmcbde \module\tenantservice\content .\
    
    #Copy transformation files
    COPY --from=sfmcbde \module\xdttransform\tenantservice\transforms\ C:\transforms\role
    
    # Copy connection string updater script file to wwwroot folder
    # Add reference data connection strings
    # Add SFMC connection strings in Tenant Service connection strings
    RUN C:\tools\scripts\Invoke-XdtTransform.ps1 -Path C:\inetpub\wwwroot -XdtPath C:\transforms\role
    
    # Copy Update-ConfigJson.ps1 into scripts folder  
    COPY tenantservice/Config/Update-ConfigJson.ps1 C:\tools\scripts 
    ENTRYPOINT "C:\tools\scripts\Update-ConfigJson.ps1" "-executeUrl" "$($env:TenantService_SfmcJourney_ExecuteUrl)"; ` 
            C:\ServiceMonitor.exe w3svc; 
  7. In the cd folder, in the Dockerfile file, enter the following instructions:

    # escape=`
    
    ARG BASE_IMAGE
    ARG SFMCBDE_IMAGE
    
    FROM ${SFMCBDE_IMAGE} as sfmcbde
    FROM ${BASE_IMAGE}
    
    SHELL ["powershell", "-Command", "$ErrorActionPreference = 'Stop'; $ProgressPreference = 'SilentlyContinue';"]
    
    WORKDIR C:\inetpub\wwwroot
    
    # Add SFMCBDE config
    COPY --from=sfmcbde \module\cm\content\App_Config\Sitecore\DataExchange\SalesforceMarketingCloud .\App_Config\Sitecore\DataExchange\SalesforceMarketingCloud
    
    # Add SFMCBDE dll
    COPY --from=sfmcbde \module\cm\content\bin\Sitecore.DataExchange.XConnect.SalesforceMarketingCloud.dll .\bin
  8. In the id folder, in the Dockerfile file, enter the following instructions:

    # escape=`
    ARG BASE_IMAGE
    ARG DEF_IMAGE
    ARG TOOLING_IMAGE
    
    FROM ${DEF_IMAGE} as def
    FROM ${TOOLING_IMAGE} as tooling
    FROM ${BASE_IMAGE}
    
    SHELL ["powershell", "-Command", "$ErrorActionPreference = 'Stop'; $ProgressPreference = 'SilentlyContinue';"]
    
    WORKDIR C:\Identity
    
    # Add DEF module
    COPY --from=def \module\transforms\ C:\transforms\
    
    COPY --from=tooling \tools\ \tools\
    RUN C:\tools\scripts\Invoke-XdtTransform.ps1 -Path C:\Identity -XdtPath c:\transforms\id
  9. In the compose\<version>\<topology>\docker-compose.override.yml file, add build instructions for the id and cd roles. If you are using, for example, the XP1 topology, the file will look like this:

    services: 
      id: 
        image: sitecore-sfmcbde-id:${SITECORE_VERSION} 
        build: 
          context: ./module 
          dockerfile: ./id/Dockerfile 
          args: 
            BASE_IMAGE: ${SITECORE_DOCKER_REGISTRY}sitecore-id6:${SITECORE_VERSION} 
            DEF_IMAGE: ${SITECORE_DOCKER_REGISTRY}modules/sitecore-def-xp1-assets:${DEF_VERSION} 
            TOOLING_IMAGE: ${SITECORE_TOOLS_REGISTRY}sitecore-docker-tools-assets:${TOOLS_VERSION} 
     
      cd: 
        image: sitecore-sfmcbde-xp1-cd:${SITECORE_VERSION} 
        build: 
          context: ./module 
          dockerfile: ./cd/Dockerfile 
          args: 
            BASE_IMAGE: ${SITECORE_DOCKER_REGISTRY}sitecore-xp1-cd:${SITECORE_VERSION} 
            SFMCBDE_IMAGE: ${SITECORE_DOCKER_REGISTRY}modules/sitecore-sfmcbde-xp1-assets:${SFMCBDE_VERSION}
  10. In the compose\<version>\<topology>\tenant-service.override.yml file, add build instructions for the tenant-service role. For example:

    services: 
      tenant-service: 
        build: 
          context: ./module 
          dockerfile: ./tenantservice/Dockerfile 
          args: 
            BASE_IMAGE: ${SITECORE_DOCKER_REGISTRY}modules/sitecore-tenant-service:${MODULE_VERSION} 
            SFMCBDE_IMAGE: ${SITECORE_DOCKER_REGISTRY}modules/sitecore-sfmcbde-xp1-assets:${SFMCBDE_VERSION} 
            TOOLING_IMAGE: ${SITECORE_TOOLS_REGISTRY}sitecore-docker-tools-assets:${TOOLS_VERSION} 
        environment: 
          TenantService_ConnectionStrings_sitecore: database=master;tenant id=${SITECORE_TENANT_ID};host=http://cm;timeout=20;auth endpoint=http://id/;client secret=${SITECORE_CLIENT_SECRET};client id=${SITECORE_CLIENT_ID} 
          TenantService_ConnectionStrings_xconnect.collection: http://xdbcollection 
          TenantService_ConnectionStrings_Xdb.ReferenceData.Client: http://xdbrefdata 
          TenantService_ConnectionStrings_sfmc: ${ConnectionString_sfmc} 
          TenantService_SfmcJourney_ExecuteUrl: ${TENANT_SERVICE_CONFIG_EXECUTE_URL}
  11. In the compose\<version>\<topology>\.env file, add the asset image version. For example:

    DEF_VERSION=<image version for your topology>
    SFMCBDE_VERSION=<image version for your topology>
    SITECORE_TOOLS_REGISTRY=scr.sitecore.com/tools/
    TOOLS_VERSION=<image version for your topology>
    MODULE_VERSION=<Tenant Service image version for your topology>

    Note

    You can find the image version in the Sitecore Docker Images repository.

  12. In the Windows console, go to the folder containing the docker-compose.override.yml file. Run the command docker-compose -f docker-compose.yml -f docker-compose.override.yml -f tenant-service.override.yml up –detach.

  13. When the Docker compose command has finished, rebuild your search indexes.

Note

To test if the Tenant Service is running, follow the Deploy the Tenant Service container section of the Installation Guide for Data Exchange Tenant Web Service, which is available on the Sitecore download page.