Salesforce Marketing Cloud

Salesforce Marketing Cloud is a Customer Relationship Management (CRM) platform predominantly used by marketers to create and manage marketing relationships and campaigns with customers. It can be integrated with websites and social media and allows for tailored ad campaigns based upon demographics and behaviors.

Information Stored
Minimum Permissions Required
Authentication Method
Prerequisite Salesforce Marketing Cloud Configurations
Credentials Required
Integrating Salesforce Marketing Cloud with SaaS Management
Salesforce Marketing Cloud Contact Usage
API Endpoint

Information Stored

The following table describes the available integration tasks and stored data.

Available Integration Tasks

Integration Task

Information Stored

Product Consumption

Unique ID
Occurred at
Used Quantity

Note:The information stored is subject to change as enhancements are made to the product.

Minimum Permissions Required

Administrator

Scopes Required

Scopes Required

Scopes Required

Description

Integration Task Name

Data Extension: Read, Write

The Data Extension read permission just grants access to the container, relationships, filters, and shared DE folders. The Data Extension write permission grants access to the data.

Product Consumption

Authentication Method

OAuth2 with Client Credentials. For details, refer to Create an OAuth 2.0 API Integration in Enhanced Packages.

Prerequisite Salesforce Marketing Cloud Configurations

The following tasks are required to configure your Salesforce Marketing Cloud account.

Creating a Contacts Counts Report in Salesforce Marketing Cloud
Creating a Data Extension for Your Contacts Counts Report
Building an Automation to Import Contacts Counts Report Data in Your Data Extension

Creating a Contacts Counts Report in Salesforce Marketing Cloud

Create a Contacts Counts report to retrieve and display the total number of billable contacts in your Salesforce Marketing Cloud account.

Important:To complete this task, the Salesforce Marketing Cloud administrator role is required.

To create a Contacts Counts Report in Salesforce Marketing Cloud:

1. From a web browser, go to your Salesforce Marketing Cloud instance.
2. Log in using your admin credentials.
3. On the page header of your instance, click the business unit profile icon. Select the top-level parent business unit so that your Contacts Counts report includes data for both the parent business unit and all corresponding child business units.
4. From the list of available Salesforce Marketing Cloud applications, click the Analytics Builder app icon, and then select Reports. The Reports app overview opens.
5. In the Report Catalog section, click View Catalog.
6. From the Reports Catalog, search for Contacts Counts and click Create. The Create Report dialog box opens.
7. In the dialog box, select the time period that you want to retrieve and display data for from the Date Range list. The default value is Last 30 Days.

Tip:Set the Date Range value to the last 7 Days to ensure consistent contacts counts between SaaS Management and your Salesforce Marketing Cloud Contacts Counts report.

8. Click Submit. Your Salesforce Marketing Cloud instance generates the report and displays the results on the Results: Contacts Counts page.
9. On the Results: Contacts Counts page, click Save. The Save Report dialog box opens.
10. In the Save Report dialog box, complete the following fields.

Save Report dialog box field

Description

Report Name

Name of the report.

Report Source

Source of the report. This field is automatically set to Contacts Counts.

Description

Description of the report.

11. Click Save.
12. Create a schedule to run the Contacts Counts report automatically.
a. On the page header of the Reports app, select the Overview tab to return to the Reports app overview.
b. From your list of reports, select your newly created Contacts Counts report. The report details open.
c. In the Schedule Options section, click Edit. The Edit Schedule Options dialog box opens.
d. In the Edit Schedule Options dialog box, complete the following fields and click Save.

Edit Schedule Options dialog box - Schedule Options

Description

Start

Date and time from which you want to start running the report.

Time Zone

Time zone in which the report is being scheduled.

Repeat

Frequency at which you want to run the report. Configure the report to run Daily to see more accurate data in the SaaS Management user interface.

End

Date on which you want to stop running the report.

Edit Schedule Options dialog box - Delivery Options

Description

Format

File type and file extension in which you want to receive the report results. Select Data (.csv).

Location

Location in which you want to save or share the report. Set this field to Save report for FTP and complete the following fields:

Report Name: File name of the report, excluding the file extension. Take note of this file name for later use.
Unique Option: Option to create a new report record instead of replacing the existing report record in SFTP. Leave this check box unselected.
FTP Location: Location of your Salesforce Marketing Cloud FTP files. Select ExactTargetEnhancedFTP so that the report is saved to your SFTP (SSH File Transfer Protocol) Reports folder.

Creating a Data Extension for Your Contacts Counts Report

Create a data extension to store your Contacts Counts report data on your Salesforce Marketing Cloud instance.

Important:To complete this task, the Salesforce Marketing Cloud administrator role is required.

About this task

Data extensions are tables that contain attributes representing your report data.

Important:Do not set up this data extension as a population. If you set it up as a population, every record in the data extension will contribute to the contact count.

To create a data extension for your Contacts Counts Report

1. On the page header of your Salesforce Marketing Cloud instance, hover over the Salesforce icon to display the list of available Salesforce Marketing Cloud applications.
2. Click the Audience Builder app icon and then select Contact Builder. The Contact Builder app opens.
3. Select the Data Extensions tab and then click Create. The Create New Data Extension dialog box opens.
4. In the Properties step, complete the following fields.

Properties field

Description

Creation Method

Method in which you want to create the data extension. Select Create from New.

Name

Name of the data extension.

External Key

Optional key that uniquely identifies the data extension. You can either use the predefined key or enter a key of your choice.

Description

Description of the data extension.

Type

Type of data extension. This field is automatically set to Standard.

Location

Location in which you want store the data extension. This field is automatically set to Data Extensions. Click Change Location to select a different location.

Is Sendable?

Option indicating whether the data extension can be sent to your subscribers.

5. Click Next.
6. In the Data Retention Policy step, set the Retention Setting field to Off.
7. Click Next.
8. In the Attributes step, add the attributes that you want to include in the data extension. Attributes are used to map and import data from a report to a data extension. You must create an attribute for each report column that you want to import data from. Each attribute name must exactly match the corresponding report column name.

For the Salesforce Marketing Cloud integration, attributes for the following Contacts Counts report columns are required:

Count_Date 
Total_Distinct_Contacts_Count 
Flag 

Attributes for all other Contacts Counts report columns are optional.

For each attribute that you want to add, complete the following fields.

Attributes field

Description

Primary Key

Option for the attribute to include a unique identifier for all records in the data extension.

This option must be enabled for the Count_Date attribute.

Name

Name of the attribute. This name must exactly match the corresponding report column name.

Data Type

Data type of the attribute.

Required

Option that indicates whether the attribute requires a value for each record in the data extension.

Length

Maximum number of characters allowed in the attribute value.

Default Value

Optional default value for the attribute.

For the Flag attribute, set the default value to 1.

Note:Do not enter a default value for any attributes that are assigned as a primary key.

9. Click Complete. The Data Extension Created dialog box opens.
10. In the dialog box, click OK.

Building an Automation to Import Contacts Counts Report Data in Your Data Extension

Create an automation to automatically import Contacts Counts report data into your data extension after the report is generated.

Important:To complete this task, the Salesforce Marketing Cloud administrator role is required.

To build an automation to import Contacts Counts Report data in your data extension

1. On the page header of your Salesforce Marketing Cloud instance, hover over the Salesforce icon to display the list of available Salesforce Marketing Cloud applications.
2. Click the Journey Builder app icon and then select Automation Studio. The Automation Studio app overview opens.
3. Click New Automation. The workflow for the new automation opens.
4. Create a scheduled automation by dragging the Schedule icon from the Starting Sources section of the left menu pane to the Starting Source section of the workflow canvas.
5. Define a schedule for the automation.
a. In the Starting Source section of the workflow canvas, click Configure. The Define Schedule dialog box opens.
b. In the Define Schedule dialog box, complete the following fields.

Define Schedule dialog box field

Description

Start Date

Date and time from which you want to start running the automation.

Time Zone

Time zone in which the automation is being scheduled.

Repeat

Frequency at which you want to run the automation. Configure the automation to run after the Contacts Counts report is generated. Set the frequency of automation to run Daily to see more accurate data in the SaaS Management user interface.

Tip:If you configure the automation to run on the same day that the report is generated, select a start time that allows enough time for the report to finish generating. It is recommended to set a start time of at least two hours after the report start time.

End

Number of times that the automation can run until the automation schedule ends. If you do not want the automation schedule to end, set this field to Never.

6. Add a script activity to execute the Server-Side JavaScript for all activities that require it.
a. In the Activities section of the left menu pane, drag the Script icon into the workflow canvas. The script activity becomes the first step of the automation workflow.
b. Click Choose on the script activity step. The Choose Script Activity dialog box opens.
c. Click Create New Script Activity. The Create New Script Activity dialog box opens.
d. In the Properties step, complete the following fields.

Properties field

Description

Name

Name of the script activity.

External Key

Optional key that uniquely identifies the script activity. You can either use the predefined key or enter a key of your choice.

Folder Location

Location in which you want to store your scripts. This field is automatically set to Scripts. Click Choose...to select a different location.

Description

Description of the script activity.

e. In the following Server-Side Javascript, replace *<data-extension-name>* with the Data-Extension name created in the step Creating a Data Extension for Your Contacts Counts Report and then copy-paste the script into the Server-Side JavaScript text box.

<script runat="server">

var rows = Platform.Function.DeleteData('*<data-extension-name>*',['Flag'],['1']);

</script>

f. Click Validate Syntax to verify that the Server-Side JavaScript syntax is valid.
g. Click Next.
h. In the Summary step, verify that the script activity configuration is correct. Then click Finish.
7. Add a data extract activity to copy the Contacts Counts report from the SFTP Reports folder to the SFTP Import folder.

The Salesforce Marketing Cloud instance uses the SFTP Import folder to locate and import report data into your data extensions. To enable your instance to import data from the Contacts Counts report into the corresponding data extension, you must copy the report to the SFTP Import folder.

a. In the Activities section of the left menu pane, drag the Data Extract icon into the workflow canvas. The data extract activity becomes the second step of the automation workflow.
b. Click Choose on the data extract activity step. The Choose Data Extract Activity dialog box opens.
c. Click Create New Data Extract Activity. The Create New Data Extract Activity dialog box opens.
d. In the Properties step, complete the following fields.

Properties field

Description

Name

Name of the data extract activity.

External Key

Optional key that uniquely identifies the data extract activity. You can either use the predefined key or enter a key of your choice.

File Naming Pattern

File name of the Contacts Counts report that you want to extract data from. This name must exactly match the file name of the Contacts Counts report that you created in Creating a Contacts Counts Report in Salesforce Marketing Cloud, including the file extension.

Extract Type

Data extract method. Set this field to Enhanced FTP File Move and Copy.

Description

Description of the data extract activity.

e. Click Next.
f. In the Configuration step, complete the following fields.

Configuration field

Description

Input Folder

Location in which you have saved the Contacts Counts report. Enter \reports\.

Output Folder

Location that you want to copy the report to. Enter \Import\.

Copy to Folder

Option to copy instead of move the report from the input folder to the output folder. This option enables you to keep the report in both locations. Select the check box to enable this option.

g. Click Next.
h. In the Summary step, verify that the data extract activity configuration is correct. Then click Finish.
8. Add an import file activity to import the Contacts Counts report data into the data extension.
a. In the Activities section of the left menu pane, drag the Import File icon into the workflow canvas. The import file activity becomes the third step of the automation workflow.
b. On the import file activity step, click Choose. The Choose Import File Activity dialog box opens.
c. Click Create New Import File Activity. The Create New Import File Activity dialog box opens.
d. In the Activity Info step, complete the following fields.

Activity Info field

Description

Name

Name of the import file activity.

Description

Description of the import file activity.

External Key

Optional key that uniquely identifies the import file activity. You can either use the predefined key or enter a key of your choice.

Send notification email to

Email address to which you want to send notifications when an import completes.

If you specify an email address, a notification email that contains the number of inserted and updated rows is sent to that address upon successful import.

Note:The notification email will contain an Invalid Field Count validation error due to the presence of empty lines in the imported CSV file. These empty lines appear automatically when you save the report to FTP. However, they have no impact on the integration.

e. Click Next.
f. In the Import File step, complete the following fields.

Import File field

Description

File Location

Location of the Contacts Counts report that you want to import data from. Select ExactTarget Enhanced FTP.

File Naming Pattern

File name of the Contacts Counts report that you want to import data from. This name must exactly match the file name of the Contacts Counts report that you created in Creating a Contacts Counts Report in Salesforce Marketing Cloud, including the file extension.

Date Format

Format in which you want to display the date and time of the report data.

Delimiter

Format in which you want to separate each report record. Select comma to separate each record with a comma.

If you want to allow the use of double quotes to separate each record, enable the Respect double quotes (") as a text delimiter option.

Bad Data Behavior

Option to skip rows with bad data. Select the check box to enable this option.

g. Click Next.
h. In the Destination step, search for and select the data extension that you created in Creating a Data Extension for Your Contacts Counts Report.
i. Click Next.
j. In the Mapping step, select the options to Add and Update and Mapping By Header.
k. Click Next.
l. In the Review step, verify that the import file activity configuration is correct. Then click Finish.
9. Click Save. The Save Automation dialog box opens.
10. In the Save Automation dialog box, complete the following fields.

Save Automation dialog box field

Description

Name

Name of the automation.

Description

Description of the automation.

External Key

Optional key that uniquely identifies the automation.

Location

Location in which you want to save the automation.

11. Click Save.
12. In the Starting Source section of the workflow canvas, click Active. The Activate Schedule Confirmation dialog box opens.
13. In the dialog box, activate the automation schedule by clicking Activate.

Credentials Required

Client ID
Client Secret
SOAP Base URI
Data Extension Name

Integrating Salesforce Marketing Cloud with SaaS Management

To integrate Salesforce Marketing Cloud with SaaS Management, perform the following steps.

To integrate Salesforce Marketing Cloud with SaaS Management:

1. Add the Salesforce Marketing Cloud application in SaaS Management. Refer to Adding an Application.
2. To obtain the Salesforce Marketing Cloud Client ID, Client Secret, and ServiceURL values:
a. Log in to the Salesforce Marketing Cloud portal with your admin username and password.
b. Click your profile in the upper-right corner and click Setup.
c. From the Platform Tools menu, select Apps.
d. From the Installed Packages menu, click the installed package.
e. Obtain the values for:
Client ID 
Client Secret 
SOAP Base URI. The SOAP Base URI value is used for the SaaS Management ServiceURL field.
3. Enter the required Salesforce Marketing Cloud Data Extension Name. To obtain this information:
a. On the page header of your Salesforce Marketing Cloud instance, hover over the Salesforce icon to display the list of available Salesforce Marketing Cloud applications.
b. Click the Audience Builder app icon and select Contact Builder.
c. Select the Data Extensions tab and note the Data Extension Name.
4. In the SaaS Management Add Application screen, enter the following information in the Salesforce Marketing Cloud fields:
Client ID 
Client Secret 
SOAP Base URI 
Data Extension Name 
5. Click Authorize. The following Salesforce Marketing Cloud tabs will display: Contact Usage, Licenses, and Integration.

For further information on these tabs, refer to:

Salesforce Marketing Cloud Contact Usage for the Contacts Usage tab
Licenses Tab
Integration Tab

Salesforce Marketing Cloud Contact Usage

The Contacts Usage tab displays your organization’s Salesforce Marketing Cloud Contacts’ entitlement and usage to control spend by minimizing contact usage overage fees.

The following prerequisites are required to display data in the Contacts Usage tab:

Obtain a copy of your Salesforce Marketing Cloud contract
Complete the Prerequisite Salesforce Marketing Cloud Configurations
Complete the tasks for Integrating Salesforce Marketing Cloud with SaaS Management
Complete the License Details in the Salesforce Marketing Cloud Licenses Tab.
Enter your usage details from your Marketing Cloud contract in the Usage Details Slideout

The Contacts Usage tab is further explained in the following sections. The Application Details link in the Contacts Usage tab is further explained in Application Details Slideout.

Usage Details Slideout
Contacts Usage Tab
Salesforce Marketing Cloud Contact Usage Scenarios

Usage Details Slideout

To better track your usage data, enter usage details from your Marketing Cloud contract in the Usage Details slideout. To access the Usage Details slideout, click the Enter Usage Details button in the Usage Details tile of the Contacts Usage tab. The table below explains how to complete the Contact Usage Details slideout. Once this information is entered, the Contacts Details tile is displayed in the Contacts Usage tab.

Contact Usage Details Slideout Features

Feature

Description

Start Date

Choose the start date to calculate your average monthly growth.

Tip:We recommend using the very beginning date that you start using contracts.

End Date

Choose the end date to calculate your monthly allowance.

Tip:We recommend using your order end date.

Quantity of purchased contracts

Enter the total number of contacts you have purchased, including the base-contacts and the additional purchased contacts.

Overage rate

Calculates the overage cost when you have used more contacts than purchased.

Associated license

In this dropdown list, you have the option to associate the contact usage to a license you created in the Licenses Tab.

Note:If no license is created in the Licenses Tab, this dropdown list is blank.

Contacts Usage Tab

The following table explains the information provided in the Contacts Usage tab. To display all the information in this tab requires prior entry in the Usage Details Slideout

Contacts Usage Tab Features

Feature

Description

Used

The number for the total Used in the Usage tile is pulled in automatically after integrating with SaaS Management.

Note:Usage data is updated when the latest Contacts Counts report is available in Salesforce Marketing Cloud. To create a Contacts Counts report, refer to Creating a Contacts Counts Report in Salesforce Marketing Cloud.

Remaining

After the purchased contact quantity is entered in the Usage Details slideout, the number of Remaining contacts (Total purchased contacts - Total used) displays in the Usage tile.

Example: On the first day of integration, SaaS Management pulls in 600 used contacts. 1000 purchased contacts are entered in the Usage Details slideout. Therefore, the remaining contacts is 1000 - 600 = 400.

% Used

After the purchased contact quantity is entered in the Usage Details slideout, the % Used displays in the Usage tile.

Average Monthly Growth

The Average Monthly Growth number represents how many contacts you are currently using on a monthly basis. To calculate this number, you need to create and update your Salesforce Marketing Cloud Contact Counts report. For details, refer to Creating a Contacts Counts Report in Salesforce Marketing Cloud.

Average Monthly Growth = (Total used contacts from the latest Contacts Counts report / days passed since start date) x 30 days 

Average Monthly Growth Example:

SaaS Management pulls in 10,000 used contacts from the latest Contacts Counts report in Salesforce Marketing Cloud.
100 days have passed since the Start date you selected in the Usage Details slideout.

Average monthly growth: (10,000 contacts/100 days) x 30 days = 3,000 contacts

Note:The Average Monthly Growth and Monthly allowance numbers are updated when the Salesforce Marketing Cloud Contacts Counts report is updated.

Monthly Allowance

The Monthly Allowance is the maximum number of contacts you can use based on the remaining contacts and remaining days until the end date without overusing your contacts.

Monthly Allowance = (Total remaining contacts/days remaining until end date) x 30 days 

Monthly Allowance Example:

SaaS Management pulls in 10,000 used contacts from the latest Contacts Counts report in Salesforce Marketing Cloud.
You entered 15,000 in the Quantity of purchased contacts field of the Usage Details slideout.
You have 5,000 contacts remaining.
There are 50 days remaining until the End date you selected in the Usage Details slideout.

Monthly Allowance: (5,000 contacts/50 days) x 30 days = 3,000 contacts

Note:The Average Monthly Growth and Monthly Allowance numbers are updated when the Salesforce Marketing Cloud Contacts Counts report is updated.

Overused

Number of overused contacts = Total used contacts - Total purchased contacts 

Overused Example:

SaaS Management pulls in 1104 contacts.
You entered 1000 in the Quantity of purchased contacts field of the Usage Details slideout.

Number of overused contacts: 1104 - 1000 = 104 contacts

Overage Cost

Total overage cost = Overage rate x (Total used contacts - Total purchased contacts) 

Overage Cost Example:

SaaS Management pulls in 1104 contacts.
You entered 1000 in the Quantity of purchased contacts field of the Usage Details slideout.
You entered $1 in the Overage rate field of the Usage Details slideout.
Number of overused contacts = 104 contacts (see Overused example above).

Total overage cost: $1 x 104 contacts = $104

Usage Over Time

This graph displays the count of your total used contacts from the Salesforce Marketing Cloud Contacts Counts report.

Click the Calendar icon in the graph’s upper-right corner to select a date range of 90 days, 1 year, or 2 years for displaying contact usage over time.

Note:When Salesforce Marketing Cloud is first integrated with SaaS Management, the first bar of the Usage Over Time trending graph is populated with the current usage count. You will be able to compare your total used contacts vs total purchased contacts after you enter your usage details from your Marketing Cloud contract in the Usage Details Slideout .

Salesforce Marketing Cloud Contact Usage Scenarios

This section explains how Salesforce Marketing Cloud contact usage data appears based on the following scenarios:

When Salesforce Marketing Cloud is added without contact usage details
Savings Mode: Contacts usage is less than the quantity of purchased contacts at the end date
Warning Mode: Monthly contacts usage is higher than the monthly allowance
Overage Cost Incurred: Contacts were overused before the end date

When Salesforce Marketing Cloud is added without contact usage details

In this scenario, only the following contact usage data displays in the Contacts Usage tab:

The Usage Over Time trending graph is populated with the current usage count pulled in from the Salesforce Marketing Cloud Contacts Counts report. Over time, when the Salesforce Marketing Cloud Contacts Counts report is updated, the Usage Over Time trending graph is updated and additional bars are added.
The Used count in the Usage tile is populated with the current usage count pulled in from the Salesforce Marketing Cloud Contacts Counts report.

Note:A dash “-” for other data (percentage used, Remaining, Avg. Monthly Growth, Monthly Allowance) indicates the contact usage data is unavailable and requires entry by your organization. For details, see the Usage Details Slideout.

Savings Mode: Contacts usage is less than the quantity of purchased contacts at the end date

This scenario occurs when ALL the following contacts usage factors are present:

Total used contacts amount is less than the quantity of purchased contacts entered in the Usage Details slideout.
Average monthly growth is less than the monthly allowance.
No overage cost is incurred.

Warning Mode: Monthly contacts usage is higher than the monthly allowance

This scenario occurs when the following contacts usage factors are present:

Current monthly usage growth is higher than the monthly allowance.
A high usage rate for the % Used in the Usage tile is observed in the Contacts Details tile.

Note:The high usage rate warning may go away based on the next Salesforce Marketing Cloud Contacts Counts report.

As a result of this scenario, a warning at the top of the Contacts Usage tab appears: "Your current monthly usage growth is higher than the monthly allowance, you may run out of contacts before the end date."

Overage Cost Incurred: Contacts were overused before the end date

This scenario occurs when the following contact usage factors are present:

The total Used count exceeds the Quantity of purchased contracts before the End Date entered in the Usage Details slideout.
The Usage tile displays:
Percentage used
Number of overused contacts
Overage cost
You ran out of contacts before the End Date listed in the Contacts Details tile.

As a result of this scenario, a red banner appears at the top of the Contacts Usage tab: "You’ve used ‘xxx’ more contacts than you’ve purchased. You’ll pay an overage cost of $’xxx’."

API Endpoint

Product Consumption

https://<ServiceURL>.soap.marketingcloudapis.com/Service.asmx