Salesforce Marketing Cloud Engagement Content Sync

The Salesforce Marketing Cloud Engagement Content Sync app syncs content from Contentful into Salesforce Marketing Cloud Engagement Data Extensions, and keeps them up to date every time an entry is published or unpublished.

Overview

The Salesforce Marketing Cloud Engagement Content Sync app turns any Contentful content type into a source of rows for a Data Extension. An admin links a content type to a Data Extension from the app's page, either by creating a new Data Extension from the content type or by choosing one that already exists. The app then copies every published entry into it.

From then on, sync is automatic. Publishing an entry updates its rows in Marketing Cloud Engagement, and unpublishing an entry marks its rows inactive. Marketers can use the synced content anywhere they use Data Extensions, including AMPscript, SQL Query Activities, and Journey Builder.

The app connects to Marketing Cloud Engagement through an Installed Package that you create in your Marketing Cloud Engagement account. The package gives you a Client ID and Client Secret, which you enter in the app's configuration screen. Setup takes about 15 minutes: the first half in Marketing Cloud Engagement, the second half in Contentful.

Requirements

  • Space Admin access to the Contentful space where you're installing the app.

  • A Salesforce Marketing Cloud Engagement account.

  • A Marketing Cloud Engagement user with the Installed Package | Administer permission. This is included in the Administrator and Marketing Cloud Administrator roles. If you don't have it, ask your Marketing Cloud Engagement admin.

  • An Installed Package with a Server-to-Server API Integration component, granted Data Extensions: Read and Write. Step 1 walks you through creating it.

  • Optional: your parent business unit's MID, if your account has more than one business unit and you want child business units to use the content. See Step 3.

Usage

Step 1: Create an Installed Package in Marketing Cloud Engagement

An Installed Package is how Marketing Cloud Engagement lets an outside app, such as Contentful, connect to your account. These steps follow Salesforce's instructions for creating a server-to-server integration.

  1. Log in to Marketing Cloud Engagement. If your account has multiple business units, switch to the parent (top-level) business unit first and create the package there.

  2. Click your username, then click Setup.

  3. Go to Platform Tools › Apps › Installed Packages.

  4. Click New.

  5. Enter a name, such as Contentful Integration, and an optional description, then click Save. The package's "Details" tab is displayed.

Step 2: Add an API Integration component

  1. On the package's "Details" tab, click Add Component.

  2. Select API Integration, then click Next.

  3. Select Server-to-Server as the integration type, then click Next. Server-to-Server integrations use the Client Credentials grant type, so no user sign-in is needed when the app syncs.

  4. Under Scope, turn on only the following:

Area

Permissions

Data › Data Extensions

Read, Write

  1. Leave all other scopes off. The app only needs to create Data Extensions and write rows to them.

  2. Click Save.

The package now shows an API Integration section with a Client Id, a Client Secret, and an Authentication Base URI. Keep this page open. You'll copy these values into Contentful in Step 6.

NOTE: Salesforce allows only one API Integration component per Installed Package, and it can't be removed once it's added. If you pick the wrong integration type, create a new package.

Step 3: Find your parent business unit MID (optional)

Skip this step if your account has only one business unit, or if you only want content in the business unit where the package lives.

Setting the parent business unit's MID makes the app create Shared Data Extensions in the parent business unit, which you can then share with child business units.

  1. Go to Setup › Administration › Business Units.

  2. The business unit at the top of the tree is the parent. Copy its MID, a number such as 523012158.

Step 4: Give the package access to your business units (multi-business-unit accounts only)

  1. Open your Installed Package and go to the Access tab.

  2. Make sure the parent business unit is selected, along with any child business units you want the app to work in.

  3. Click Save.

If you skip this step, the connection check in Step 7 fails with an access error for the parent business unit.

Step 5: Install the Salesforce Marketing Cloud Engagement Content Sync app in Contentful

  1. Log in to the Contentful web app.

  2. Under Platform, click Apps.

  3. Under Marketplace, click All apps.

  4. Find the Salesforce Marketing Cloud Engagement Content Sync app and click its card. The App details window is displayed.

  5. Click Install. The Manage app access window is displayed.

  6. Under Environments, select the environments where you want to install the app.

  7. Click Authorize access. The configuration screen is displayed.

Step 6: Enter your connection details

Copy these values from the Installed Package page you left open in Step 2:

Contentful field

Where to find it in Marketing Cloud Engagement

Auth base URL

Authentication Base URI, for example https://mc1a2b3c.auth.marketingcloudapis.com/

Installed Package client ID

Client ID

Installed Package client secret

Client Secret. Click Show or the eye icon to reveal it.

Parent BU MID (optional)

The MID from Step 3. Leave blank if you skipped it.

NOTE: You don't need the REST or SOAP base URIs. The app picks them up automatically.

The client ID and secret are stored securely and aren't shown again after you save. To change them later, enter new values. To keep the current ones, leave the fields blank.

Step 7: Save and check the connection

  1. Click Install (or Save if the app is already installed) in the top right.

  2. The app checks the connection automatically. With a parent BU MID, you should see a green message such as:
    Connected. New Data Extensions will be created as Shared Data Extensions in parent BU [BU MID#], under Shared Data Extensions › Contentful.
    If the Contentful folder doesn't exist yet, the message ends with (created on first use). The app creates the folder the first time it creates a Data Extension.
    Without a parent BU MID, the message names the business unit the Installed Package uses instead:
    Connected. New Data Extensions will be created in BU [BU MID#] (not shared). Set the Parent BU MID to create Shared Data Extensions instead.

You can run the check again at any time with Check connection on the configuration screen. It only reads from Marketing Cloud Engagement and changes nothing.

Saving also adds two content types to your space: Data Extension Registry (do not delete) and DE Sync Linkage (do not delete). The app uses them to remember which content type syncs to which Data Extension. Manage them from the app's page rather than editing those entries directly, and don't delete either content type.

Step 8: Sync your first content type

Open the app's page from Apps › Salesforce Marketing Cloud Engagement Content Sync. The page lists every content type in the space with its linked Data Extension, if any. Use the search box or the filter to find a content type, then open its three dots menu (⋯).

To create a new Data Extension from a content type:

  1. Choose Create new Data Extension.

  2. Select the fields you want to sync. Use Select all or Select none to speed this up.

  3. Optional: in Extra field labels, add comma-separated labels for extra text columns that you want in the Data Extension but that don't come from Contentful.

  4. Click Create and link. The app creates the Data Extension, links the content type, and copies every published entry into it.

To link a content type to an existing Data Extension:

  1. Choose Link to existing Data Extension.

  2. Pick the Data Extension from the list. Data Extensions that aren't linked yet are listed separately from ones already used by other content types.

  3. If the Data Extension's columns don't match the content type's fields, the app shows a warning listing columns that will stay empty and fields that won't sync. Review it before you continue.

  4. Click Link and backfill.

Step 9: Manage a linked content type

Open the three dots menu (⋯) on any linked content type to:

  • Backfill now: copy every published entry into the Data Extension again.

  • Edit synced fields: change which fields sync. Newly selected fields get a new column in the Data Extension. Fields you deselect keep their column but stop being updated. Click Save and re-sync to save and re-sync the content type.

  • Change Data Extension: link the content type to a different Data Extension, then click Change and backfill.

  • Unlink: stop syncing this content type. The app asks you to confirm first. Nothing is deleted in Marketing Cloud Engagement.

Where to find the synced data

Synced data lives in Contact Builder, not Content Builder:

  • Without a parent BU MID: Audience Builder › Contact Builder › Data Extensions › the Contentful folder.

  • With a parent BU MID: in the parent business unit, Contact Builder › Shared Data Extensions › the Contentful folder.

Each Data Extension is named after its content type, for example, blogPost_DE.

Share with child business units (multi-business-unit accounts only)

The app can't control which child business units see a Shared Data Extension. Marketing Cloud Engagement manages that. In the parent business unit, open Shared Data Extensions, right-click the Contentful folder (or a single Data Extension), choose Sharing, and select the child business units.

In a child business unit, refer to a Shared Data Extension with the ENT. prefix, for example ENT.blogPost_DE in AMPscript or SQL Query Activities.

How content is synced

  • One row per locale. Each Data Extension the app creates has an ExternalKey primary key made of the entry ID and the locale, so each locale of an entry is its own row.

  • Publishing updates rows. Publishing an entry adds or updates its rows.

  • Unpublishing deactivates rows. Unpublishing an entry sets IsActive to false on its rows instead of deleting them. Filter on IsActive = true in your AMPscript lookups and queries.

  • Deleting an entry. Contentful requires you to unpublish an entry before deleting it, so a deleted entry's rows stay in the Data Extension marked inactive.

  • Bookkeeping columns. Every Data Extension the app creates also includes ContentfulEntryId, ContentfulSpaceId, ContentTypeId, Locale, ContentVersion, PublishedAt, IsActive, and SourceSystem.

  • Field types. Fields map to Data Extension columns as follows:

Contentful field type

Data Extension column

Short text

Text (255)

Long text, Number, Short text list (comma-separated)

Text (4000)

Integer

Number

Date and time

Date

Boolean

Boolean

  • Reference, media, Rich Text, JSON object, and location fields aren't synced yet.

Limitations

  • Reference, media, Rich Text, JSON object, and location fields can't be synced yet.

  • Rows are never deleted. Unpublishing an entry marks its rows inactive. Unlinking a content type stops syncing but leaves the Data Extension and its rows in place.

  • Sharing Shared Data Extensions with child business units is managed in Marketing Cloud Engagement, not in the app.

  • Changing the parent BU MID only affects Data Extensions created afterwards. Existing Data Extensions keep syncing to the business unit they're in.

  • Very large content types (many thousands of entries) can time out during a backfill.

Troubleshooting

Message

What it means

Fix

Marketing Cloud Engagement is not configured on this app installation (...)

The auth base URL, client ID, or client secret is missing.

Enter the missing values from Step 6 and save.

OAuth failed (401) or invalid_client

The client ID or secret is wrong, or the secret was rotated.

Copy both values again from the Installed Package and save.

OAuth failed for business unit <MID>

The package doesn't have access to that business unit.

Step 4: select the business unit on the package's Access tab.

BU <MID> is not the parent (Enterprise) BU

The MID belongs to a child business unit.

Use the MID at the top of the business unit tree (Step 3).

No Shared Data Extensions folder was found in parent BU <MID>

The app can't reach the Shared Data Extensions folder in that business unit.

Confirm the MID is the parent business unit (Step 3) and that the package has access to it (Step 4).

Enter the auth base URL like https://...auth.marketingcloudapis.com/

The URL isn't the Authentication Base URI.

Copy the Authentication Base URI exactly. It contains .auth.

OAuth response did not include the REST and SOAP base URLs

The auth base URL isn't the one on your Installed Package.

Copy the Authentication Base URI from the package's API Integration section and save.

Insufficient privileges when creating a Data Extension

The package is missing the Data Extensions scope.

Step 2: turn on Data Extensions Read and Write, then save the package.

Can't find the data in Marketing Cloud Engagement

You're looking in Content Builder.

See Where to find the synced data.

Rotate the client secret

Marketing Cloud Engagement client secrets expire. The expiry date is shown under Active Secret on the API Integration. To rotate without downtime:

  1. On the API Integration, click Generate under Staged Secret.

  2. Paste the new secret into the app's Installed Package client secret field and save.

  3. Back in Marketing Cloud Engagement, click Activate to make the staged secret active.

FAQs

Does the app sync automatically when I publish an entry?
Yes. Once a content type is linked, publishing an entry updates its rows and unpublishing marks them inactive.

Do edits in Marketing Cloud Engagement Content sync back to Contentful?
No. Sync goes one way, from Contentful to Marketing Cloud Engagement. Contentful stays the source of truth.

Why are my rows still there after I unpublished an entry?
Marketing Cloud Engagement's row API can't delete rows, so the app sets IsActive to false instead. Filter on IsActive = true to exclude them.

Can child business units use the synced content?
Yes. Set the parent BU MID during setup so the app creates Shared Data Extensions, then share them with child business units in Marketing Cloud Engagement. Child business units reference them with the ENT. prefix.

Who does the app act as in Marketing Cloud Engagement?
The Installed Package. It uses the Client ID and Client Secret you entered, with only the Data Extensions permissions you granted. No individual user's sign-in is involved.