Marketing Cloud

INTRODUCTION

The Marketing Cloud module adds connectivity from Drupal to Salesforce Marketing Cloud. This allows the module builders to do things like send SMS's, or emails to individual users from a user page, send to all users, or from the results of a view on a new page available form the menus.

All Marketing cloud API calls are defined in this module, with JSON Schema to validate messages. This allows site builders to easily create plugins to send to SalesForce Marketing Cloud, and module builders to use this as a base module and use the API calls out of the box as a service, without having to worry about token authentication since the services already have this functionality.

The SalesForce API documentation is often inaccurate and contradictory. So in creating the JSON schema, I have made an assumption that the sample requests are more accurate than the object notation. 

In addition, there were cases where the URL could contain parameters with an empty body, or a different URL, with parameters in a JSON payload. In these cases, I followed the pattern of JSON payload and uniform URL.

For a full description of the module, visit the project page:

• https://drupal.org/project/marketing_cloud

To submit bug reports and feature suggestions, or to track changes:

• https://drupal.org/project/issues/marketing_cloud

REQUIREMENTS 

composer

See https://www.drupal.org/docs/8/extending-drupal-8/installing-modules-comp... for notes on contrib module's composer dependencies 

Install composer_manager module (https://www.drupal.org/project/composer_manager), or run the following commands from with docroot:

$ composer require drupal/marketing_cloud

If composer does not automatically install the following json-schema dependencies, also run:

$ composer require swaggest/json-schema

Then enable the module:

$ drush pm-enable -y marketing_cloud
$ drush cr

INSTALLATION

• See https://www.drupal.org/docs/8/extending-drupal-8/installing-drupal-8-mod... for information on installing modules.

• Enable the following module:

  • marketing_cloud - the base module for marketing cloud

• Enable any of the sub-modules to add functionality to call the SF API's, such as SMS, Messaging, push etc.

  • Marketing Cloud Address

  • Marketing Cloud Assets

  • Marketing Cloud Campaigns

  • Marketing Cloud Contacts

  • Marketing Cloud Data Events

  • Marketing Cloud Interaction

  • Marketing Cloud Messaging

  • Marketing Cloud Platform

  • Marketing Cloud Push

  • Marketing Cloud SMS

  • Marketing Cloud Workflow Teams

CONFIGURATION

General

Navigate to Admin » Configuration » Web Services » Marketing Cloud:

• Client ID - Your Salesforce Marketing Cloud Client ID.
• Client Secret - Your Salesforce Marketing Cloud Client Secret.
• Scope - A space-separated list of data-access permissions for your application. Review REST API Permission IDs and Scopes for a full list of permissions.
• Account ID - Account identifier, or MID, of the target business unit. Use to switch between business units. If you don't specify account_id, the returned access token is in the context of the business unit that created the integration.
• Validate JSON - Turn this off if there are issues with the validation or you want to increase the request speed.
• Do not send API request - useful for local unit testing or seeing the final request sent to Marketing Cloud.
• Salesforce API URL base - Do not edit this, it defines the API base URL.
• Salesforce auth token request URL - Do not edit this, it defines the API token request URL.
• Salesforce auth token request version - Salesforce currently has two versions of token request (V1 & V2). All new Marketing cloud instances on Salesfoce will use V2, but existing accounts will use V1. This allows you to select the correct auth type.
• TTL for the Marketing cloud token - Life of the marketing Cloud token in seconds. MC default is 20 minutes (1200s)
• Seconds to wait before token re-request - If a token request is in progress, wait n seconds.
• Max login attempts - The maximum attempts at a valid token request.
• Reset Token - reset the token if the system becomes stuck. This should never be required, but has been included as a fail-safe feature.

Endpoints & schema

After enabling any Marketing Cloud sub-modules, navigate to Admin » Configuration » Web Services » Marketing Cloud. The enabled module will appear on a tab.

Expand ENDPOINT DEFINITIONS, and the API call that you want to edit. Here you can edit the method, endpoint URI (beginning with a trailing slash) and the Json Schema.

This has been created to allow quick adjustment if Salesforce change their endpoints without notice saving you from having to wait for a module update, and thus not temporarily lose functionality.

Endpoints and schema are the same for auth V1 and V2.

Roles

Configure user permissions in Administration > People > Permissions:

Administer Marketing Cloud

Gives permission for the user to administer Marketing Cloud settings.

Users in roles with the "Administer Marketing Cloud" permission will see
the Marketing Cloud configure link in the admin > configure page.

JSON STANDARDS

The Json-Schema validation accepts versions 4,6 & 7.

SalesForce API's are quite forgiving. They allow uc_first and lc_first keys, and they allow booleans to be 0/1/true/false/"true"/"false".

At the same, Json Schema is case sensitive, and provides a convenient boolean type. So the following standards now follow for all JSON payloads:

• Camel case is used for all keys.

• Lower case first is used for all keys.

• Boolean types must be type booleans (not 0/1 or textual).

CUSTOMISATION

See the Marketing Cloud Example module for examples of creating a webform plugin, to trigger an SMS on form submission.

USING THE SERVICES

Instantiate the service that you require from the sub-module, and call it in the usual manner.

Some API calls also require URL params. These are passed in as separate values to the JSON. Please inspect the service contract for details.

$date = new \DateTime();
$date->modify('-1 day');
$messageId = 'F00b4r';
$data = [
  'mobileNumbers' => [1234567890],
  'override' => TRUE,
  'messageText' => 'Hello World!',
  'sendTime' => $date->format('Y-m-d H:i'),
];

$response = \Drupal::service('marketing_cloud_sms.service')
  ->postMessageToNumber($messageId, $data);

if (!$response) {
  // Handle error.
} else {
  // Handle success.
}

MARKETING CLOUD EXAMPLE

This creates a webform with a custom handler. This handler uses the service in marketing_cloud_sms to send an SMS request to marketing cloud.

API SERVICES RETURN VALUES

The service functions all return a standard FALSE on a failure or the result from Salesforce. In some use cases, the API returns an error object with a 200 response. Your code should guard against this.

TROUBLESHOOTING

• If messages are not sent:

  • Check that your Client ID/Secret are correct.

  • Check in Watchdog and SalesForce log for any error messages.

  • There are 2 versions of the IP address for the token request. New Marketing Cloud accounts will automatically be using the new version (v2), and the module's default token request is for v1. You can edit the token request URL at Admin » Configuration » Web Services » Marketing Cloud. 

• SalesForce complains that there are missing fields or an invalid message.

  • Check the Watchdog logs to see if there are any messages about invalid or missing fields.

  • There may have been an API change at the SalesForce end. Check the docs at https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/r...

    • If you are able to, you can edit the JSON Schema at Configuration » Web Services » Marketing Cloud » Marketing Cloud <SMS, Contacts, etc>

    • Raise a support ticket at https://www.drupal.org/project/issues/marketing_cloud

FAQ

• Why are messages are not sent immediately?

  • Salesforce works on batch messaging, and has  a high volume of message requests, so is unable to send immediately.

• To use the marketing cloud services (see marketing_cloud_example to see a working example):

  • Enable marketing_cloud, and any of the API services that you want to use, such as marketing_cloud_push or marketing_cloud_messaging

  • Create an array for the JSON data in the call. 

  • $response = \Drupal::service('marketing_cloud.<service_name>')-><message_function>($data);

    • In some cases, extra parameters are required for the URL. As a standard, extra URL parameters occur after the JSON data object in the service contract.

      •  Example: \Drupal::service('marketing_cloud_sms.service')->postMessageToNumber($messageId, $data);

  • The login and session token will all be taken care of by marketing_cloud and its configuration.