Commit 8d66ae61 authored by john_a's avatar john_a Committed by john_a
Browse files

Issue #2974148 by john_a: README.md files required for all base and sub modules

parent 6777e30e
# 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 ###
# Synopsis
This suite of modules supports provides services to all of the Salesforce
marketing cloud APIs, and validates all payloads against Json Schema. The
following API resources are available in sub-modules:
* Address
* Assets
* Campaigns
* Contacts
* Data Events
* Interaction
* Messages
* Platform
* Push
* SMS
This module is intended for module developers.
# Requirements
* [json-guard](https://packagist.org/packages/league/json-guard)
* [json-reference](https://packagist.org/packages/league/json-guard)
# Objectives
There are a lot of API calls available in the Salesforce Marketing Cloud API.
This module aims to provide all of them as a service in one place.
The different sections of API have been separated into sub-modules, to allow
lighter weight in Drupal and for developers using this as a sub-module, to
select which services they want to be available.
The JSON body objects in API calls can often be very complex and potentially
infinite depth. Therefore, a decision was made early on in the development to
not provide service functions that have individual input variables and then
render the JSON from that. Instead, it is up to the developer to produce the
JSON object, and the service will then validate the JSON object against the
schema to make sure that it meets minimum requirements.
The schema can be edited and validated, and Json validation can we switched
on/off in the settings.
# CONFIGURATION
* Configure user permissions in Administration > People > Permissions:
Administer Marketing Cloud
Users in roles with the "Administer Marketing Cloud" permission will see
the Marketing Cloud configure link in the admin > configure page.
* Configure Marketing Cloud
* admin > config > marketing cloud
* Client ID: The client ID from Salesforce for your app.
* Client Secret: The client secret from Salesforce for your app.
* Validate JSON: Uncheck this to prevent the module from validating any
JSON body payloads.
* Validate JSON Schema: Check this to force the module to validating the
JSON schema on every API call. This is useful for debugging.
* Do not send API request: This is only used for automated testing.
* Salesforce API URL base: The Salesforce exact target API URL.
* Salesforce auth token request URL: The URL defined by SalesForce to fetch
a valid auth token.
* Max login attempts: The URL defined by SalesForce to fetch a valid auth
token.
* Seconds to wait before token re-request: used to prevent concurrent fresh
token requests causing a stampede.
# USAGE
See the Marketing Cloud Example module for an example of creating a webform
plugin, to trigger an SMS on form submission.
For details on the Marketing Cloud API, please visit
https://developer.salesforce.com/docs/atlas.en-us.noversion.mc-apis.meta/mc-apis/routes.htm
# 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 ###
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 ###
* 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.
# Similar projects
## [Salesforce](https://www.drupal.org/project/salesforce)
This suite integrates with Salesforce by asynchronously synchronizing Drupal
entities (E.g., users, nodes, files) with Salesforce objects (E.g., contacts,
organizations, opportunities).
However it uses Salesforce OAuth, which is an entirely different endpoint to
Marketing Cloud, and requires different credentials.
# Support
Updates to the Json Schema are welcome.
A community documentation page is available on Drupal.org. Please add your
notes on solving issues and configuring the module there. Please search the
issue queue before filing an issue, and update to latest development release
to make sure your problem has not already been fixed. Issues filed using the
issue summary template will receive priority over other issues.
# Supporting organizations
* [The Playhouse Group](www.theplayhousegroup.com) - sponsor
* Specializing in strategy, design, mentoring and implementation of Drupal,
Magento and Salesforce powered sites.
### 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.
# 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 Address API
## Introduction
This module enables the address API in the Marketing Cloud as a service.
For details on individual API calls and the Marketing Cloud REST API, please
visit
https://developer.salesforce.com/docs/atlas.en-us.noversion.mc-apis.meta/mc-apis/routes.htm
## Service functions
| Name | Function |
| --------------------- | ------------------------------ |
| Validate email | validateEmail($json) |
## Requirements
* marketing_cloud
## Installation
Please see marketing_cloud README.md
## Configuration
Please see marketing_cloud README.md for general configuration.
This module will add a tab to admin > config > marketing cloud. here you can
edit the individual rest call definitions.
# Marketing Cloud assets API
Enables the assets API in the Marketing Cloud.
# Requirements #
* marketing_cloud
\ No newline at end of file
# Marketing Cloud Assets API
## Introduction
This module enables the assets API in the Marketing Cloud as a service.
For details on individual API calls and the Marketing Cloud REST API, please
visit
https://developer.salesforce.com/docs/atlas.en-us.noversion.mc-apis.meta/mc-apis/routes.htm
## Service functions
| Name | Function |
| --------------------- | ------------------------------ |
| Simple query | simpleQuery($params) |
| Advanced query | advancedQuery($json) |
| Create category | createCategory($json) |
| Get categories | getCategories($params) |
| Get category by id | getCategoryById($id) |
| Update category by id | updateCategoryById($id, $json) |
| Delete category by id | deleteCategoryById($id) |
## Requirements
* marketing_cloud
## Installation
Please see marketing_cloud README.md
## Configuration
Please see marketing_cloud README.md for general configuration.
This module will add a tab to admin > config > marketing cloud. here you can
edit the individual rest call definitions.
# Marketing Cloud campaigns API
Enables the campaigns API in the Marketing Cloud.
# Requirements #
* marketing_cloud
# Marketing Cloud Campaigns API
## Introduction
This module enables the campaigns API in the Marketing Cloud as a service.
For details on individual API calls and the Marketing Cloud REST API, please
visit
https://developer.salesforce.com/docs/atlas.en-us.noversion.mc-apis.meta/mc-apis/routes.htm
## Service functions
| Name | Function |
| --------------------------------- | ------------------------------------------- |
| Create campaign | createCampaign($json) |
| Get campaign collection | getCampaignCollection($params) |
| Get campaign | getCampaign($id) |
| Delete campaign | deleteCampaign($id) |
| Associate asset to campaign | associateAssetToCampaign($id, $json) |
| Get collection of campaign assets | getCollectionOfCampaignAssets($id) |
| Get campaign asset | getCampaignAsset($id, $assetId) |
| Unassociate asset from campaign | unassociateAssetFromCampaign($id, $assetId) |
## Requirements
* marketing_cloud
## Installation
Please see marketing_cloud README.md
## Configuration
Please see marketing_cloud README.md for general configuration.
This module will add a tab to admin > config > marketing cloud. here you can
edit the individual rest call definitions.
# Marketing Cloud contacts API
Enables the contacts API in the Marketing Cloud.
# Marketing Cloud Contacts API
## Introduction
This module enables the contacts API in the Marketing Cloud as a service.
For details on individual API calls and the Marketing Cloud REST API, please
visit
https://developer.salesforce.com/docs/atlas.en-us.noversion.mc-apis.meta/mc-apis/routes.htm
## Service functions
| Name | Function |
| ------------------------------------- | -------------------------------------------------------- |
| Get schemas collection | getSchemasCollection() |
| Create contacts | createContacts($json) |
| Update contact | updateContacts($json) |
| Create contact events | createContactEvents($json) |
| Remove contact from journey | removeContactFromJourney($json) |
| Get contacts exit status from journey | getContactsExitStatusFromJourney($json) |
| Search contacts | searchContacts($json) |
| Search attributes | searchAttributes($json) |
| Insert attribute values by id | insertAttributeValuesById($id, $json) |
| Update attribute values by id | updateAttributeValuesById($id, $json) |
| Get contact key for email addresses | getContactKeyForEmailAddresses($json) |
| Search attribute sets by name | searchAttributeSetsByName($name) |
| Search attribute groups by schema | searchAttributeGroupsBySchema($schemaId) |
| Get custom object info | getCustomObjectInfo($id) |
| Search attribute group id by schema | searchAttributeGroupIdBySchema($schemaId, $id) |
| Search attribute set definitions | searchAttributeSetDefinitions($id) |
| Search attribute set names by schema | searchAttributeSetNamesBySchema($schemaId, $name, $json) |
| Delete contacts by id | deleteContactsById($json) |
| Delete contacts by key | deleteContactsByKey($json) |
| Delete contacts by list reference | deleteContactsByListReference($json) |
## Requirements
# Requirements #
* marketing_cloud
## Installation
Please see marketing_cloud README.md
## Configuration
Please see marketing_cloud README.md for general configuration.
This module will add a tab to admin > config > marketing cloud. here you can
edit the individual rest call definitions.
# Marketing Cloud Data Events API
Enables the data events API in the Marketing Cloud.
# Marketing Cloud Data events API
## Introduction
This module enables the data events API in the Marketing Cloud as a service.
For details on individual API calls and the Marketing Cloud REST API, please
visit
https://developer.salesforce.com/docs/atlas.en-us.noversion.mc-apis.meta/mc-apis/routes.htm
## Service functions
| Name | Function |
| -------------------------------------------- | -------------------------------------------------------------------------- |
| Insert data extension rows by key | insertDataExtensionRowsByKey($key, $json) |
| Insert data extension row by key | insertDataExtensionRowByKey($key, $primaryKeys, $json) |
| Increment column value by data extension key | incrementColumnValueByDataExtensionKey($key, $primaryKeys, $column, $step) |
## Requirements
# Requirements #
* marketing_cloud
## Installation
Please see marketing_cloud README.md
## Configuration
Please see marketing_cloud README.md for general configuration.
This module will add a tab to admin > config > marketing cloud. here you can
edit the individual rest call definitions.
# INTRODUCTION #
# Marketing Cloud Example
## Introduction
The Marketing Cloud Example module provides a very simple webform plugin that
sends an SMS text to mobile numbers on form submission.
......@@ -8,13 +10,14 @@ It expects 2 fields in the webform"
* mobile_numbers
* message_text
# Requirements #
## Requirements
* marketing_cloud
* marketing_cloud_sms
* webform
* webform_ui
# Installation #
## Installation
* The SalesForce "post a message to a number" API call requires:
* A short code for an existing text message. Ensure that a message has been
......
# Marketing Cloud Interaction API
Enables the interaction API in the Marketing Cloud.
# Requirements #
## Introduction
This module enables the interaction API in the Marketing Cloud as a service.
For details on individual API calls and the Marketing Cloud REST API, please
visit
https://developer.salesforce.com/docs/atlas.en-us.noversion.mc-apis.meta/mc-apis/routes.htm
## Service functions
| Name | Function |
| -------------------------------- | ------------------------------------------------ |
| Retrieve rest discovery document | retrieveRestDiscoveryDocument() |
| Insert journey | insertJourney($json) |
| Search journeys | searchJourneys($params, $json) |
| Update journey version | updateJourneyVersion($json) |
| Create event definition | createEventDefinition($json) |
| Fire event | fireEvent($json |
| Get journey | getJourney($id) |
| Delete journey | deleteJourney($id, $versionNumber) |
| Get journey audit log | getJourneyAuditLog($id, $action, $versionNumber) |
| Get publish status | getPublishStatus($statusId) |
| Stop journey | stopJourney($id, $versionNumber) |
| Publish journey version | publishJourneyVersion($id, $versionNumber) |
## Requirements
* marketing_cloud
## Installation
Please see marketing_cloud README.md
## Configuration
Please see marketing_cloud README.md for general configuration.
This module will add a tab to admin > config > marketing cloud. here you can
edit the individual rest call definitions.
# Marketing Cloud messages API
Enables the messages API in the Marketing Cloud.
# Marketing Cloud Messages API
## Introduction
This module enables the messages API in the Marketing Cloud as a service.
For details on individual API calls and the Marketing Cloud REST API, please
visit
https://developer.salesforce.com/docs/atlas.en-us.noversion.mc-apis.meta/mc-apis/routes.htm
## Service functions
| Name | Function |
| ------------------------- | ---------------------------------------------- |
| Send email | sendEmail($triggeredSendDefinitionId, $json) |
| Get email delivery status | getEmailDeliveryStatus($key, $recipientSendId) |
## Requirements
# Requirements #
* marketing_cloud
## Installation
Please see marketing_cloud README.md
## Configuration
Please see marketing_cloud README.md for general configuration.
This module will add a tab to admin > config > marketing cloud. here you can
edit the individual rest call definitions.
# Marketing Cloud Platform API
Enables the platform API in the Marketing Cloud.
# Requirements #
## Introduction
This module enables the platform API in the Marketing Cloud as a service.
For details on individual API calls and the Marketing Cloud REST API, please
visit
https://developer.salesforce.com/docs/atlas.en-us.noversion.mc-apis.meta/mc-apis/routes.htm
## Service functions
| Name | Function |
| ----------------- | -------------------------- |
| Get endpoints | getEndpoints() |
| Get token context | getTokenContext() |
| Get endpoint | getEndpoint($endpointType) |
## Requirements
* marketing_cloud
## Installation
Please see marketing_cloud README.md
## Configuration
Please see marketing_cloud README.md for general configuration.
This module will add a tab to admin > config > marketing cloud. here you can
edit the individual rest call definitions.
# Marketing Cloud Push API
Enables the push API in the Marketing Cloud.
# Requirements #
## Introduction
This module enables the push API in the Marketing Cloud as a service.
For details on individual API calls and the Marketing Cloud REST API, please
visit
https://developer.salesforce.com/docs/atlas.en-us.noversion.mc-apis.meta/mc-apis/routes.htm
## Service functions
| Name | Function |
| --------------------------------------- | ------------------------------------------------------- |
| Create push message | createPushMessage($json) |
| Get push messages | getPushMessages() |
| Create location | createLocation($json) |
| Get locations | getLocations() |
| Get app info | getAppInfo($appId) |
| Update push message | updatePushMessage($messageId, $json) |
| Delete push message | deletePushMessage($messageId) |
| Get push message | getPushMessage($messageId) |
| Get specific location | getSpecificLocation($locationId) |
| Update location | updateLocation($locationId, $json) |
| Delete location | deleteLocation($locationId) |
| Get custom keys | getCustomKeys($appId) |
| Update custom keys | updateCustomKeys($appId, $json) |
| Delete custom keys | deleteCustomKeys($appId) |
| Refresh list | refreshList($id) |
| Send message to all | sendMessageToAll($messageId, $json) |
| Send message to tagged users | sendMessageToTaggedUsers($messageId, $json) |
| Send message to list | sendMessageToList($messageId, $json) |
| Update custom key | updateCustomKey($appId, $key) |
| Delete custom key | deleteCustomKey($appId, $key) |
| Send message to mobile devices in batch | sendMessageToMobileDevicesInBatch($messageId, $json) |
| Send message to mobile devices | sendMessageToMobileDevices($messageId, $json) |
| Get refresh list status | getRefreshListStatus($id, $tokenId) |
| Get delivery status of message app | getDeliveryStatusOfMessageApp($messageId, $tokenId) |
| Get delivery status of message tag | getDeliveryStatusOfMessageTag($messageId, $tokenId) |
| Get delivery status of message list | getDeliveryStatusOfMessageList($messageId, $tokenId) |
| Get delivery status of message contact | getDeliveryStatusOfMessageContact($messageId, $tokenId) |
## Requirements
* marketing_cloud
## Installation
Please see marketing_cloud README.md
## Configuration
Please see marketing_cloud README.md for general configuration.
This module will add a tab to admin > config > marketing cloud. here you can
edit the individual rest call definitions.