Skip to main content

Walkthrough: Preparing to install an SFMC Content Exchange connector

Abstract

How to prepare for installing a Salesforce Marketing Cloud connector in Sitecore

This topic explains how to prepare for deploying the Sitecore Connect for Salesforce Marketing Cloud - Content Exchange (SFMCCE) connector to Docker and Azure Kubernetes Service.

Before you install SFMCCE for containers, you must have the following:

  • Docker Desktop installed and running. For instructions on how to set up the Docker environment, see the Containers in Sitecore development documentation.

  • If the installation is done on Docker, you must have the Sitecore Docker container files deployed on a local machine . For instructions on how to prepare the Sitecore containers, see the Installation Guide for Developer Workstation with Containers on the Sitecore download page.

  • If the installation is done on Kubernetes, you must have the Sitecore AKS container files deployed on a local machine . For instructions on how to prepare a Sitecore environment with Kubernetes, see the Installation Guide for Production Environment with Kubernetes on the Sitecore download page.

  • An SFMC account where you can create an installed package with appropriate access rights.

This walkthrough describes how to:

  • Add an API integration package to your installation.

  • Prepare a Salesforce Marketing Cloud (SFMC) connection string for your Sitecore installation.

  • Prepare the installation files.

  • Build the Docker images.

To add an API integration package to your SFMC installation:

  1. Follow the steps in the Marketing Cloud Package Development documentation for Salesforce, in the Create and Install Packages section.

  2. Select the Server-to-Server integration type for the API Integration package.

  3. Add the following required rights for your connection:

    Category

    Type

    Rights

    Assets

    Documents and images

    • Read

    • Write

    Assets

    Saved content

    • Read

    • Write

    Hub

    Tags

    • Write

When you install an SFMC connector you must specify a connection string to allow Sitecore to connect to SFMC.

To construct the SFMC connection string:

  1. In Salesforce, in the component you created, in the Components area, make a note of the following values:

    • Client Id

    • Client Secret

    • Authentication Base URI

    • REST Base URI

    • SOAP Base URI

  2. Use the values to construct a connection string with this format:

    SFMC_CONNECTIONSTRING=client id=<Client Id>;
                          client secret=<Client Secret>;
                          auth endpoint=<Authentication Base URI>;
                          rest endpoint=<REST Base URI>;
                          soap endpoint=<SOAP Base URI>;
    

To prepare the files you need for the installation:

  1. Download the SFMCCE container deployment package from the Sitecore download page. Extract it to your local workstation with the folder structure intact.

  2. Go to the folder into which you extracted the SFMCCE container deployment package. Go to the folder for the Windows version and topology you are using, for example, compose\ltsc2019\xp1.

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

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

  5. Open the .env file in an editor, and paste in the variables from the SFMCCE .env-example file. Replace the default value for SFMC_CONNECTIONSTRING with the connection string you prepared in Prepare an SFMC connection string for your Sitecore installation.

  6. From the SFMCCE compose\<version>\<topology> folder, copy the docker-compose.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, you must create Docker files for each role, and build the Docker images.

Note

For more information on image assets, see the documentation on how to Add Sitecore Modules.

To build the images:

  1. 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. Create a folder and name it module.

  2. In the module folder, create this subfolder:

    • cm

  3. In the subfolder, create a new file and name it Dockerfile. In the Dockerfile file, enter the following instructions:

    # escape=`
    ARG BASE_IMAGE
    ARG SFMCCE_IMAGE
    ARG TOOLING_IMAGE
    
    FROM ${SFMCCE_IMAGE} as sfmcce
    FROM ${TOOLING_IMAGE} as tooling
    FROM ${BASE_IMAGE} as baseImage
    
    SHELL ["powershell", "-Command", "$ErrorActionPreference = 'Stop'; $ProgressPreference = 'SilentlyContinue';"]
    
    #Add tools from sitecore-docker-tools-assets
    COPY --from=tooling \tools\ C:\tools\
    
    FROM baseImage as toolsfmc
    
    #Copy from image\module\cm\content
    COPY --from=sfmcce \module\cm\content C:\inetpub\wwwroot
    
    #Copy transformation files
    COPY --from=sfmcce \module\xdttransform\cm\transforms\ C:\transforms\role
    
    # Add SFMCCE connection strings in Sitecore config file
    RUN C:\tools\scripts\Invoke-XdtTransform.ps1 -Path C:\inetpub\wwwroot -XdtPath C:\transforms\role
    
  4. In the compose\<version>\<topology>\docker-compose.override.yml file, add build instructions for each role. If you are using, for example, the XP0 topology, the file will look like this:

    services:
      cm:
        image: sitecore-sfmcce-xp0-cm:${SITECORE_VERSION}
        build:
          context: ./module
          dockerfile: ./cm/Dockerfile
          args:
            BASE_IMAGE: ${SITECORE_DOCKER_REGISTRY}sitecore-xp0-cm:${SITECORE_VERSION}
            SFMCCE_IMAGE: ${SITECORE_DOCKER_REGISTRY}modules/sitecore-sfmcce-xp0-assets:${SFMCCE_VERSION}
            TOOLING_IMAGE: ${SITECORE_TOOLS_REGISTRY}sitecore-docker-tools-assets:${TOOLS_VERSION}
            environment:
              Sitecore_ConnectionStrings_mysf: ${MYSF_CONNECTIONSTRING}
    
  5. In the compose\<version>\<topology>\.env file, add the asset image version. For example:

    SFMCCE_VERSION=<image version for your topology>
    SITECORE_TOOLS_REGISTRY=scr.sitecore.com/tools/
    TOOLS_VERSION=<image version for your topology>

    Note

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

  6. In the Windows console, go to the folder containing the docker-compose.override.yml file. Run the command docker-compose build.

  7. If you are deploying to Docker, continue with the instructions in Add the SFMCCE connector module to Sitecore in Docker.

    If you are deploying to Kubernetes, continue with the instructions in Walkthrough: Adding the SFCRMCE connector module to Sitecore in Azure Kubernetes Service.