CONTENTS OF THIS FILE
=====================

 * Introduction
 * Requirements
 * Installation
 * Configuration
 * Usages
 * Troubleshooting
 * Faq
 * Maintainers


INTRODUCTION
============

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.

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 Json validation can we switched
on/off in the settings.


REQUIREMENTS
============

 * [Swaggest PHP Json Schema](https://github.com/swaggest/php-json-schema)


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.
   * 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.


USAGES
======

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.
   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.
   * Call the service:
      ```php
      $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.


MAINTAINERS
===========

 * John Avery (john_a) - https://drupal.org/user/2573976