Get and export data overview including via REST API

You have two integration methods to select from when exporting data from ion to your Eloqua instance (also known as an “Add Lead” integration): the REST API method and the Post to Web Form method. Both methods can work seamlessly with your ion creatives. The best method for you will depend on how you like to trigger automation in Eloqua and whether you intend to pass data collected in ion to custom data objects in Eloqua.

REST API

Ion is an Oracle Silver Partner. Our native integration creates/updates contacts directly in your Eloqua lead table. This method often requires less effort to update or expand your integration in the future. However, it won’t trigger form processing steps or support creation of segments filtered on form completion, since there was no Eloqua form submitted. It also cannot interact with custom data objects.

Export Data via REST API

If needed, please contact Eloqua support for guidance in obtaining these items:

  • Eloqua user name
  • Eloqua password
  • REST API endpoint URL

There are few steps you’ll need to take in ion prior to setting up the integration, listed below:

  • Create data collection fields
  • Create ion form(s)
  • Set up testing creative

1. Add Eloqua account credentials to ion

You can enter your Eloqua credentials directly through your ion console by following the instructions below.

  1. Click the Integrations tab in your console’s side nav
  2. Click “Set up account credentials” button
  3. Under Eloqua, click the “New eloqua credential” button
  4. Add a friendly label for your account then click “authorize eloqua”
  5. Add your Eloqua credentials into the embedded Eloqua interface and then click “Accept” to allow ion to access the Eloqua REST API

2. Create field mapping

Taking the steps below will map your ion data collection fields to their corresponding Eloqua API field names. To get started, add a new field mapping:

  1. Navigate back to the Integrations screen
  2. Click green “New field mapping” button
  3. Label the field mapping and optionally add a description
  4. From the Integration type menu, select “Eloqua”
  5. Save

3. Add Outbound fields to field mapping

Outbound fields define the data you extend from ion to Eloqua

  1. Click green “New outbound field” button
  2. Add a field by selecting the field type from the Source dropdown
    • To add a form field, hidden field or query string parameter, select Data Field and pick the category then data collection field
    • OR, to add an ion Core field, select Core Field then pick the field you seek to include
    • OR, to export multiple ion fields to one external field, pick Mashup and plug {% raw%} {{DataName}} {% endraw %} {% raw%} {{DataName2}} {% endraw %}, etc. into the editor
    • OR, to reformat a value prior to export, pick Javascript code and add logic around the value collected in ion. To access data collection fields via Javascript, use respondent.dataname.
  3. Optionally check the box to make it required for this field to have data in order for the integration to run
  4. Optionally add a default value (to a field that is not marked as required)
  5. Select the Eloqua field from the drop-down menu of your Eloqua API field names
  6. Repeat these steps for each field that should be included in the Field Mapping
  7. Skip adding Inbound fields

4. Create integration

  1. Navigate back to the Integrations screen
  2. Click into the Integrations tab
  3. Click green “New integration” button
  4. Enter label
  5. Optionally add a description
  6. Select the Field Mapping you’ve just created
  7. Set maximum retries
    • If there is a service interruption with the external platform, ion will retry the post on the top of the hour for as many retries as you indicate here.
  8. Select Add Lead as the API method
  9. Optionally add yourself to the debug distribution list for testing
    • This will deliver an email to the designated address when the integration runs that displays the request and response from Eloqua

5. Add integration to ion pages

The ion platform runs the integration based on rules you create. Rules can be added to any actionable item in your ion creative. Integration rules are typically run at the form-level, upon form submission, or on an assessment step. Follow the steps below to add the integration to your ion pages.

  1. Navigate into the creative
  2. Click on the form, button or link you seek to make the trigger to run your integration
  3. In Creative Studio, click on +rules
  4. Select the condition that needs to be met to run the integration
    • “No conditions required” is typically used
  5. Select “Run integration” then select your Eloqua integration as the action
  6. Save

6. Test integration

To test your integration, use the creative you set up prior to beginning the integration steps. Please note, integrations do not run in Preview Mode so you’ll want to open a URL for testing. The integration will run once you submit the ion form, or complete the action that runs the integration rule. If you’re on the debug email distribution list, you’ll receive an email that displays the data you transferred and response from Eloqua. You’ll also want to verify success by ensuring the lead was created in your Eloqua instance.

 

Get data via REST API

You can leverage ion’s Get Lead integration with the Eloqua REST API to optimize your ion experiences. This integration enables you to retrieve data from Eloqua based on a respondent’s email address. You can leverage Get Lead to pre-populate (or shorten) ion forms, auto-segment respondents and for progressive profiling.

This document provides step-by-step instructions to set up a REST API integration with Eloqua to get lead data. We’ll use the integration to pre-populate an ion form in this document, but, as noted, there are a few different ways you can use Get Lead to enhance your ion experiences.

There are few items you’ll need to a roundup from Eloqua prior to setting up the integration, listed below:

  • Eloqua Username
  • Eloqua Password
  • REST API Endpoint URL

There are few items you’ll need to have ready in ion prior to setting up the integration, listed below:

Check out the “Before you begin” support post for guidance in creating these items.

  • Create data collection fields that will store Eloqua data
  • Create ion form(s) that will populate with Eloqua data
    • You can pass an email address value into the ion page on the query string, and populate a form on the landing page with data
    • OR, you can collect email address on an initial form, and populate a subsequent form with Eloqua data
  • Set up testing creative

1. Add Eloqua account credentials to ion

  1. Click the Integrations tab in your console’s side nav
  2. Click “Set up account credentials” button
  3. Under Eloqua, click the “New eloqua credential” button
  4. Add a friendly label for your account then click “authorize eloqua”
  5. Add your Eloqua credentials into the embedded Eloqua interface and then click “Accept” to allow ion to access the Eloqua REST API

2. Create field mapping

Taking the steps below will enable you to extend an email address value to Eloqua and map the data points returned to their corresponding ion data collection fields. To get started, add your new field mapping:

  1. Navigate back to the Integrations screen
  2. Click green “New field mapping” button
  3. Label the field mapping and optionally add a description
  4. From the Integration type menu, select “Eloqua”
  5. Save

3. Add Email Address as the Outbound field

The email address value will be used as the key to retrieve data from Eloqua.

  1. Click green “New outbound field” button
  2. Select Data field from the Source drop-down
  3. Select Contact Info > Email Address
  4. Make the field required for the integration to run
  5. Select the corresponding Eloqua Email Address field
  6. Save

4. Create Inbound fields

Inbound fields will map the data Eloqua returns into their corresponding ion data collection fields.

  1. Click green “New inbound field” button
  2. From the Target dropdown menu, select Data field and then select the ion data field you seek to populate with Eloqua data
    • To pre-populate ion forms with Eloqua data, be sure to select the data field used on your form
  3. From the Source dropdowns, select the Eloqua field you seek to pull data from
  4. OR, select Javascript code if you seek to transform the Eloqua data prior to storing it in ion data collection
    • Use responseBody.eloqua_field_name to access the Eloqua field via Javascript
  5. OR, select Response body to save the response from Eloqua to an ion data field
  6. Save
  7. Repeat these steps for each Eloqua data field you seek to save into ion data collection

5. Create integration

  1. Navigate back to the Integrations screen
  2. Click into the Integrations tab
  3. Click green “New integration” button
  4. Enter label
  5. Optionally add a description
  6. Select the Field Mapping you’ve just created
  7. Skip Maximum retries
  8. Select Get Lead as the API method
  9. Select the outbound Email Address field
  10. Optionally add yourself to the debug distribution list for testing
    • This will deliver an email to the designated address when the integration runs that displays the request and response from Eloqua
    • Check Only send error emails if you want to receive the debug email only when there is an error

6. Add integration to ion pages

The ion platform runs the integration based on rules you create. For Eloqua Get Lead, the rule will typically run behind a form that collects email address (so that the Eloqua data is available for use on the subsequent page), or the rule is run at the page-level of a landing page where email address is passed in on the query string.

  1. Navigate into a testing creative
  2. If passing email address into your page from the query string, under the Page tab in creative studio, click on +RULES
  3. Add the following rule:
    • Condition: No conditions required
    • Action: Run integration (select Elq Get Lead integration)
    • OR, if collecting email address on an initial form, run the above rule at the form-level
  4. Save

7. Test integration

Please note, integrations do not run in Preview Mode, so you’ll want to open a URL for your testing creative. Either pass email address into your ion page on the query string, or submit your initial form that collects email address. If passing email address into ion on the query string, be sure that the parameter name you append to the URL matches the “data name” of the ion data collection field selected as the outbound field in your Field Mapping.

Once the integration runs, the form you seek to pre-populate will display the data retrieved from Eloqua. If you’re on the debug email distribution list, you’ll receive an email that displays the request and response from Eloqua.

Once you’ve completed these steps, your integration is ready for use. You can add the rule to run the integration on all applicable creatives.

As noted, Eloqua Get Lead can be used to accomplish other objectives. Here are some examples that can be accomplished using this integration and ion’s Rules engine:

  • Shorten or replace forms
  • Auto-segment respondents
  • Build progressive profiles
  • Serve-up dynamic content based on Eloqua data

Post to Web Form

A Post to Web Form integration is what it sounds like: data collected in ion is re-posted to a form you’ve published in Eloqua. While the customer sees a form you built in ion (and data is saved to your ion console), Eloqua treats it like someone completed the Eloqua form directly. This method often requires more effort to update or expand your integration in the future, as any changes must be made to both your ion integration and your Eloqua form(s). The benefits of this method are the ability to trigger automation in Eloqua based on form completion, as well as the ability to pass data to a custom data object (via form processing steps on your Eloqua form).

Check out the table below for a more detailed comparison of the methods.

  Eloqua REST API Eloqua Post to Web Form
How does it work? A connection is established between your ion console and your Eloqua instance. Next a field mapping is completed in ion to define which ion fields should be exported and how they correspond to your Eloqua Contact record fields.

 

When the integration runs, an Eloqua Contact record will be created or updated (key: email address).

A form is published in Eloqua to receive your ion data. Next a field mapping is completed in ion to define which ion fields should be exported and where that data should be submitted in your Eloqua form. That field mapping includes a hidden field that specifies the Eloqua form to post to, so you can support multiple Eloqua forms with a single integration in ion.

 

When the integration runs, data collected in ion is re-posted to the Eloqua form.

What kind of data can be sent to Eloqua? All types of data can be seamlessly passed to a contact record in Eloqua. This includes Basic Lead Data, ion Core Data, data passed on the query string (like tracking parameters), and interaction data (like a calculator input or an assessment result).

 

Note: Integration services may be limited to certain data types. Check with your Customer Success Manager if you are unsure what you’ve purchased.

All types of data can be seamlessly passed to a contact record in Eloqua. This includes Basic Lead Data, ion Core Data, data passed on the query string (like tracking parameters), and interaction data (like a calculator input or an assessment result).

 

Using form processing steps on your Eloqua form, you can also pass data to a custom data object.

Note: Integration services may be limited to certain data types. Check with your Customer Success Manager if you are unsure what you’ve purchased.

What are my options to manage sensitive data? Field-level security controls are available. The sensitive data expiration setting allows you to mark data in a given field for automatic deletion at a specific time interval (e.g. delete 72 hours after last contact). Field-level security controls are available. The sensitive data expiration setting allows you to mark data in a given field for automatic deletion at a specific time interval (e.g. delete 72 hours after last contact).
How will I build the form my visitors see? Can I change the styling? You will use ion’s form building components. This gives you maximum control of the look, feel, and flow of your form experience, and allows you to leverage the branded theme built for you in ion. You will use ion’s form building components. This gives you maximum control of the look, feel, and flow of your form experience, and allows you to leverage the branded theme built for you in ion.
Can my forms be pre-populated with known lead data? Forms can be pre-populated based on ion data or (if a Get Lead integration is setup) based on Eloqua + ion data.

 

Note: Integration services may not include a Get Lead integration. Check with your Customer Success Manager if you are unsure what you’ve purchased.

Forms can be pre-populated based on ion data or (if a Get Lead integration is setup) based on Eloqua + ion data.

 

Note: Integration services may not include a Get Lead integration. Check with your Customer Success Manager if you are unsure what you’ve purchased.

How often are my leads sent to Eloqua? Leads are immediately sent to Eloqua each time the integration runs. Most ion users apply their integration to run on the submission of a form in their ion creative. Leads are immediately sent to Eloqua each time the integration runs. Most ion users apply their integration to run on the submission of a form in their ion creative.
What happens if there is an Eloqua service interruption? Visitors will still be able to submit forms and form data will be saved according to your configuration in ion. We’ll retry the post once an hour until successful, up to the maximum number set in your integration. (default: 50 retries) Visitors will still be able to submit forms and form data will be saved according to your configuration in ion. We’ll retry the post once an hour until successful, up to the maximum number set in your integration. (default: 50 retries)

Post data to Elq web form

Ion can reliably post data to existing web forms published in Eloqua’s marketing automation platform. Once integrated, your ion experiences will seamlessly post the data you define to your Eloqua form(s). 

Before we begin

There are a few items you’ll need to roundup from Eloqua before beginning, listed below:

  • Eloqua-supplied Basic Page View Tracking script
  • Eloqua endpoint URL and field names
  • Eloqua Site ID and form name(s)

The Eloqua form HTML contains your Site ID, endpoint URL and field names.

There are a few steps to take in ion before you begin listed below:

  • Create data collection fields
  • Create data collection fields for Eloqua hidden fields, using the following data names:
    • elqSiteId
    • elqFormName
    • elqCustomerGUID
    • elqCookieWrite
  • Create ion form(s)
  • Set-up testing creative 

Let’s get started!

1. Create field mapping

Taking the steps below will create a field map between your ion data collection fields to their corresponding Eloqua field names.

  1. Click the Integrations tab in your console’s side nav
  2. Click the green “New field mapping” button
  3. Label the field mapping and optionally add a description
  4. From the Integration type menu, select “Post to Web Form”
  5. Save

2. Add Outbound fields

Outbound fields define the data you extend from ion to your external web form. Refer to your Eloqua form HTML for the proper external field names. Be sure to add your Eloqua hidden fields, using the values from the Eloqua form as the default value for the Outbound field. Please note, elqCustomerGUID will not have a default value. If you are posting to multiple Eloqua forms, you can save the the elqFormName value via an ion form rule. We’ll cover how to do this later in the document.

  1. Click the green “New outbound field” button to add a new field to your field mapping
  2. When adding a new field, you will either select from the Data Collection drop-down menus, Core Field drop-down menu, implement a mashup template or add a field via JavaScript
    • To add a form field, use the Data Collection drop-down menus to select the data field category then data collection field
    • OR, to add an ion Core field, select from the Core Field drop-down menu
    • OR, to export multiple ion fields to one external field, use the Mashup Field by plugging {% raw%} {{DataName}} {% endraw %} {% raw%} {{DataName2}} {% endraw %}, etc. into the editor
    • OR, to reformat a value prior to export, use the JavaScript field to add logic around the value collected in ion. To access data collection fields via Javascript, use respondent.dataname.
  3. Optionally make your field required to run the integration
  4. Optionally add a default value
  5. Enter the external field name
  6. Save
  7. Repeat these steps for each field that should be included in the Field Mapping

3. Create Integration

  1. Navigate back to the Integrations screen
  2. Click into the Integrations tab
  3. Click the green “New integration” button
  4. Enter label
  5. Optionally add a description
  6. Select the Field Mapping you’ve just created
  7. Paste the Eloqua Form URL into the editor
    • This is the “post to” or end point URL of your web form.
  8. Set maximum retries
    • If there is a service interruption with the external platform, Ion will retry the post on the top of the hour for as many retries as you indicate here.
  9. Select POST as the method
  10. Optionally add Debug email address
    • Email addresses specified here will receive an email each time the integration runs that displays the data posted and response received. This is feature typically only used for testing and troubleshooting.
  11. Save

4. Add integration to your Ion pages

The ion platform runs the integration based on rules you create. Rules can be added to any actionable item in your ion creative. Integration rules are typically run at the form-level, upon form submission, or on an assessment step. Follow the steps below to add the integration to your ion pages.

  1. Navigate into the creative
  2. Click on the form submit button or link you seek to make the trigger to run your integration
  3. In Creative Studio, click on +rules
  4. Select the condition that needs to be met to run the integration
    • “No conditions required” is typically used
  5. Select “Run integration” as the action
  6. Save
  7. Repeat for each applicable creative

5. When posting to multiple Eloqua forms…

If you seek to post data to multiple Eloqua forms, you can save the elqFormName value via a form-level rule. The value you save here will overwrite the default value in the export format. This rule action needs to be implemented above the rule to run the integration.
 

Condition: No conditions required

Action: Save into database – elqFormName = value

6. Optionally implement Eloqua visitor tracking script

Eloqua provides visitor tracking script that can be implemented on your ion experiences. The Basic Page View tracking script can be found in the Eloqua Asynchronous Visitor Tracking Scripts document and a sample is included below. Replace ‘SiteId’ on line three with your Eloqua SiteId.
 

a. Store Eloqua script Ion Libraries

  1. In ion, navigate to the Libraries menu and select Scripts
  2. Add a new category labeled “Eloqua” or navigate into an existing category
  3. Click green “New script” button
  4. Use “Campaign – Head” as the label
  5. Paste the script into the editor

b. Add Eloqua script to ion Campaigns

  1. Navigate to your Campaign Management screen
  2. Click into the Actions dropdown menu and select “Edit campaign”
  3. Select  Eloqua > Campaign – Head script from the head tag drop-down menus
  4. Save
  5. Repeat for each applicable Campaign

c. Sample Eloqua Vistor Tracking Script:

<script type="text/javascript">

var _elqQ = _elqQ || [];

_elqQ.push(['elqSetSiteId', 'siteId']);

_elqQ.push(['elqTrackPageView']);

(function () {

function async_load() {

var s = document.createElement('script');

s.type = 'text/javascript';

s.async = true;

s.src = '//img.en25.com/i/elqCfg.min.js';;

var x = document.getElementsByTagName('script')[0];

x.parentNode.insertBefore(s, x);

}

if (window.addEventListener)

window.addEventListener('DOMContentLoaded', async_load, false);

else if (window.attachEvent) 

window.attachEvent('onload', async_load);

})();

</script>

7. Optionally add script to save elqCustomerGUID into data collection

You’ll add one more code block to your ion form pages in order to save the Eloqua GUID value and store it in an ion data collection field. This enables you to include the GUID in your post to the Eloqua form.
 

a. Create ion data collection field to save GUID value

  1. Navigate to Data Management > Data Collection
  2. Navigate into an existing category or create a new data field category
  3. Add a new data field with a data name of elqCustomerGUID
  4. Save

b. Store GUID script in ion Libraries

  1. In ion, navigate to the Libraries menu and select Scripts
  2. Add a new category labeled “Eloqua” or navigate into an existing category
  3. Click green “New script” button and use “Form page – Body” as the label
  4. Paste the script into the editor

c. Add GUID script to form pages

  1. Navigate into your ion creative’s form page
  2. Click +scripts from the Page tab in your creative studio
  3. Select Eloqua > Form page – Body from the closing body tag drop-down menus
  4. Save
  5. Repeat for each applicable form page

d. Example script to save GUID:

<script type="text/javascript">

var timerId = null, timeout = 5;

function WaitUntilCustomerGUIDIsRetrieved() {

if (!!(timerId)) {

if (timeout == 0) {

return;

} 

if (typeof this.GetElqCustomerGUID === 'function') {

var elq_GUID = GetElqCustomerGUID();

liveballData("elqCustomerGUID", elq_GUID);

return;

}

timeout -= 1;

}

timerId = setTimeout("WaitUntilCustomerGUIDIsRetrieved()", 500);

return;

}

window.onload = WaitUntilCustomerGUIDIsRetrieved;

_elqQ.push(['elqGetCustomerGUID']);

</script>

8. Test integration

To test your integration, use the testing creative you set up prior to beginning the integration steps. Please note, integrations do not run in Preview Mode so you’ll want to open a URL for testing. The integration will run once you submit the ion form, or complete the action that runs the integration rule. If you’re on the debug email distribution list, you’ll receive an email that displays the data posted and response from the external server. You’ll also want to check that the data you submitted was received by and processed properly by Eloqua.

Nice work!

Once you’ve completed these steps, your integration is ready for use. You can add the rule to run the integration on all applicable creatives. 


If you have any questions, please contact us at [email protected].  

Share this: