Information for: DEVELOPERS   PARTNERS   SUPPORT

Salesforce plugin setup

Organizations use customer relationship management (CRM) tools, such as Salesforce and marketing automation platforms (MAPs), such as Campaign Studio, hand-in-hand. This enables them to collect and store data about their customers and leads. Such organizations use the data to provide personalized marketing from Campaign Studio based on the data stored in Salesforce.

Note

The Salesforce plugin that is available in Campaign Studio, uses API calls, which are only available in the following Salesforce editions:

  • Enterprise
  • Unlimited
  • Developer
  • Performance

If you don’t use one of these Salesforce editions, you can’t use the plugin.

Using the Salesforce plugin has two primary phases:

  1. Configuration
  2. Ongoing usage

Creating a connected app in Salesforce

In order to use Salesforce with Campaign Studio, you must have a connected app in Salesforce. You may use an existing Salesforce user for the connection. However, Acquia recommends that you create a Salesforce user exclusively for connecting with Campaign Studio.

Note

You can use a regular user’s profile to connect to Campaign Studio. However, the user name used for authentication is the user name that displays for any changes to data pushed from Campaign Studio to Salesforce.

To create a connected app:

  1. Access your Salesforce account.

  2. Navigate to Setup > Apps > App Manager and click New Connected App.

    For more information, see Configure Basic Connected App Settings.

    SF new app

  3. In the Basic Information section:

    campaign-studio-salesforce-connected-app

    1. In Connected App Name, specify a name for the connected app. For example, Campaign Studio.
    2. In API Name, set the value to Campaign_Studio. The system populates this field dynamically based on the value specified in Connected App Name.
    3. In Contact Email, specify the email address to which Salesforce can send an email, regarding the connected app.
    4. In Contact Phone, specify the phone number which Salesforce can contact regarding the connected app.
    5. In Logo Image URL, click Upload logo image to upload the image located here.
    6. In Info URL, specify the URL for this documentation page.
    7. In Description, specify the description for the connected app. For example, Integration with Campaign Studio.
  4. Under the API (Enable OAuth Settings) section:

    campaign-studio-salesforce-oauth-app

    1. Select the Enable OAuth Settings check box.

    2. In Callback URL, specify the Callback URL displayed in the plugin configuration modal in your Campaign Studio instance. The format is: https://subdomain.company.com/integration/Salesforce2/callback, where subdomain.company.com is replaced with your custom domain.

      campaign-studio-salesforce-oauth-app-screen

    3. Clear the Use digital signatures check box.

    4. In Selected OAuth Scopes, select the following scopes and move them to the Selected OAuth Scopes section on the right.

      • Manage user data via APIs (api)
      • Perform requests at any time (refresh_roken, offline_access)
  5. Save the changes.

  6. On the App Manager page, locate the row for your connected app.

  7. Click the down arrow icon in the same row and then click View.

  8. Locate Manage Consumer Details and copy the value for Consumer Key and Consumer Secret.

    You must specify these values in Campaign Studio while configuring the Salesforce plugin. For more information, see Configuring the plugin in Campaign Studio.

    campaign-studio-salesforce-oauth-app-screen-consumer

Configuring the plugin in Campaign Studio

To configure the plugin in Campaign Studio:

  1. Sign in to your Campaign Studio account.

  2. Click the Settings icon on the top right corner and select Plugins.

  3. Click the Salesforce plugin. If you see two Salesforce options, select the second one (the first one is the legacy Salesforce plugin).

    campaign-studio-salesforce-plugin

  4. Under the Enabled/Auth section, perform the following steps:

    campaign-studio-salesforce-Enabled/Auth

    1. Leave the plugin unpublished until you’re fully ready to turn on the plugin and start syncing data.

      Note

      Whenever you make any configuration changes, such as field mapping changes, ensure that you unpublish and re-publish the plugin for all the changes to take effect.

    2. Specify the values for Consumer id and Consumer secret. You’ll get these values from Salesforce apps page. For more information, see Creating a connected app in Salesforce.

    3. Click Authorize App. A new window will open, where you can log in to Salesforce using the user credentials you’ve created for the plugin to use.

      Note

      If you try to authorize Campaign Studio immediately after creating the connected app in Salesforce, you might get an error. If so, wait for ~10 minutes and try again. The connected app and its credentials need time to propagate.

  5. Under the Features section, perform the following steps:

    campaign-studio-salesforce-Features

    1. To enable sync between Salesforce and Campaign Studio, select the Sync objects between Campaign Studio and this integration check box. If this box is not selected, data doesn’t sync regularly. However, you’ll be able to use specific actions in campaigns, forms, and point triggers to push contacts from Campaign Studio to Salesforce. Once pushed, no data for those contacts will be updated in Campaign Studio if this check box is not selected.

    2. In Select the objects to sync with Campaign Studio, select the specific objects for which you want to get data synced between Salesforce and Campaign Studio. Available objects are Leads, Contacts, and Accounts.

    3. In Start synchronization from date, select the date from which data needs to be synced between Salesforce and Campaign Studio. Any records updated in Salesforce more recently than the selected date will be pulled into and synced with Campaign Studio. If you change this date after first publishing the plugin, you’ll need to unpublish and re-publish the plugin for the sync to start from the new date.

    4. (Optional) In Fetch only records for Lead that meet the following condition, select either Include or Exclude to include or exclude leads who have either a positive or negative value on a boolean field in Salesforce.

      Note

      If you don’t want to sync all leads, you may want to create a field in Salesforce for Sync to Campaign Studio and update that to a positive value using a Salesforce workflow, based on the criteria you determine.

    5. (Optional) In Push only records for Lead that meet the following condition, select either Include or Exclude to include or exclude leads who have either a positive or negative value on a boolean field in Salesforce.

      Note

      If you do not want to sync all contacts, then create a field in Salesforce for Sync to Campaign Studio and update that to a positive value using a Salesforce workflow, based on the criteria you determine.

    6. (Optional) Repeat the above step for Company.

    7. (Optional) Repeat the above step for contact and account objects.

    8. To display a lead or contact’s Campaign Studio activity timeline on the record in Salesforce, set the Upload Campaign Studio activities toggle bar to Yes. For more information, see Timeline object.

    9. In Events to include in the activity sync, select the activity types that you’d like to display in Salesforce, if the Upload Campaign Studio activities toggle bar is set to Yes. For example, Email read, Form submitted, Point gained.

    10. If the Salesforce account that you’re connecting to is a sandbox for testing purposes, select the This is a Sandbox account check box.

      Note

      For sandbox, ensure that you select this check box as sandbox logins have different URLs, such as test.salesforce.com.

    11. In If your Salesforce account uses a namespace prefix, enter it here, specify your organization’s namespace prefix, if it is defined. Having a namespace prefix changes the API names for fields. Hence, if you have one, you must define it here.

  6. Under the Lead Field Mapping section, perform the following steps:

    campaign-studio-salesforce-Lead

    1. Map the specific Campaign Studio lead to a Salesforce field. Campaign Studio automatically identifies the Salesforce fields for each of the lead objects. The fields for each object are listed alphabetically. However, you can find a specific Salesforce field by using the Filter integration fields… search bar.

    2. From the following available options, select the direction you’d like the data to flow. To ensure that the data gets synced properly, see Field mapping validation.

      • Sync only to Campaign Studio: If Salesforce is your source of truth and data shouldn’t be updated in Salesforce by Campaign Studio.
      • Sync only to the integration: If you don’t want data to be updated in Campaign Studio by Salesforce.
      • Sync both ways: if you want to always match the fields using the latest updated data, no matter which system the data was last updated in.

      Important

      • If a synced record is updated in both systems within the same window between syncs, the system with the more recently changed data pushes data to the other system. The sync is expected to take place approximately every five minutes.
      • If a field is not writable in Salesforce, the system displays only the Sync only to Campaign Studio option for the direction of the sync.
      • For leads, you must map Company Name, Email address, and Last Name. Records that don’t have values in any required fields don’t sync.
  7. Repeat the above step for the Contact Field Mapping and Account Field Mapping sections. For contacts, you must map Email and Last Name. For accounts, you must map Account Name.

  8. Under the Enabled/Auth section, set the Plugin must be enabled and authorized for this field to work toggle bar to Yes (published).

  9. Click Apply or Save & Close.

Important

Each time you publish/re-publish the plugin, the entire sync is triggered/re-triggered. This uses API calls, which Salesforce monetizes. Once you’ve hit your API limits with Salesforce, your data stops syncing until either the limit refreshes or you pay more to increase the limit.

Field mapping validation

Within the field mapping, Campaign Studio has validations that prevent mismatched data from being synced. There are two types of validation that Campaign Studio performs:

  • Field Type: If the data types on the mapped fields are mismatched, Campaign Studio displays a warning. For example, mapping a field with data type string in Salesforce to a number data type in Campaign Studio triggers this warning.
  • Field Length: If the maximum length of the field in the source location is longer than the maximum length in the destination, Campaign Studio displays a warning. For example, if the Lead Source field in Salesforce has a maximum length of 255 characters but that field’s maximum length has been reduced to 30 characters in Campaign Studio and you set the direction of the mapping to be bidirectional, you’ll see the warning.

In both cases, you can save the mapping and ignore the warning. In cases where field data can’t be synced, any other syncable data on a record is synced and the remaining data is skipped. You’ll see a notification in your Campaign Studio instance and on the individual contact record.

Note

Before you delete a custom field from Salesforce, you must remove the related field mapping from Campaign Studio to avoid losing leads/contacts.

Setting up timelines

As a Salesforce user, you might want to view a lead or contact’s engagements with marketing activities. The following two ways enable you to view activities and interactions from Campaign Studio, as a Campaign Studio user would normally see on a contact record:

Timeline object

By using the timeline object feature, you can view the details about activities passed from Campaign Studio to Salesforce, within Salesforce.

Important

To use this option, ensure that you set the Upload Campaign Studio activities toggle bar to Yes (under the Features tab of the Salesforce plugin configuration in Campaign Studio).

To use this feature:

  1. Follow the steps mentioned in Creating a custom object.

  2. Set the Label to Campaign Studio Activities and Object Name to mautic_timeline.

    salesforce-timeline-objects

  3. Save the changes.

  4. Under the Custom Fields & Relationships section, click New to create the following custom fields with the mentioned data types:

    • ActivityDate: Date/Time
    • contact_id: Lookup(Contact)
    • Description: Long Text Area(131072)
    • WhoId: Lookup(Lead)
    • MauticLead: Number(18, 0) (External ID)
    • mautic_url: URL(255)
    • ReferenceId: Text(255)

    Note

    • Set the ReferenceId as unique. To do so, select the do not allow duplicate values check box.
    • The object name must be mautic_timeline and the fields must contain Mautic as stated above.
  5. Save the changes.

  6. Update the layouts for both the lead and contact objects so that the new custom object can be viewed.

  7. On the timeline object in the layout editor, select ActivityDate from the list of Available Fields to add it to Selected Fields and save.

  8. Unpublish and re-publish the Salesforce plugin.

    Note

    Once you delete a custom field in Campaign Studio, mapping for that custom field also gets deleted from the Salesforce configuration.

Segment filters

salesforce-segment

Once the plugin is authorized and published, you can view three Salesforce specific segment filters:

  • Is a Salesforce Contact
  • Is a Salesforce Lead
  • Salesforce Campaign

The Salesforce filters for lead and contact have operators of including/excluding with values of yes/no.

For example,

  • To create a segment of any Campaign Studio records that are synced to Salesforce contacts, select Is a Salesforce Contact, Including, and Yes.
  • To create a segment of all records which aren’t synced with a Salesforce contact, select Is a Salesforce Contact and Excluding/Yes or Including/No.

For Salesforce campaign filters, the operators are equals/not equal/empty/not empty. Once you’ve selected the appropriate operator, type the name of the Salesforce campaign that you want to use in the filter. Campaign Studio displays a list of Salesforce campaigns with matching names, and the available statuses. To include multiple campaigns and/or statuses, add multiple segment filters with the OR filters.

Form, Campaign, and Point Trigger Actions

salesforce-actions

Campaign Studio has multiple Salesforce specific actions related to forms, campaigns, and point triggers. These actions can modify the way a record is synced with Salesforce:

All of the above actions are available as standalone form actions, campaign actions, and as point triggers. However, these actions are not available for campaign forms.

Create Salesforce task

salesforce-action-create

When a contact submits a form, Campaign Studio can automatically create a task for a Salesforce user to follow up or complete some other action. To get a task created in Salesforce automatically, you can use the Create Salesforce task action.

The available fields for this action are:

  • Name: This is simply a name for the form action. This doesn’t appear in Salesforce.
  • Description: Add more details on what the task is. This will not appear in Salesforce.
  • Subject: Add a title for the task that indicates what should be done with the record. This is the name of the task that appears in Salesforce.
  • Owner: Allow Campaign Studio to assign the task to the record’s owner in Salesforce automatically or assign the task to a specific Salesforce user manually. If you select the Assign to contact owner option but the record doesn’t have an owner in Salesforce, Campaign Studio assigns the task to the selected default owner.
  • Priority: Set the priority of the task as high, medium, or low.
  • Status: Set the status of the task automatically, based on the statuses available for tasks in your Salesforce configuration.
  • Comments: Specify any comments that should appear in the Comments section of the task in Salesforce. This may include steps to complete the task, why the task is assigned, or any other information.
  • Due In: Set the number of days in which the task should be completed.
  • Remind In: Set the number of days in which a reminder notification (within Salesforce) needs to be sent to the task’s owner/assignee, if the task isn’t completed.

Push contact to Salesforce

salesforce-action-push

When a lead or contact submits a Campaign Studio form, you may want to add them to a specific Salesforce campaign and set a status within that campaign. If the lead or contact already exists in Salesforce, Campaign Studio automatically syncs with that record (based on email address) and adds the existing record to the campaign with the designated status. If there is no corresponding record in Salesforce, Campaign Studio creates a new lead and adds the lead to the campaign with the designated status.

Note

The Push to Salesforce action should only be used to add contacts to a specific Salesforce campaign and not simply to create new contacts in Salesforce if the sync is turned on with the What features of this integration should be enabled check box under Settings > Plugins. Use this action to create new contacts in Salesforce only if the sync is turned off.

The available fields for this action are:

  • Name: Specify the name for the form action. This doesn’t appear in Salesforce.
  • Description: Add more detail on what the Salesforce campaign is used for.
  • Select Salesforce Campaign: Select the Salesforce campaign to which you’d like to add the lead or contact. The system populates this field with all the active campaigns in Salesforce.
  • Select Salesforce Campaign Status: Select the campaign status that triggers the push action. The system populates this field with the available statuses for the selected campaign.

To add a contact to multiple Salesforce campaigns, add multiple form actions.

Remove from Salesforce campaign

salesforce-action-remove

Once a record submits a specific Campaign Studio form, you may want to remove such a record from an existing Salesforce campaign membership.

The available fields for this action are:

  • Name: Specify the name for the form action. This doesn’t appear in Salesforce.
  • Description: Add more detail about the campaign you’re removing records from and why you’re removing records from that campaign.
  • Select Salesforce Campaign: Select the Salesforce campaign you’d like to remove the records from.

Points

Based on the status of a Salesforce campaign, Campaign Studio can add or remove points from a record.

To allocate points for Salesforce records:

  1. Sign in to your Campaign Studio account.

  2. Go to Points > Manage Actions and click New.

    salesforce-points

  3. In Name, indicate a name for the point action that appears in your point action list.

  4. In Description, add more detail on the campaign status and the value in adding or removing points based on that status.

  5. In Change points (+/-), set the number of points you’d like to add (positive number) or subtract (negative number) based on the campaign status.

  6. In When a contact, select Salesforce campaign member change for the Salesforce-specific point action. For more information, see points.

  7. In Select Salesforce Campaign, select the campaign that you want to use as the basis for changing points. The system populates this field with all the active campaigns in Salesforce.

  8. In Select Salesforce Campaign Status, select the status that triggers the point addition or subtraction to the record. The system populates this field with the available statuses for the selected campaign.

  9. Save the changes.

Once a record has the selected status on the selected campaign in Salesforce, the point action adds or subtracts the designated number of points.