- marketingcloud_handler
- marketing_cloud_enhanced
- marketing_cloud_enhanced_interaction (submodule of marketing_cloud_enhanced module)
The three modules included within this directory have been developed in order to create a custom Drupal to Marketing Cloud integration via Webform submissions.
For more context, Insulet is a global corporation with a presence in the EU and the US. One of the main ways that we generate business is by customers or potential customers submitting forms through our various digital properties. Because of GDPR, we need to maintain two separate instances of Marketing Cloud - one for North-American (US and Canada) user data and another for the EU user data.
The site using these modules is www.myomnipod.com. In order to cater to our international audience, we decided to use a single site architecture and to indicate which region the user is visiting via a sub-path in the URL. So for example, the home page for the UK-facing portion of our site is www.myomnipod.com/en-gb/home, the French version is www.myomnipod.com/fr-fr/home, etc. The US-facing portion of the site is just www.myomnipod.com/home.
"Data Extension" is the term used by Marketing Cloud to describe the database that the form data is being submitted to.
In addition, Marketing Cloud recently deprecated v1 of their Authentication API (Legacy), and replaced it with v2 (Enhanced). The version of the Authentication API being used by a Data Extension within Marketing Cloud is determined by when the Data Extension was created within Marketing Cloud. Since a subset of our forms use the Legacy Auth API, the marketingcloud_handler is also used to identify which form is being submitted and from what region it is being submitted, and then uses those data points to determine which Auth API to utilize in order to get the token.
As the name implies, the marketingcloud_handler module is a Webforms Handler Plugin. This handler is attached to any webform that should submit user data to Marketing Cloud. The module is primarily used to:
- capture and manipulate the data submitted by the user prior to submitting the data to Marketing Cloud,
- generate any required values that are not provided/generated by the form or the form fields,
- fire API calls to Marketing Cloud's Authentication and Interaction APIs to submit the data via the marketing_cloud_enhanced and the marketing_cloud_enhanced_interaction modules,
- determine which instance of Marketing Cloud to target (North America or EU), and
- determine which version of Marketing Cloud's Authentication API to utilize in order to get an auth token from Marketing Cloud to actually submit the data
The marketingcloud_handler provides one configuration variable - the event_definition_key, which is used to target a 'Data extension' (i.e. a table within their database ) within one of our two marketing cloud instances.
So given that contextual information mentioned above, the marketingcloud_handler ultimately addresses the following challenges whenever a form is being submitted in order to ensure that the data is successfully submitted to the correct instance:
- Some forms use v1 of the auth API,
- Some forms use v2 of the auth API, and
- One of our two instances needs to be dynamically targeted based on data points from the webform's configuration and region the form is being submitted from
Keep in mind that this is a highly customized trio of modules that are customized to the needs of Insulet and have very specific requirements set by Marketing Cloud / Salesforce for the formatting of the data. So testing it will not be easy given the fact that it heavily relies on the configuration of the webform that it is being attached to. Also, all sensitive data (keys, api endpoint, etc) has been stripped out of the module for security purposes.
NOTE: For the sake of transparency, I want to be upfront in stating that the marketing_cloud_enhanced module was based off of the marketing_cloud contributed module (link: https://www.drupal.org/project/marketing_cloud).
While it was based off of the marketing_cloud module, it has been highly modified and customized in order to fit my specific use case. If you compare the original module with my version, you will see that the marketing_cloud_enhanced module has been highly modified in the following ways:
- The majority of the module's methods, API endpoints, and sub-modules have been stripped out or rewritten. My use case only required the use of Marketing Cloud's Authentication API and the Interaction API.
- At the time of this initiative, the marketing_cloud module could only use the legacy Authentication API. In order to ensure that the all forms could submit data regardless of the Authentication API required by Marketing Cloud, I needed to further customize the module to work with both the legacy and enhanced Auth APIs.
- Originally, the marketing_cloud module was configured to get the Authentication token statically. User's had to go to the module's configuration form, insert the relevant client_id, client_secret, and API endpoints, and then submit the form to get the Auth token. Because we have two instances of Marketing Cloud that need to targeted dynamically, the module had to be customized to fire a call to the Authentication API every time a form was submitted in order to get the Authentication token for the correct instance of marketing cloud.
- Environmental variables are being used to provide the API endpoints, client_id, and client_secret instead of using configuration variables set by the user. This was done because we wanted to ensure that the right authentication credentials are always being used in the correct environment, mitigating the risk of users utilizing the wrong set of credentials in the wrong environment and/or targeting the wrong instance (EU vs North America).
The marketing_cloud_enhanced module service is primarily utilized to procure the authentication token and to submit the data to Marketing Cloud via their Interaction API.
NOTE: For the sake of transparency, I want to be upfront in stating that the marketing_cloud_enhanced_interaction submodule was based off of a submodule within the the marketing_cloud contributed module (link: https://www.drupal.org/project/marketing_cloud).
The marketing_cloud_enhanced_interaction module is primarily used to get relevant authentication credentials
(client_secret and client_id) and the api endpoint URLs (for both the Authentication API call and for the Interaction
API call). These resources are then passed to the marketing_cloud_enhanced service in order to get the Authentication
token and subsequently fire the Interaction API call to submit the data.
Environmental variables are being used to provide the API endpoints, client_id, and client_secret instead of using configuration variables set by the user. This was done because we wanted to ensure that the right authentication credentials are always being used in the correct environment, mitigating the risk of users utilizing the wrong set of credentials in the wrong environment and/or targeting the wrong instance (EU vs North America).
- Webform is created.
- Webform is configured to utilize the Marketingcloud Handler.
- A user goes to the webform and submits their form.
- Handler captures the data and modifies the data as required by Marketing Cloud.
- Once all relevant data is prepared, the handler makes a call to the marketing_cloud_enhanced_interaction service and passes the form data and the parameters required to determine which instance of Marketing cloud to target and which Authentication API version to use get the authentication token.
- The marketing_cloud_enhanced_interaction service then fires one of two functions that initiate the REST call being made to Marketing Cloud's Interaction API from the marketing_cloud_enhanced service, passing the data and the correct authentication details associated with getting the Authentication token for v1 or v2 of the Authentication API.
- Before the REST call is made to Marketing Cloud's Interaction API, the marketing_cloud_enhanced service creates a MarketingCloudEnhancedSession in order to procure the token from which ever version of the Authentication API is being used for the Marketing Cloud Data Extension associated with the form being submitted.
- This token is then returned to the marketing_cloud_enhanced service and utilized in the Interaction API call to submit the data into the Marketing Cloud Data Extension.
- Data has been submitted to Marketing Cloud.
- Process over.
Link to Marketing Cloud's API Documentation: https://developer.salesforce.com/docs/atlas.en-us.noversion.mc-apis.meta/mc-apis/routes.htm Link to Github Repository: https://github.com/matthewgsommers/customModulesCodeSample