Marketing Cloud Form Selector

The Marketing Cloud Form Selector app lets editors search Salesforce Marketing Cloud Growth forms and attach them to Contentful entries, rather than manually copying embed codes or form IDs.

Overview

The Marketing Cloud Form Selector app adds a form selector to a JSON object field in your content model. On an entry, editors can click Select form, search your Marketing Cloud Growth forms by name, and select one. The app saves the form's content key and fragment ID on the entry. Your website or app uses those values to display the live Salesforce form.

Admins can connect the space to Salesforce in the app configuration screen. They can also limit which Salesforce CMS workspaces editors select forms from.

The app connects to Salesforce with OAuth through the Contentful External Client App, so access follows the permissions of the Salesforce user who connects it. No passwords or API keys are stored in Contentful.

The app selects forms, but doesn't display them. A developer must add form rendering to your front end once, using the stored values. See Display the form on your website.

Requirements

To use the Marketing Cloud Form Selector app, you need:

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

  • A Salesforce org with Marketing Cloud Growth and at least one published form.

  • The Contentful External Client App (ECA) package installed in that Salesforce org - allows Contentful to connect to Salesforce with OAuth. See Step 1.

NOTE: If your org already has Contentful ECA package installed for another Contentful Salesforce app, such as Marketing Cloud Next, you can skip this step.

  • A Salesforce user who can sign in through the ECA and view your Marketing Cloud Growth forms and CMS workspaces. Editors see the forms and workspaces this user can see.

  • Your Salesforce org's My Domain URL, for example, https://yourcompany.my.salesforce.com. You can find it in Salesforce under Setup › My Domain › Current My Domain URL.

  • A content type with a JSON object field to hold the selected form - You can add one in Step 6.

Usage

Step 1: Install the Contentful External Client App in Salesforce

The External Client App (ECA) is a small Salesforce package that registers Contentful as a trusted app in your org. You must install it only once per Salesforce org.

  1. Log in to Salesforce as an admin.

  2. Open the install link for the Contentful package (version 0.2.0-1): · Production or Developer Edition org: https://login.salesforce.com/packaging/installPackage.apexp?p0=04ti8000002OjXVAA0

  3. When Salesforce asks who to install the package for, choose Install for Admins Only or Install for All Users.

  4. Click Install and approve the third-party access prompt if it appears.

  5. Wait for the confirmation that installation is complete. Large orgs may get an email instead.

  6. To confirm, go to Setup › External Client App Manager. Contentful will be listed as Packaged (Installed) and Enabled.

Step 2: Install the Marketing Cloud Form Selector 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 Marketing Cloud Form Selector 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 3: Enter your Salesforce My Domain URL and install

  1. In the Salesforce My Domain URL field, enter your org's My Domain URL, for example, https://yourcompany.my.salesforce.com. Enter the host only, with no path or query string.

  2. Click Install in the top right.

NOTE: The app must be installed before you can connect to Salesforce, this is why it is essential to complete this step before Step 4.

Step 4: Connect to Salesforce

  1. Under Salesforce connection, click Connect.

  2. A popup opens Salesforce's sign-in screen. Sign in as the Salesforce user, as described in the requirements above.

  3. Approve access.

  4. The popup closes, the button changes to Connected, and Contentful displays Connected this space to Salesforce.

NOTE: The connection covers the whole space and environment. Every editor's form searches use it, so you only connect once. If the popup doesn't open, make sure popups aren't blocked for your Contentful domain.

Step 5 (optional): Limit the workspaces editors can select from

By default, editors can select forms from every Salesforce CMS workspace the connected user can see. To narrow that down:

  1. Under Allowed workspaces, click the Workspaces box and type to search. The list loads from Salesforce after you connect.

  2. Select a workspace to add it to the list of allowed workspaces. Repeat for each workspace you want to allow.

  3. To remove a workspace, click the × on its pill.

  4. Click Save in the top right.

NOTE: If this list is empty, editors can select forms from every workspace.

Step 6: Add a form field to a content type

  1. In the Contentful web app, go to Content model and either open an existing content type that will hold a form, or create a new one.

  2. Click Add field, select JSON object, name the field (for example, "Form"), and click Add and configure.

  3. Open the field's Appearance tab and select Marketing Cloud Form Selector.

  4. Click Confirm, then save the content type.

Step 7: Attach a form to an entry

  1. Open an entry of that content type.

  2. In the form field, click Select form. The Select a Marketing Cloud form dialog window is displayed.

  3. Type in Search forms by name to filter the list. If more than one workspace is allowed, use the workspace menu to narrow the list further.

  4. Choose a form with a Published status and click Select. The field displays the form's name and the stored value.

  5. Publish the entry.

  6. To use a different form, click Change. To remove the form from the field, click Clear.

Display the form on your website

The app saves a small JSON value on the entry:

Marketing Cloud Form Selector - app JSON

  • contentKey - identifies the form's embed bundle in Salesforce.

  • fragmentID - identifies the form's custom element inside that bundle.

To display the form, your front end loads the form's embed bundle from your org's Salesforce site domain and renders the matching element:

Marketing Cloud Form Selector - display the form

Replace yourcompany.my.site.com with your org's site domain. It's your My Domain host with .my.salesforce.com replaced by .my.site.com. If your Salesforce landing page requires reCAPTCHA, your page must also load it.

Limitations

  • The app selects forms but doesn't display them. Your front end renders the form from the stored values.

  • Only published forms have a fragment ID. If you select an unpublished form, the field shows a warning and stores an empty fragment ID. Publish the form in Salesforce, then click Change and select it again.

  • Search shows up to 50 matching forms, most recently changed first. Type more of the name to find older forms.

  • The app reads the form's en-US embed bundle.

  • A single Salesforce org can be connected per space and environment. The connection is shared by everyone who uses the app there, and Disconnect removes it for everyone.

  • Salesforce sandbox orgs aren't supported yet.

Troubleshooting

Connect doesn't complete, or the pop-up closes without connecting

Make sure pop-ups aren't blocked for your Contentful domain. Confirm the Contentful External Client App is installed in your Salesforce org (Step 1) and that the user you're signing in as is allowed to use it. If Contentful displays "Salesforce declined the connection," the message that follows gives Salesforce's reason.

The Connect button shows "Failed to start Salesforce OAuth flow"

Install the app first (Step 3). The connection can only be made once the app is installed. If the app is already installed, reload the configuration screen and try again.

An error about the My Domain URL when installing or saving

Enter your My Domain URL exactly as shown in Setup › My Domain › Current My Domain URL, such as https://yourcompany.my.salesforce.com. It must start with https:// and have no path or query string. Don't use login.salesforce.com, test.salesforce.com, or a .my.site.com site domain. None of them serve the Salesforce APIs the app needs.

"This space isn't connected to Salesforce" when searching for forms

No space has been connected yet, or the connection was removed. A space admin must open the app's configuration screen and click Connect.

The form selector shows "No forms found."

The connected Salesforce user can't see any matching forms. Check that the forms exist in Marketing Cloud Growth, whether the user can see their CMS workspace, and whether the workspace is allowed under Allowed workspaces. Clear the search box to see all forms.

The field warns that the form isn't published

The form had no fragment ID when it was selected. Publish the form in Salesforce, then click Change on the field and select it again.

The Workspaces box says "Connect to Salesforce first"

Workspaces load from Salesforce, so connect first (Step 4). If you're connected and the list still doesn't load, click Load workspaces.

The form doesn't show up on my website

Check that the entry is published and the stored value has a fragmentID. Then check that your front end loads the embed bundle from your .my.site.com domain and renders fragment-{fragmentID}. See Display the form on your website.

FAQs

Does the app store the form's HTML or embed code?

No. It stores only the form's content key and fragment ID. Your front end builds the embed code from those values, so it always shows the form as it's currently published in Salesforce.

If we edit a form in Salesforce, do we need to update the entry?

No, as long as it's the same form. The entry points to the form, so republished changes show up on your website. If you switch to a different form, click Change on the entry.

Which user does the app act on behalf of?

The app acts on behalf of the Salesforce user who selected Connect on the configuration screen. Every editor's search uses that user's permissions. To change users, hover over Connected, click Disconnect, and connect again as the new user. Disconnecting affects everyone in the space.

Can editors select forms from only some workspaces?

Yes. Add the workspaces you want under Allowed workspaces on the configuration screen. Editors can then select only from those workspaces.

Do I need to install the External Client App again for each Contentful space?

No. The ECA is installed once per Salesforce org. Each Contentful space only needs to install the Marketing Cloud Form Selector app and connect.