Oracle Eloqua, part of Oracle's Marketing Cloud suite of products, is a cloud based B2B marketing platform that helps automate the lead generation and nurture process. It enables the marketer to plan and execute marketing campaigns while delivering a personalized customer experience to prospects.
In this blog I will describe how to integrate Eloqua with other SaaS applications using Oracle's iPaaS platform, the Integration Cloud Service(ICS).
ICS provides an intuitive web based integration designer for point and click integration between applications, a rich monitoring dashboard that provides real-time insight into the transactions, all of it running on a standards based, mature runtime platform on Oracle Cloud. ICS boasts of a large library of SaaS, Application, as well as Technology Adapters that add to its versatility.
One such adapter is the Eloqua adapter, which allows synchronizing accounts, contacts and custom objects with other applications. The Eloqua Adapter can be used in two ways in ICS:
As the target of an integration where external data is sent to Eloqua,
Or as the source of an integration where contacts(or other objects) flowing through a campaign or program canvas in Eloqua are sent out to any external application.
This blog provides a detailed functional as well as technical introduction to the Eloqua Adapter's capabilities.
The blog is organized as follows:
Eloqua Adapter Concepts
Installing the ICS App in Eloqua
Creating Eloqua connection
Designing the Inbound->Eloqua flows
Designing the Eloqua->Outbound flows
This blog assumes that the reader has basic familiarity with ICS as well as Eloqua.
In this section we'll go over the technical underpinnings of the ICS Eloqua adapter.
ICS Adapter is also referred to as ICS Connector, they mean the same.
The ICS adapter can be used in ICS integrations for both triggering the integration and as target(Invoke) within an integration.
When used as target :
The adapter can be used to create/update Account, Contact and custom objects defined within Eloqua.
Under the hood the adapter uses the Eloqua Bulk 2.0 APIs to import data into Eloqua. More on this later.
When used as trigger :
The Eloqua Adapter allows instantiating an ICS integration when a campaign or program canvas runs within Eloqua.
The adapter must be used in conjunction with a corresponding 'ICS App' installed within Eloqua.
Installing the ICS App is mandatory for triggering ICS integrations. The next section describes the installation.
The marketer in Eloqua uses this app as a step in his campaign, and the app in turn invokes the ICS endpoint at runtime. The image below shows a sample ICS App in use in a campaign canvas within Eloqua:
The Eloqua ICS App resides within the Eloqua AppCloud, and complements the ICS Eloqua Adapter such that contacts and other objects flow out from the campaign, into the ICS App and eventually to the ICS integration. The image below describes this.
As explained above, installing the ICS App in Eloqua is mandatory for the Eloqua->Outbound scenarios.
The app is available in Oracle Marketplace, and the installation is straightforward:
Open the ICS App on Oracle Marketplace at https://cloud.oracle.com/marketplace/app/AppICS
Click 'Get App'. Accept the terms and conditions in the popup. Click 'Next'. This will redirect you to your Eloqua login page. Sign in, and click 'Accept and Install'
The next page takes you to the ICS configuration, where you need to provide the ICS URL, username and password. Click 'Save'.
Click 'Sign In' on the next page, thus providing the app access to Eloqua on your behalf(OAuth2).
Click 'Accept' on the next page.
The ICS App is now installed and ready to use as an 'Action' in Eloqua Canvas.
Now we will look at creating Eloqua connections and integrations in ICS.
At this point ICS authenticates with Eloqua using the credentials provided above. The authentication process depends on the connection role:
Log on to the ICS home page. Click on 'Create Connections', then 'New Connection' , and choose 'Eloqua'.
Name the connection appropriately.
The Connection Role can be:
Click 'Create'. Click on the 'Configure Security' button, and enter the Eloqua Company name, username and password. Then click on 'Test'.
If 'Invoke' role, then ICS performs an HTTP Basic Authentication to https://login.eloqua.com using base64-encoded "<company>\<username>:<password>" string. This process is described in more detail here.
If 'Trigger' or 'Trigger and Invoke' role, then along with the above test ICS also reaches out to Eloqua AppCloud and checks if the Eloqua ICS App has been installed. If not installed then the connection test will fail.
Once the connection test is successful, save the connection.
Now that the connection has been defined, we can use the Eloqua adapter in an ICS integration to sync data. Let's take a look at designing the Inbound->Eloqua usecases, i.e. where Eloqua is the target application.
The Eloqua adapter for inbound->Eloqua flows only relies on the Bulk 2.0 APIs and doesn't need the ICS App to be installed in Eloqua.
Below are the steps to configure the adapter.
Create an ICS integration, and drag the Eloqua connection on the target or as an invoke activity in an orchestration.
Name your endpoint and click Next.
On the operations page, you can choose the Eloqua business object that needs to be created/updated, as well as fields within the object. You can choose the field to be uniquely matched on, etc.
You can also set the Auto-Sync time interval such that periodically the Eloqua data inserted into staging area will be synced to actual Eloqua tables.
Finish the wizard, complete the rest of the integration, and then activate it.
At runtime, since we know that under the hood the Bulk Import APIs are being used, the following specific events happen:
Depending on the business object and the fields chosen, an import definition is created by POSTing to the "/bulk/2.0/<object>/imports/" Eloqua endpoint.
This returns a unique URI in the response, which is used to POST the actual data to Eloqua. Thus, as data gets processed through the ICS integration, it reaches the Eloqua Invoke activity, which internally uses the URI returned above to POST the data to Eloqua. The data is now in the Eloqua staging area, ready to be synced into Eloqua.
Now, depending on the 'Auto-Sync' interval defined in design-time, periodically the '/bulk/2.0/syncs' endpoint is invoked which moves the data from the staging area to Eloqua database tables.
The Bulk API steps above are described in more detail here.
Design time :
Create an ICS integration, and drag the Eloqua connection as the source of the integration.
Select the business object, select the fields, followed by selecting the response fields.
Finish the wizard. Complete the integration and activate it.
When the integration is activated, ICS makes a callout to the Eloqua ICS App, registering the integration name, its ICS endpoint, and request and response fields chosen above.
At this point, back in the Eloqua UI, the marketer can configure the ICS App in her campaign by choosing among the activated ICS integrations and configuring them appropriately. For example, the screenshot below shows the ICS App's 'cloud action' configuration screen from a sample Eloqua campaign, after an integration called 'eloqua_blog' with the Eloqua Adapter as source is activated:
The Marketer now runs her campaign. Contacts start flowing through various campaign steps, including the ICS App step, at which point the ICS App gets invoked, which in turn invokes the configured ICS integration.