Skip to main content
Sign in

Project Recipe: UTM Mapping for Marketo to Salesforce

  • Updated

BETA - Please be aware that this feature is currently in beta mode

The following is a guideline to follow when using the recipe "UTM Mapping for Marketo to Salesforce." Please read these guidelines before cloning the recipe.

Preparation

This project uses Openprise's API Factory and Marketo's Webhook functionality to write UTM data to a Campaign member record in Salesforce. We recommend you review the following article about creating a Marketo Webhook for Openprise before cloning this recipe.

Overview

This recipe provides the following:

  • An API Factory job to receive API calls from a Marketo Webhook.
  • Jobs that process API responses by identifying related Campaign Members within Salesforce and updating the UTM information. 
  • An App Factory Search Table to review received API requests and the original information submitted
  • An App Factory Search Table to review the current status of an API request being matched and updated in Salesforce

The assumption is that your Salesforce Campaign and Campaign Member objects are being imported on a regular basis by pre-existing bots.

Preparation

  1. If a data source does not already exist, create a data source for Salesforce Campaign Members and Campaigns with at least the following attributes.
    *Note: If these data sources are already created, please verify that the following attributes are defined in the data sources.
    Campaign Campaign Member
    Id Id
    Name LeadorContactId
    "Attribute used as Unique Identifier" 

    *see Phase 3: Live Testing of Marketo Webhook (below) for more information    		 Email
      FirstName
      LastName
      "All UTM Attributes Available or will be used in the App"
  2. Create new data targets: Create a new data target for Salesforce Campaign Members with the attributes listed in Step 1 above.
  3. Create a spreadsheet in Google drive for the template for the lists to be loaded. This spreadsheet will only be used to define the attributes for the UTM string to be passed to Openprise.  
    Column name Openprise data type
    Email text
    Campaign Identifier text
    SFDCLeadID text
    SFDCContactID text
    gclid text
    utm_agn text
    utm_audience text
    utm_campaign text
    utm_content text
    utm_location text
    utm_medium text
    utm_origin text
    utm_source text
    utm_term text
    Add one record to the template by adding the value "template" in the Email column. You can leave all other values in the spreadsheet blank.
  4. Create a data source named from the above spreadsheet. When creating the data source:
    1. The Data source name should be Reference - Solutions - UTM Tagging Template.
    2. The source technology and data format for the data source should be Google Drive - Sheets.
    3. On the Map screen, all fields can be left as the default data type of Text, single value.
    4. Note: Two additional columns will be added when the data source is created: OPFileNames and OPAutoDate. These attributes should remain in the data source.
    5. Import the sample record in to the data source just created.

Clone

To clone the project recipe, navigate to Projects Recipes and select the project recipe to clone

1.png

UTM.png

You will need to provide:

  • Project name
  • Prefix and/or suffix for all objects in the project
  • Data source to be used in the project
  • Data target to be used in the project

Examine the Cloned Project

We recommend you look through all the newly created project elements to familiarize yourself with what has been created.

Look for:

  1. Any job that is marked with errors. These errors must be manually corrected.
  2. Export tasks that write back to Salesforce. Make changes by selecting any values you want to send to Salesforce. Note: Any Export task to Salesforce has been bypassed for your protection. We recommend that you run the jobs with bypass enabled to review any data changes before writing data back to Salesforce.
  3. Review logic in the jobs to validate that it meets your requirements for identifying the correct Campaign and Campaign Member, as well as what UTM information needs to be updated.
  4. Check that you have an automated bot that imports Campaigns and Campaign Members on a frequent basis so we are always processing up-to-date records.

Test the App

When you're ready to test, we recommend running the test in three (or two, depending on the platforms available) phases. See the following instructions for each phase. 

Phase 1: Testing the Openprise API 

It is optional to test Openprise API functionality using a third-party API send tool (e.g. Postman). You may skip this phase if you are not using an API send tool. This phase will test that Openprise is receiving API calls correctly.

After cloning and reviewing the recipe, navigate to Automation Jobs from the Dashboard within the Openprise Workbench and search for SFDC_UTM Mapping 01 - Intake API Calls.

  1. Click on Actions, and select View API Docs.
    Screenshot 2023-07-26 at 4.30.42 PM.png

  2. Copy the information in the API Doc to your API send tool.
    Note: URL and API key have been blanked out in the screenshots below. For your testing, this information should come from the job's "API Docs."
    Screenshot 2023-07-26 at 4.25.52 PM.pngScreenshot 2023-07-26 at 4.28.09 PM.png
  3. Copy the Request text from the API Doc into the body of the API send tool. Then change the Email value from to Template.
    Note: For your test record, Email = Template is set to be filtered out of the solution so that this test case will not affect the solution when it goes live. 
    Screenshot 2023-07-26 at 4.25.52 PM.png
    Screenshot 2023-07-26 at 4.34.49 PM.png
  4. Once completed, validate that you get a successful return in Postman and that a record is in the MDS "Log - UTM Tagging - API Call Receives" with an Email value of "Template". 

Phase 2: Testing the Marketo Webhook

In this phase, we will set up the Marketo Webhook and send a test record through the process to validate that Marketo and Openprise APIs are communicating appropriately. 

Note: If an Openprise CS Team member is setting up the solution, they will need to work with your Marketo administrator to set up the Marketo Webhook.

  1. Please follow the instructions in this helpdesk article to configure the Marketo Webhook.
    How to Create Marketo Webhooks for API Factory

    Note: The only difference in the article linked above is that rather than getting the API Doc from a bot, you will view the API Doc from job "SFDC_UTM Mapping 01 - Intake API Calls" since a bot does not control this API process. 
  2. Once the Webhook is completed, work with your Marketo administrator to generate sample records to pass through the Webhook. We recommend starting simple for this test and just sending email address through the webhook.
  3. We will want to confirm two successes: 
    1. Marketo's Activity logs show a successful Webhook call
    2. Openprise MDS "Log - UTM Tagging - API Call Receives" has received the call and data from Marketo's Webhook.

Phase 3: Live Testing of Marketo Webhook

Now that we have validated the success of Openprise's API and Marketo's Webhook configurations, it is time to test the logic in the solution. We will begin sending "live" records or records with the information that would be expected to be received in the process. 

Key Considerations for this section: 

  1. Openprise will match an API call to a Campaign Member using unique identifiers. One identifier to locate the correct campaign member and one identifier to locate the correct campaign. 
    1. Marketo should be able to send the related Salesforce LeadId or ContactId. If these IDs are not available, Openprise will also try to identify a Campaign Member record with the same Email address. 
    2. The naming conventions of Campaigns in Marketo often differ from those of Salesforce campaigns.

      If the naming convention is the same, the Marketo Campaign name can be passed, and Openprise can locate the Salesforce campaign with the same name.

      If the naming conventions differ, Marketo does not allow the related Salesforce Campaign ID to be passed through the API, so we may need to get creative on sending a unique identifier.
      One solution to that has worked for other customers is to append the Salesforce Campaign ID to the Marketo Campaign Name with a special character. For example, if the Marketo Campaign Name is "Summer CXO Mailing List," we could modify that to "Summer CXO Mailing List || 7017V000001YEdnQAG." With the special character, Openprise can look for that special character and parse the ID out of the account name. 

 

Related articles