Add Transaction Event

Oracle Marketing Cloud - Eloqua Transactional Email App Feature

To send a transactional email using the Transaction Email app for Eloqua, you first need to set up and enable a transactional event including:

  • Specifying an Eloqua email to be used
  • Selecting an API authentication method
  • Provide sample JSON that will be received from the external system
  • Specify fields that should be used to personalized content and/or update an Eloqua Contact
  • Test your configuration

To add a new transactional event, navigate to the Settings area ( icon) and click on Apps under the Settings menu in the Platform Extensions section. Open the Transactional Email app and click on the Configure icon (). You may need to log in using your Relationship One AppCloud credentials.

1726

Step 1: Add a Transactional Event

Under the Transactional Events section, click the +Add button to add a new event.

3164

Give your event a name and search for the Eloqua email asset that should be used when sending a transactional email message.

1764

Step 2: Select a Security Method

Data can be sent from an external system (e.g., commerce platform, CRM, etc.) using either a secure webhook or an API endpoint using basic authentication.

For a webhook, a unique event endpoint will be generated as well as a security token required to configure your external system. You can use this system-generated token or replace it with your own if one is provided by your external system.

1302

Alternatively, select Basic Authentication to set up a REST API call from your external system. You will need to provide a username and password. Click the Get Event Endpoint button to generate an event-specific endpoint. You can update the Username and Password values as long as the transaction event is disabled.

1309

Step 3: Provide Sample JSON

You will need to provide a sample of the JSON that will be sent via the Webhook or REST API call. For example, an order confirmation JSON might look like:

{
  "id": 1090,
  "parent_id": 0,
  "number": "1090",
  "order_key": "wc_order_n3FybzySEvpxh",
  "created_via": "checkout",
  "version": "4.7.0",
  "status": "processing",
  "currency": "USD",
  "date_created": "2021-07-06T01:41:20",
  "date_created_gmt": "2021-07-06T01:41:20",
  "date_modified": "2021-07-06T01:41:21",
  "date_modified_gmt": "2021-07-06T01:41:21",
  "discount_total": "0.00",
  "discount_tax": "0.00",
  "shipping_total": "0.00",
  "shipping_tax": "0.00",
  "cart_tax": "0.00",
  "total": "91.45",
  "total_tax": "0.00",
  "prices_include_tax": false,
  "customer_note": "",
  "billing": {
    "first_name": "Tx",
    "last_name": "Demo",
    "company": "",
    "address_1": "333 N Washington Ave",
    "address_2": "Suite 300",
    "city": "Minneapolis",
    "state": "MN",
    "postcode": "55401",
    "country": "US",
    "email": "[email protected]",
    "phone": "7633551025"
  }
}

Paste your sample JSON into the JSON Template editor. Note: Field names (ex. "id" from the example above) may include only the following characters:

  • Upper and lowercase characters {A-Z} {a-z}, (accented characters not accepted)
  • Numbers {0-9}
  • Underscore {_}
  • Hyphen {-}
  • Colon {:}
  • Period {.}
  • Comma {,}
  • Single quote {'}
  • Forward slash {/}
  • Space { }
  • Square brackets {[]}
1339

The app will automatically generate a schema from your JSON sample which will be used for field mapping. You can always update your JSON sample, and resulting schema, by pasting a new version. Note: Date fields must be in ISO 8601 format.

1342

Step 4: Bulk Calls

Optionally, enable Bulk Calls to configure sending multiple transactional events in a single API call. This allows transaction events to be passed in as an array in the JSON rather than sending individually in separate calls. The array containing the events to be used for field mapping must then be selected from the dropdown.

1774

Step 5: Transaction Parameters

Next, identify and define the parameters from the JSON that you wish to use in the Cloud Content or for mapping to Eloqua Contacts or Custom Objects (CDOs). At a minimum, the first row must contain the parameter that contains the email address to which your transactional email should be sent. For each parameter, provide a display name, select the JSON parameter from the dropdown, and select the data type. Only the parameters defined in this section will be available in your Cloud Content or the mapping sections.

If your data includes an array of values (for example, an Order Confirmation JSON message may include the list of order line items including product name, product quantity, product price) you will see an array symbol [] within the Transaction Parameter (JSON) dropdown. When mapping array values to an Eloqua Contact field, array values will be separated by a :: (double-colon) delimiter. Values will be truncated if they are longer than the Eloqua field data type length:

  • Data Type Text and Field Type Textbox: 100 characters
  • Data Type Text and Field Type Picklist: 100 characters
  • Data Type Text and Field Type Multi-Select Picklist: 1000 characters
  • Data Type Large Text and Field Type Textbox: 32000 characters
  • Data Type Numeric and Field Type Textbox: 19 characters
1329

Click the Add button to add additional parameter mappings.

Step 6: Field Mapping

Optionally, you can map your transaction parameters to the associated Eloqua Contact or one or multiple CDOs. This step is not required to send your transactional emails, but may be useful if you want to save some of your transactional data within Eloqua.

First, click the +Add button in the Field Mapping section to create a new mapping. Toggle between Contact or CDO by clicking the icon to the far left of the mapping row. If mapping to a CDO, use the typeahead search to find and select the CDO you wish to map to.

950 1033

Next, click Configure in the mapping row. In the mapping window, map the desired transaction parameters configured in step 5 to the Contact or CDO fields. Additionally, you can optionally choose to map the entire JSON payload to a field.

1798

🚧

CDO Mapping Required Fields

If mapping to a CDO, you must include the CDO's unique ID and the email address if your CDO has those fields configured (see the last two fields in the screenshot below from the Custom Object Details page). Map the unique ID field in the green row 1 if it has one. The email address can be mapped anywhere in the mapping. For more on Eloqua Custom Objects, including the unique ID field, see Eloqua's documentation.

1182

Step 7: Dynamic Links

Optionally, dynamic links that can be used within Email Cloud Content can be created using non-array mapped parameters specified in the Field Mapping. To create a new dynamic link, click the +Add button.

1811

Use the editor to type in your protocol (https:// or http://) and base URL, then drag and drop field merges to fill in any path variables or query parameters. Click on the pencil () icon to edit a link. Click on the trashcan () icon to remove a link.

1795

Step 8: Event Status Callback

Optionally, status callbacks can be configured for failed or both failed and successful events. First, select the preferred security method and associated credentials similar to step 2.

Next, select an event status to determine for which types of events you wish to receive a status callback (Testing Mode and Enbabled, Enabled Only, or Testing Only).

1922

Next, select to receive callbacks for Failed Events Only or both Failed and Successful Events.

1910

Finally, select any mapped parameters to be included in the event status callback.

1918

Step 9: Enable Transactional Event

To enable your transactional event, click the Enabled toggle.

1336

Click the Save button to save your configuration. Once saved, your event will be enabled to receive transactional calls until you disabled it or put it in Test Mode.

Testing Mode

Enable Event Testing and specify a testing email address to test your event confirmation. NOTE, enabling Event Testing will automatically disable the app if it was set as Enabled.

1335

When Event Testing is enabled, any transaction event sent to the event endpoint will result in an email being sent to the specified testing email address regardless of the email provided in the JSON message. If an Eloqua Contact does not exist for the testing email address, a new one will be created. Any Eloqua Contact fields specified in the optional field mapping (e.g., First Name, Last Name, etc.) will be updated.

Transaction Event Log

When a Transaction Event is enabled or in Testing mode, a log of all events is captured and available by clicking on the chart icon.

2310

Mouse over the Request Body column to view more of the transaction request. Click on a request to view the entire request message. You can copy the message by clicking the copy () icon.

1244