Many-to-One Email Cloud App Documentation

image_pdfimage_print

Purpose

With the Many-to-One Email cloud app, you can create highly personalized emails to contacts with complex many-to-one relationships. This is accomplished by updating Contacts with Custom Object data, regardless if it’s the first, fourth or last custom object record within a particular Custom Object.

This document describes how this Cloud App can be used in Eloqua’s Campaign Canvas.  The app can also be used in Program Canvas.

Set-up in Eloqua

Please follow these instructions to set up this cloud app in your Oracle Eloqua instance.

  • Log in to Oracle Eloqua.
  • Click on Get App below to install.

        NOTE: If prompted to log again, please do so.

  •  In the next screen, click “Sign In” and then “Accept”
Many-to-One Email Cloud App Documentation 1

1.4. In the next screen, click “Sign In” and then “Accept”

Many-to-One Email Cloud App Documentation 2

1.5. You’re all set. Your Many-to-One cloud app is ready to be used.

Many-to-One Email Cloud App Documentation 3

Configuring your Custom Object

If you know that there will be multiple records for each email address, you will also need to add two fields to your CO and configure them for use later. These fields are used to flag if processed, and if there are additional records matching the filter for a contact. You may name these new CO fields as you wish, and then configure them when required.

Many-to-One Email Cloud App Documentation 4

How To Use

The following instructions show the basic use of the app. You can incorporate this Cloud App into any existing campaign.

Create/Open a Campaign

Click on “Actions” on the top left side, then “Show All Steps”, and then locate the “Many-to-One Email” Cloud App under the Actions options (colored in purple).

Many-to-One Email Cloud App Documentation 5
Many-to-One Email Cloud App Documentation 6

Drag and drop the cloud app to the canvas area. Connect the corresponding elements to the dropped cloud app.

Many-to-One Email Cloud App Documentation 7

Double click the Many-to-One Email step icon. You will see some options for this element.

Rename the step if needed

Many-to-One Email Cloud App Documentation 8

Click the pencil icon to open the settings for this step.

You will need a 4Thought Marketing App Cloud Portal user to log in and configure this app. If you don’t have one, you can create one. If you do, use your user to log into the page shown in the following screenshot:

Many-to-One Email Cloud App Documentation 9

Indicate the Custom Object (CO) which contains the data that will update the linked Contact records.

Many-to-One Email Cloud App Documentation 10

Selecting Records Using Filters and Operators

You can now filter the CO records linked to the Contact Record – this step is not required.

  • The filtering in this section normally matches the filter on the CO records used in the feeder to the Campaign
Many-to-One Email Cloud App Documentation 11
  • Select the CO field on which you want to filter
  • Select the operator
  • Select the value to be compared
  • Click the ‘Add Filter’ button
  • You may add additional filters using this process – you can include AND/OR logic as well (see example)
Many-to-One Email Cloud App Documentation 12

e. The following filter operators are available for your use:

  • Equals (=)
  • Not Equals (!)
  • Contains (~)
  • Less Than (<)
  • Less Than or Equal To (<=)
  • Greater Than (>)
  • Greater than or Equal To (>=)
  • NOT (in combination with other operators; do not use “NOT” with the following Date operators; Use “NOT” only with one operator, do not use with complex expression: “NOT (Contains)” is ok; “NOT (Equals AND Equals)” is not permissible)
  • Within Next (date fields)
  • Not Within Next (date fields)
  • Not Within Last (date fields)

Be aware of these known Eloqua constraints on filtering

  • There is an Eloqua limit of 1,000 characters that can be used to build the filter. The app displays a counter to notify you regarding the number of characters used. When the number gets close to 1,000, the app will not allow any more filter elements to be added
  • You cannot use Comma, Single Apostrophe, Parenthesis, Bracket – these are characters used in the Eloqua language
  • The “NOT” Operator is not supported when used in complex filters. If used with a single element, it will work. If used with complex expressions, it will return invalid results
  • The “NOT” Operator should not be used with date operators.
  • Eloqua does not allow more than 2 date fields to be included in one filter

Next, you need to specify the mapping from CO fields to Contact Fields.

Select the CO field and the matching Contact field. Repeat these steps to add all the fields you need. At least one field must be mapped.

Use the trash button to remove a specific field from the mapping area

Many-to-One Email Cloud App Documentation 13

Marking Records as Processed

In the “Additional Settings” box, select the CO field that will be used to designate the CO as processed. This field will be set to the Campaign ID upon completion of the data move. This field is required only if you know there will be more than one CO record that matches the filter criteria

In the “Additional Settings” box, select a Contact field that will designate no more COs to process. This field will be set to “No” upon completion of the data move. This field is required only if you know there will be more than one CO record that matches the filter criteria

Many-to-One Email Cloud App Documentation 14

Then click “Save Settings”.

Recommended: Create an element in the campaign in case an error happens, in this example, it’s a Wait Step. Check the box to “Automatically route contacts with errors from cloud app”, select the step where you want the contacts to be routed (in this example, the Wait Step).

Many-to-One Email Cloud App Documentation 15

Save the Campaign first and then Configure the Reset step by referencing the Many to One step. The reset steps clears all of the flags used in previous steps to process CO data.

Click the following link:

  • On the next screen, click “Accept and Install” on the top-right section
Many-to-One Email Cloud App Documentation 16

That’s all. Activate the campaign, and see the Many-to-One Email Cloud App in action!

Note: Use of the Bulk processing app

This version is installed when the standard version is installed. It should be used whenever the user expects more than 20K contacts to be added to the step at one time. There is also a M2O bulk reset version which should be used in conjunction with the Many to One Bulk Processing version.

Many-to-One Email Cloud App Documentation 17

b. We recommend that you select a frequency of 1 hour, all other configurations will be same as standard version.

Many-to-One Email Cloud App Documentation 18

Troubleshooting

The following is a list of common causes of errors in the Many to One application and how to fix them:

No matching CO records – by far the most common cause for contact records to receive an error and move to the Error step. Often data will change after a campaign has been initiated. If a Contact enters the Many to One step, and there are no longer any CO records that match the filter criteria, an error will be identified and the contact record will be routed to the Error step if you have identified one. This will also show up in the error logs.

  • To address this issue, you will have to either remove the contact from the campaign, or modify the data in the CO record to match the filter criteria

Timeout – if the Eloqua API has issues, it is possible for the interaction between the app and Eloqua to timeout. If this occurs, the app will attempt up to 3 times to make connections and continue processing records. Only after 3 unsuccessful attempts will an error be registered, and the record moved to the error step.

  • To address this issue, you should move the contacts from the error step to the step just prior to the Many to One app. If this problem continues, please contact support.

Configuration screen not available – After an Eloqua upgrade, it is possible that the configuration screen is not available. This does not affect any configurations already in place, but may make it difficult to configure new instances of the app.

  • To address this issue, first try closing and then re-opening the configuration screen. If that does not resolve the issue, then try re-installing the app from the app cloud setup screen. If you continue to have a problem, contact support.

Note: Most 4Thought Marketing apps use the Eloqua BULK API to export/import records, therefore when an app is used in a campaign or program the user that activates the campaign should have the following permissions:

• API
o Consume API
• Contacts
o Upload Contacts/Prospects/Companies
o Manage Data Export
o Manage Contacts

License Information

You need a license to configure and execute this Cloud App. Otherwise in the configuration page you will see the following error:

Many-to-One Email Cloud App Documentation 19

Additionally, if you happen to see records stuck in the Cloud App step, it may be due to a missing or expired license. You may contact your 4Thought Marketing Account Manager to address licensing questions.