Commit 0813111b authored by john_a's avatar john_a
Browse files

initial commit

parents
# INTRODUCTION #
The Marketing Cloud module adds connectivity from users to Salesforce Marketing Cloud. This allows the site administrators to 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 the project, 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 is a base module and use the API calls out of the box as a service, along with the token authentication service that it uses and provides.
The SalesForce API documentation if often inaccurate 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 ###
* telephone (https://www.drupal.org/docs/8/core/modules/telephone/overview)
#### composer
See https://www.drupal.org/docs/8/extending-drupal-8/installing-modules-composer-dependencies 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:
```javascript
$ composer require drupal/marketing_cloud
```
If composer does not automatically install the following json-schema dependencies, also run:
```javascript
$ composer require league/json-guard
$ composer require league/json-reference
```
Then enable the module:
```javascript
$ drush pm-enable -y marketing_cloud
$ drush cr
```
### INSTALLATION ###
* See https://www.drupal.org/docs/8/extending-drupal-8/installing-drupal-8-modules for information on installing modules.
* Enable the following modules:
* 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
### CONFIGURATION ###
* Configure user permissions in Administration » People » Permissions:
* #### Administer Marketing Cloud ####
* The top level administration permissions for The Marketing Cloud module. This will allow the user to be able to edit Client ID/Secret, the endpoint definitions and JSON schemas for each API call.
* Configure the Salesforce Client ID and Client Secret in Configuration » Web Services » Marketing Cloud
* Configure any enabled sub-module endpoints at Configuration » Web Services » Marketing Cloud » Marketing Cloud <SMS, Contacts, etc>. This has been created to allow quick adjustment if Salesforce change their endpoints without while you to wait for a module update, and thus not temporarily lose functionality.
### JSON STANDARDS
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).
### CUSTOMIZATION ###
* See the Marketing Cloud Example module for examples of creating a webform plugin, to trigger an SMS on form submission.
### TROUBLESHOOTING ###
* If messages are not sent:
* Check that your Client ID/Secret are correct.
* Check in Watchdog and SalesForce log for any error messages.
* 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/routes.html
* 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);
* The session login and token will all be taken care of by marketing_cloud and its configuration.
### CONTACT ###
Current maintainers:
* John Avery (john_a) - https://drupal.org/user/2573976
This project has been sponsored by:
* #### The Playhouse Group ####
Specializing in strategy, design, mentoring and implementation of Drupal, Magento and Salesforce powered sites. Visit https://www.theplayhousegroup.com for more information.
* #### Salesforce ####
We’re the innovative company behind the world’s #1 CRM platform that employees can access entirely over the Internet — there’s no infrastructure to buy, set up, or manage — you just log in and get to work. And now our new Lightning Platform gives you the fastest, most complete way to put your customers at the center of everything you do. Visit https://developer.salesforce.com/docs/atlas.en-us.noversion.mc-apis.meta/mc-apis/index-api.htm for more information.
{
"name": "drupal/marketing_cloud",
"description": "Provides Drupal 8 integration with Marketing Cloud",
"type": "drupal-module",
"homepage": "http://drupal.org/project/marketing_cloud",
"authors": [
{
"name": "John Avery",
"homepage": "https://www.drupal.org/u/john_a"
}
],
"support": {
"issues": "https://www.drupal.org/project/issues/marketing_cloud",
"irc": "irc://irc.freenode.org/drupal-contribute",
"source": "https://cgit.drupalcode.org/marketing_cloud"
},
"license": "GPL-2.0+",
"require": {
"league/json-guard": "^1.0",
"league/json-reference": "^1.0"
}
}
client_id: ""
client_secret: ""
validate_json: true
validate_schema: false
do_not_send: false
base_url: "https://www.exacttargetapis.com"
request_token_url: "https://auth.exacttargetapis.com/v1/requestToken"
login_attempts_max: 3
request_token_wait: 10
token: "0"
requesting_token: false
# Schema for the configuration files of the marketing_cloud module.
marketing_cloud.settings:
type: config_object
label: 'Marketing Cloud settings'
mapping:
client_id:
type: string
label: 'Client ID'
client_secret:
type: string
label: 'Client Secret'
validate_json:
type: boolean
label: 'Validate JSON'
do_not_send:
type: boolean
label: 'Do not send'
validate_schema:
type: boolean
label: 'Validate Schema'
request_token_url:
type: string
label: 'Salesforce auth token request URL'
base_url:
type: string
label: 'Salesforce API URL base'
login_attempts_max:
type: integer
label: 'Max login attempts'
request_token_wait:
type: integer
label: 'Seconds to wait before token re-request'
token:
type: string
label: 'Salesforce auth token'
requesting_token:
type: boolean
label: 'Salesforce auth token request in progress'
name: Marketing Cloud
type: module
description: Gives Drupal the ability to communicate with Marketing Cloud
core: 8.x
package: Marketing Cloud
configure: marketing_cloud.settings
marketing_cloud.settings:
title: Marketing Cloud
description: Configure the Marketing Cloud module
parent: system.admin_config_services
route_name: marketing_cloud.settings
marketing_cloud.settings:
title: Marketing Cloud
description: Configure the Marketing Cloud module
route_name: marketing_cloud.settings
base_route: marketing_cloud.settings
administer_marketing_cloud:
title: 'Administer Marketing Cloud'
description: 'Gives permission for the user to administer Marketing Cloud settings'
restrict access: true
marketing_cloud.settings:
path: '/admin/config/marketing_cloud'
defaults:
_form: '\Drupal\marketing_cloud\Form\MarketingCloudSettings'
_title: 'Marketing Cloud'
requirements:
_permission: 'administer_marketing_cloud'
services:
marketing_cloud.service:
class: Drupal\marketing_cloud\MarketingCloudService
# Submodules
These define distinct API's in the Salesforce API, e.g. mobile connect, contacts, etc.
# TODO
* the user field_mobile_number current uses the module_number field module. This should be updated to use the international_phone module when they have fixed the jquery bug (see https://www.drupal.org/project/international_phone/issues/2927093)
# Marketing Cloud address API
Enables the address API in the Marketing Cloud.
# Requirements #
* marketing_cloud
definitions:
validate_email:
method: "post"
endpoint: "/address/v1/validateEmail"
schema: |
{
"$schema": "http://json-schema.org/draft-06/schema#",
"title": "Validate Email",
"description": "Validates an email by specifying the email address and validators to be used in the request body of the HTTP POST. You can use more than one validator in the same call.",
"type": "object",
"properties": {
"email": {
"type": "string"
},
"validators": {
"type": "array"
}
},
"additionalProperties": false
}
marketing_cloud_address.settings:
type: config_object
label: Marketing Cloud Address settings
mapping:
definitions:
type: sequence
sequence:
type: mapping
mapping:
method:
type: string
label: Method
endpoint:
type: string
label: Endpoint
schema:
type: string
label: Schema
name: Marketing Cloud Address
type: module
description: Gives drupal the ability to send address message requests to Marketing Cloud
core: 8.x
package: Marketing Cloud
configure: marketing_cloud_address.settings
dependencies:
- marketing_cloud
marketing_cloud_address.settings:
title: Address Endpoints
description: Configure the Marketing Cloud Address module
parent: marketing_cloud.settings
route_name: marketing_cloud_address.settings
marketing_cloud_address.settings:
route_name: marketing_cloud_address.settings
title: Address Endpoints
description: Configure the Marketing Cloud Address module
base_route: marketing_cloud.settings
marketing_cloud_address.settings:
path: /admin/config/marketing_cloud/address
defaults:
_form: \Drupal\marketing_cloud_address\Form\AddressSettings
_title: Marketing Cloud Address settings
requirements:
_permission: administer_marketing_cloud
services:
marketing_cloud_address.service:
class: Drupal\marketing_cloud_address\AddressService
<?php
/**
* @file
* Contains \Drupal\marketing_cloud_message\MessageService.
*/
namespace Drupal\marketing_cloud_address;
use Drupal\marketing_cloud\MarketingCloudService;
/**
* Class AddressService
*
* For all of the API service calls, a correct JSON data payload is expected.
* This is then validated against the JSON Schema. This approach minimises
* any short-term issues with changes in the SF API, provides a sanitized
* interface to send API calls and leaves flexibility for any modules that
* want to use this as a base-module.
*
* @package Drupal\marketing_cloud
*/
class AddressService extends MarketingCloudService {
private $moduleName = 'marketing_cloud_address';
/**
* AddressService constructor.
*/
public function __construct() {
}
/**
* Sends an email to a contact.
* @see https://developer.salesforce.com/docs/atlas.en-us.noversion.mc-apis.meta/mc-apis/validateEmail.htm
*
* @param $json
* @return mixed
*/
public function validateEmail($json) {
$machineName = 'validate_email';
return $this->apiCall($this->moduleName, $machineName, $json);
}
}
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment