Pmc Exacttarget

ExactTarget Plugin for PMC

This plugin provides ability to send Newsletters and Breaking News Alerts to PMC brands. It uses Salesforce Marketing Cloud ( formerly known as ExactTarget ) for carrying out this task. Each brand that intends to have this functionality must have an account with Marketing Cloud.

Check https://confluence.pmcdev.io/display/HIG/Newsletter+Implementation+Details (opens in a new tab) for few attachments of Postman API Collections and Screenshots.

The plugin facilitates mainly 2 types of email sending.

Breaking News Alerts
This is sent immediately when an Editor publishes the post. The email will contain a single post, the one being published.

This requires creating a Breaking News Alert which contains configurations such as which Dataextension (opens in a new tab) ( list of subscribers ), Template ( html template to be used for email ) and Send Classification (opens in a new tab) to use for sending the email.
Recurring Newsletter
These are curated newsletters containing multiple posts and can be sent as and when needed by performing a manual SEND, or can be scheduled to have them delivered to subscribers at a specific time, e.g. 12:00 PM every Monday.

This requires creating a Nesletter similar to Breaking News Alert. It contains almost all configurations from BNA and a few more relating to scheduling and curation of posts that would be sent as part of Newsletter.

Curation is facilitated by a VIP plugin named Zoninator (opens in a new tab).

Setup

Setting up requires acquiring API Client ID, Secret Key, Authentication URL, REST Base URL and SOAP Base URL from concerned brand's Salesforce Marketing Cloud ( formerly known as ExactTarget ) account.
These credentials can be found in Installed Packages section in Marketing Cloud dashboard.

Setup For Local Development/Testing

There is no Marketing Cloud sandbox, so anything you send WILL USE PRODUCTION MARKETING CLOUD.

You will still need to use the credentials from the setup section above. However, you need to add a new Breaking News Alert or Recurring Newsletter with a TEST Data Extension (i.e. 'TEST - DRAMSEY', 'Test - Vinod').

There are a few already set up. You will need to add your email address to that Test group. (First you need to sign up for the brand's newsletter that you're working on). Reach out to your RM or Newsletter group to get set up.

Technical Details and Architecture

Classic Content vs Content Builder

Classic Content and Content Builder both are Marketing Cloud's Content Managers. They're used for managing emails, templates, images, web pages etc. Classic Content is Marketing Cloud's legacy Content Manager whereas Content Builder is newer version of their Content Manager, it offers block based email creation and much more powerful tools for creating Emails and Templates and any other type of assets.

Important
This plugin used only Classic Content up until 8th February 2021, support for newer Content Builder side was added starting from that date as Marketing Cloud decided to drop support of the ability to create or update templates in Classic Content side. As of writing this document the plugin uses both Classic Content and Content Builder. The plan is to eventually move all Recurring Newsletters and Breaking News Alerts to newer Content Builder side. All the Templates, Breaking News Alerts and Recurring Newsletters created after 8th February 2021 uses Content Builder, only the existing Newsletter configs are using Classic Content they eventually will be updated to use Content Builder whenever someone requests edits to the templates used by those configs.

Classic Content related code is supposed to be removed once all newsletter configurations on all brands are updated to use Content Builder

How to update existing Configuration to use Content Builder?

Below are the steps to update existing Configuration to use Content Builder.
If it's a Recurring Newsletter then Pause it then Edit the newsletter configuration

In edit screen select 'Yes' in Content Builder dropdown ( see screenshot below ). You should be able to see '( Content Builder )' appear under HTML Template label, this indicates that templates dropdown is now updated to display templates from Content Builder.
Make sure to select appropriate template in template selection dropdown.
Save the configuration.
If everything goes well then page shoud refresh and you should see an Alert saying 'Saved'. If an error occures while saving the newsletter configuration then the error message will be displayed at the top of the page.
The newsletter configuration is now updated to use Content Builder.

Marketing Cloud ( ExactTarget ) Architecture

Marketing Cloud offers many types of emails, e.g. HTML Emails, Template Based Emails etc, we're only using HTML Emails for our purposes.

The general workflow is, first the template that Newsletter or BNA is configured to use is fetched, then an Email is created or updated using the content of the template. Then using FuelSDK ( \FuelSdk\ET_Client ) class the email is sent.

File Organization

All the Emails created via this plugin resides in the root folder in Marketing Cloud's Content Builder. Content Builder can be found in Marketing Cloud Dashboard > Email Studio > Content.
All the Templates resides in a folder named Content Builder > My templates > Active WordPress Sends, the plugin depends on this folder structure and naming scheme which means each brand is supposed to follow it. Only the templates in this folder and it's sub folders are displayed in the select box when creating a Newsletter or BNA config.
Codesnippets (opens in a new tab) resides in Content Builder > my contents. These are only used with Recurring Newsletters, See 2. Recurring News Alerts for more information on how Codesnippets are used.
Dataextensions (opens in a new tab) resides in Marketing Cloud Dashboard > Email Studio > Subscribers > Data Extensions > Active WordPress Sends. the plugin depends on this folder structure and naming scheme which means each brand is supposed to follow it. Only the Dataextensions in thes folder and it's sub folders are disaplayed in the select box when creating a Newsletter or BNA config.
Send Classifications (opens in a new tab) resides in Marketing Cloud Dashboard > Email Studio > Admin > Send Management > Send Classifications.

Note: The plugin highly relies on this File / Folder organization.

Everytime a Newsletter or a Breaking News Alert is sent, certain steps are performed to carry out the task, below is the workflow description of how an email goes from the website ( e.g. variety.com ) to a subscriber's inbox.

Breaking News Alerts
1. Creating Breaking News Alert configuration
  
  When you submit the form to create a Breaking News Alert, an Email is created in Marketing Cloud's Content Builder side in the root folder using the selected Template and subject line if provided. The name of the Email is same as the Alert's name.
  
  IMPORTANT: The plugin uses email's name for fetching / updating / deleting the email associated with the Breaking News Alert.
  
  Code reference: pmc-exacttarget/fast-newsletter.php
  
  Steps performed to create BNA config:
  - Fetch the selected template's content
  - Upsert an email to Marketing Cloud using this content and title set in config
  - If everything went well then save the configuration to the DB
2. Sending Breaking News Alert
  
  A BNA is sent when a post is published or updated. Editor must select a BNA configuration from a list of configurations in the Post's edit screen.
  The code that handles this is written here: pmc-exacttarget/sailthru.php in a function named sailthru_publish_to_sailthru()
  
  Steps performed when sending a BNA:
  - Perform basic checks and validations
  - Fetch template's content from Marketing Cloud
  - Replace tokens in the content with proper values. When a template is created, it contains some tokens such ##content##, ##title##, ##excerpt##, ##thumb##, ##author##, ##tags## and few more to allow injecting dynamic content at the time of sending BNA. These tokens are supposed to be replaced with the data from the post being sent as a Breaking News Alert.
  - Get the Send Classification (opens in a new tab) Key. It is stored in BNA config.
  - Create a temporary Email in Content Builder using the content
  - Send the email using FuelSdk\ET_Client::send_senddefinition
    - This will create a temporary Send Definition (opens in a new tab) in Marketing Cloud Dashboard > Email Studio > Interactions > User Initiated Emails using the email, classification and dataextension.
      Send Definition is basically a preset that can be used to send an email, it contains all the necessary information such as which email to send, to which dataextention the email is to be sent and what classification to use etc
    - Perform send definition
    - Delete send definition
  - Delete the temporary email if everything went well.
  - The log is saved in the post meta with the key fastnewsletter_log_{name_of_BNA}
3. Deleting BNA
  - Delete corresponding email in Marketing Cloud
  - Remove BNA config from Database.
Recurring Newsletter
1. Creating Recurring Newsletter configuration
  
  When you submit the form to create a Newsletter configuration, an email with content from the selected template is created in Content Builder's root folder.
  Refer to this file for code reference: pmc-exacttarget/recurring-newsletter.php
  
  Each Newsletter has a corresponding RSS feed, this feed contains all the posts which are supposed to be included in the newsletter. This feed is generated based on configured options. You can refer to these configuration options in Newsletter create screen. Refer to this code for more information: pmc-exacttarget/sailthru.php function sailthru_addfeed_do_feed().
  
  How the RSS Feed is utilized to fetch posts :
  The general worflow is, a Codesnippet block is created containing a http fetch call to the above mentioned RSS Feed > An email is created / updated in Marketing Cloud > A Send Definition is Created > Send Definition is Executed > Marketing Cloud executes the email > Email calls the Codesnippet block and fetches the posts from RSS Feed > Email is sent > Send Definition is delete.
  
  More detailed steps are listed below.
  
  Steps performed to create Recurring Newsletter config:
  - Prepare HTML for email using template
    - Prepare XML source / RSS Feed source
      - Upsert a Codesnippet (opens in a new tab) block with the feed URL for this Newsletter. The name of this codesnippet is same as name of the Email but spaces and special characters are replaced with -. This Codesnippet block will be later called by the Email ( at the time of sending ) using an AMPScript (opens in a new tab) function named ContentBlockByName( 'my contents\name-of-email' ). This Codesnippet block contains a http call that retreives data from the feed.
    - Retrieve template content
    - Replace dynamic content placeholders in this content with a Salesforce function call so the email can retrieve posts from RSS feed. Each newsletter template has a placeholder ( ##pmc-auto-insert-feed-url## ) which the plugin replaces with appropriate AMPScript (opens in a new tab) function call that is responsible for fetching posts using the RSS feed. e.g. It will be replaced by
      Set @xml = ContentBlockByName("my contents\name-of-email" )
  - Upsert Email using the prepared HTML content. This email is upserted in root folder of the Content Builder. At this point this Email contains HTML markup with some AMPScript that processes dynamic content.
  - If eveything went well then save the configuration to DB.
    See ( Sailthru_Blast_Repeat::save_api_to_db() )
2. Sending Recurring Newsletter
  Newsletters can be sent in couple of ways. Below is a list and technical description of each way.
  1. Sending a Test Newsletter uring TEST button on Recurring Newsletters page ( e.g. https://variety.pmcqa.com/wp-admin/admin.php?page=sailthru_recurring_newsletters (opens in a new tab) ).
    
    Clicking on the TEST button will open up a dialogue box containing a dropbox of Test Subscribers Lists. These lists are stored in Marketing Cloud in Email Studio > Subscribers > My Lists. The dropbox will contain only those lists that has editorial test in it's name. e.g. Editorial Test - Kelin will show up in the dropbox but EShow Daily List won't.
    
    Refer to this code for more information: pmc-exacttarget/sailthru.php function: sailthru_test_send_repeat()
    
    Steps performed when sending a Test Newsletter:
    - Perform basic checks and validations
    - Check if email corresponding to newsletter exists in Content Builder.
    - Prepare HTML for email using template
      - Prepare XML source
      - Upsert a Codesnippet (opens in a new tab) block with the feed URL for this Newsletter. The name of this codesnippet is same as name of the Email but spaces and special characters are replaced with -. This Codesnippet block will be later called by the Email ( at the time of sending ) using an AMPScript (opens in a new tab) function named ContentBlockByName( 'my contents\name-of-email' ). This Codesnippet block contains a http call that retreives data from the feed.
      - Retrieve template content
      - Replace dynamic content placeholders in the template content with a Salesforce function call so the email can retrieve posts from RSS feed. Each newsletter template has a placeholder ( ##pmc-auto-insert-feed-url## ) which the plugin replaces with appropriate AMPScript (opens in a new tab) function call that is responsible for fetching posts using the RSS feed. e.g. It will be replaced by
        Set @xml = ContentBlockByName("my contents\name-of-email" )
    - Upsert Email using the prepared HTML content. This email is upserted in root folder of the Content Builder. At this point this Email contains HTML markup with some AMPScript that processes dynamic content.
    - Retrieve Classificaion Key
    - Send Test Recurring Newsletter using Selected Subscriber List and Classification. The plugin uses this function: FuelSdk\ET_Client::SendEmailToList() from third party library called FuelSdk. This library is icluded as a plugin ( fuelsdk-php ) in pmc-plugins.
      - This will create a temporary Send Definition (opens in a new tab) in Marketing Cloud in Email Studio > Interactions > User Initiated Emails using the email, classification and subscribers list.
        Send Definition is basically a preset that can be used to send an email, it contains all the necessary information such as which email to send, to which dataextention the email is to be sent and what classification to use etc.
      - Perform send definition
        
        Marketing Cloud initiates send protocol this executes the AMPscript code written in the Email.
        
        AMPscript fetches content of the Codesnippet block passed as argument to ContentBlockByName() in the Email content.
        
        This will fetch XML Feed containing newsletter articles.
        
        Further AMPscript code is run and entire email is built.
        
        Email is sent by Marketing Cloud
      - Delete send definition
  2. Manually sending the newsletter using SEND NOW button on Recurring Newsletters page
    
    Clicking on SEND NOW button will send the newsletter immediately to the configured subscribers.
    
    Refer to this code for reference: pmc-exacttarget/sailthru.php function: sailthru_send_repeat_now().
    
    Steps performed to send a recurring newsletter
    - Basic checks and validations are performed.
    - Checks if email corresponding to newsletter exists in Marketing Cloud.
    - Steps mentioned under the title Steps Performed to Process a Recurring Newsletter are performed. Check below.
  3. Scheduling a Newsletter to be automatically sent on scheduled time.
    
    A scheduled Recurring Newsletter is automatically sent at the scheduled time. This is achieved via a custom endpoint that the plugin exposes. The endpoint is of the format https://{brandname.com}/pmc-exacttarget/{token}/ where token is configured via brand's Dashboard ( e.g. https://variety.com/wp-admin/admin.php?page=sailthru_newsletter_settings ).
    
    A Jenkins Job (opens in a new tab) is responsible for hitting this endpoint at a specific interval ( at the time of writing this the interval is set to 5 minutes ). When this endpoint is hit, WordPress is initialized and looks for scheduled recurring newsletters and processes them.
    
    Code Reference: \PMC\Exacttarget\Sailthru_Blast_Repeat::template_redirect()
    
    Steps performed to send a scheduled recurring newsletter
    - Jenkins hits the endpoint responsible for processing the scheduled newsletters.
    - WordPress is initialized
    - Retrieve all the Recurring Newsletter Configurations from DB
    - Process them one by one
      - Perform basic checks and validations
      - Check if this configuration is scheduled to be sent now. The information relating the scheduled time is stored with the configuration is the DB.
      - if the Newsletter is scheduled to be sent now then steps mentioned under the title Steps Performed to Process a Recurring Newsletter are performed. Check below.
  Below is a description of steps performed to process a newsletter.
  
  Steps Performed to Process a Recurring Newsletter
  - Prepare HTML for email using template
    - Prepare XML source / RSS Feed
    - Upsert a Codesnippet (opens in a new tab) block with the feed URL for this Newsletter. The name of this codesnippet is same as name of the Email but spaces and special characters are replaced with -. This Codesnippet block will be later called by the Email ( at the time of sending ) using an AMPScript (opens in a new tab) function named ContentBlockByName( 'my contents\name-of-email' ). This Codesnippet block contains a http call that retreives data from the feed.
    - Retrieve template content
    - Replace dynamic content placeholders in the template content with a Salesforce function call so the email can retrieve posts from RSS feed. Each newsletter template has a placeholder ( ##pmc-auto-insert-feed-url## ) which the plugin replaces with appropriate AMPScript (opens in a new tab) function call that is responsible for fetching posts using the RSS feed. e.g. It will be replaced by
      Set @xml = ContentBlockByName("my contents\name-of-email" )
  - Upsert Email using the prepared HTML content. This email is upserted in root folder of the Content Builder. At this point this Email contains HTML markup with some AMPScript that processes dynamic content.
  - Retrieve Classificaion Key
  - Send Recurring Newsletter using Selected Dataextension and Classification. Uses library function to perform the send: FuelSdk\ET_Client::send_senddefinition()
    - This will create a temporary Send Definition (opens in a new tab) in Marketing Cloud in Email Studio > Interactions > User Initiated Emails using the email, classification and dataextension.
      Send Definition is basically a preset that can be used to send an email, it contains all the necessary information such as which email to send, to which dataextention the email is to be sent and what classification to use etc.
    - Perform send definition
      - Marketing Cloud initiates send protocol this executes the AMPscript code written in the Email.
        
        AMPscript fetches content of the Codesnippet block passed as argument to ContentBlockByName() in the Email content.
        
        This will fetch XML Feed containing newsletter articles.
        
        Rest of the AMPscript code in email is run and the email markup is built.
      - Email is sent by Marketing Cloud
    - Delete send definition

Code Architecture

New Rest API classes

\PMC\Exacttarget\Rest_Request
Responsible for making the actual rest request and processing the results.
\PMC\Exacttarget\Rest_Support
Base class, provides RESTful services to child classes. e.g. \PMC\Exacttarget\Email_Rest, \PMC\Exacttarget\Folders_Rest etc.
\PMC\Exacttarget\Email_Rest
Responsible for creating, updating, retrieving and deleting an Email in Marketing Cloud Content Builder
\PMC\Exacttarget\Content_Block_Rest
Responsible for creating, updating, retrieving and deleting an Content Blocks like Codesnippet (opens in a new tab) blocks in Marketing Cloud Content Builder
\PMC\Exacttarget\Folders_Rest
Responsible for retrieving list of Folders ( also known as Categories ) from Marketing Cloud Content Builder
\PMC\Exacttarget\Templates_Rest
Responsible for retrieving Template(s) from Marketing Cloud Content Builder
\PMC\Exacttarget\Rest_Error
An Error class, used for returning structured errors, similar to Rest_Request class to ensure uniformity in return values from functions.

References

For more details https://confluence.pmcdev.io/display/HIG/Newsletter+Implementation+Details (opens in a new tab)
Marketing Cloud REST API Overview https://trailhead.salesforce.com/en/content/learn/v/modules/marketing-cloud-apis/use-rest-api-across-marketing-cloud (opens in a new tab)
Salesforce Marketing Cloud APIs [ VIDEO ] https://www.youtube.com/watch?v=hhLw_fWYjLY (opens in a new tab)
Marketing Cloud API Developer Documentation https://developer.salesforce.com/docs/atlas.en-us.noversion.mc-apis.meta/mc-apis/index-api.htm (opens in a new tab)

Pmc Events Pmc Faq