Eloqua web services api 1.2 user guide v1.0.1

© 2008-2014 Oracle Corporation. All rights are reserved. Trademarks Eloqua™, Eloqua Conversion Suite™, Eloqua Lite™, Eloqua

Express™, Eloqua Team™, Eloqua Enterprise™, and Eloqua Hypersites™ are trademarks or registered trademarks of Eloqua Corporation.

All other products mentioned are trademarks or registered trademarks of their respective owners.

ELOQUA USER GUIDE

WEB SERVICES API V1.2

VERSION 1.0.1

FEBRUARY 7, 2014

866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation

This page was intentionally left blank.


TABLE OF

CONTENTS

Conventions Used in This User Guide ............................................................... 1

About Eloqua ........................................................................................................ 1

About Web Services ............................................................................................ 1

Possible Uses of the API ..................................................................................... 2

Eloqua API ............................................................................................................ 2

SUPPORTED PLATFORMS ......................................................................................................... 3 STANDARD TECHNOLOGIES ..................................................................................................... 3 ELOQUA API SUPPORT POLICY ................................................................................................ 3 RELATED RESOURCES .............................................................................................................. 3 END OF LIFE ................................................................................................................................ 4

Getting Started ..................................................................................................... 4

STEP 1: REQUEST THE WEB SERVICES API INTEGRATION ................................................... 4 STEP 2: OBTAIN COMPANY NAME, USERNAME, AND PASSWORD ....................................... 4 STEP 3: RETRIEVE WSDL ........................................................................................................... 4 STEP 4: IMPORT WSDL ............................................................................................................... 5

FOR JAVA ............................................................................................................................... 5 FOR VISUAL STUDIO ............................................................................................................. 6

STEP 5: WRITE THE CODE REQUIRED ...................................................................................... 7

Eloqua Objects Overview .................................................................................... 7

Object Model ......................................................................................................... 7

ENTITIES ...................................................................................................................................... 7 ENTITY RELATIONSHIPS ............................................................................................................ 8 ENTITY METADATA ..................................................................................................................... 9 ...................................................................................................................................................... 9 ENTITY - GLOBAL TYPES ......................................................................................................... 10 BASE ENTITY TYPES ................................................................................................................ 10 ASSETS ...................................................................................................................................... 11 ASSET METADATA ................................................................................................................... 11 CRM INTEGRATION CONSIDERATIONS .................................................................................. 12 SCENARIO 1: MARKETING ACTIVITY INTEGRATION ............................................................ 13 PROCESSED ACTIVITY QUEUE ............................................................................................... 14 SCENARIO 2: SYNCHRONIZE LEAD/CONTACT DATA ........................................................... 16 CRM/ELOQUA DATA MODEL ................................................................................................... 17 FIELD TYPES ............................................................................................................................. 18 SECURITY .................................................................................................................................. 19 SYSTEM FIELDS ........................................................................................................................ 20

API Call Basics ................................................................................................... 20


API CALL CHARACTERISTICS ................................................................................................. 20 ERROR HANDLING .................................................................................................................... 20

Additional Considerations ................................................................................ 21

USAGE METERING .................................................................................................................... 21 COMPRESSION ......................................................................................................................... 22 INTERNATIONAL CHARACTERS .............................................................................................. 22 ELOQUA IDENTIFICATION CODES .......................................................................................... 22

API Reference ..................................................................................................... 22

METADATA ................................................................................................................................ 22 ENTITY METADATA ................................................................................................................... 22 ENTITY METADATA OPERATIONS .......................................................................................... 23

LISTENTITYTYPES ............................................................................................................... 23 DESCRIBEENTITYTYPE ....................................................................................................... 25 DESCRIBEENTITY ................................................................................................................ 27

ENTITY OPERATIONS ............................................................................................................... 30 CREATE ................................................................................................................................ 30 RETRIEVE ............................................................................................................................. 34 UPDATE ................................................................................................................................ 37 DELETE ................................................................................................................................. 41 QUERY .................................................................................................................................. 44

ASSET METADATA ................................................................................................................... 48 ASSET METADATA OPERATIONS ...................................................................................... 49 LISTASSETTYPES ................................................................................................................ 49 DESCRIBEASSETTYPE ........................................................................................................ 51

Data Transfer Service ........................................................................................ 53

DATA EXPORT OPERATIONS .................................................................................................. 54 INITIALIZEDATAEXPORT ..................................................................................................... 54 DATAEXPORTSTATUS......................................................................................................... 57 GETDATAEXPORTFILE ........................................................................................................ 59

DATA IMPORT OPERATIONS ................................................................................................... 63 INITIALIZEDATAIMPORT ...................................................................................................... 63 DATAIMPORTSTATUS ......................................................................................................... 66

Errors................................................................................................................... 69

1 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation

Conventions Used in This User Guide

The following conventions are used in the Eloqua® Web Services API Beta v1.2 User Guide.

Bold text is used to indicate the start of procedures (in the format "To do xyz...:").

Bold text is used to indicate elements or controls found in the User interface.

Bold text is used to introduce each Note, Tip and Warning! If you are viewing this document in color, a

Warning! also appears using a violet-colored font.

Text describing controls is generally included in full in procedures unless it is quite lengthy, in which case

only the first word or few words are indicated followed by ellipses (for example: No, send document...).

Path names, file names, code samples, and file extensions are rendered using the

Courier New font.

About Eloqua

Eloqua Conversion Suite is the industry’s leading family of demand generation applications for business-to-

business (B2B) marketers who need to generate a continuous flow of qualified leads for their sales teams.

Our solutions—Eloqua Lite™, Eloqua Express™, Eloqua Team™ and Eloqua Enterprise™—integrate

Email, direct mail, Forms automation, website analytics and event-triggered automation with Sales Force

Automation (SFA) to continuously, repeatedly, and measurably create demand for your company’s products

or services. As a result, your sales team gets better quality sales leads, higher win rates and accelerated

sales cycles.

Eloqua acts as a front-end marketing database that captures Form submissions from your website and can

then nurture leads before passing them into your CRM system for the salespeople to see.

For more information about Eloqua you can visit our website at www.eloqua.com or use the online

documentation and training portal within the Eloqua application.

About Web Services

The term “web services” describes a standardized way of integrating Web-based applications over the Web.

Web services allow organizations to communicate with each other, without intimate knowledge of each

other’s IT systems.

API stands for Application Programming Interface. Simply put, the API allows a software’s functionality to be

extended to 'the outside world.' Programmers can write their own code that exercises the functionality that

the API exposes.

Web services rely on the following core technologies:

Extensible Markup Language (XML)—XML is a general-purpose specification for creating custom markup

languages. It is classified as an extensible language because it allows its users to define their own

elements. Its primary purpose is to facilitate the sharing of structured data across different information

systems, particularly via the Internet, and it is used both to encode documents and to serialize data.

Web Services Description Language (WSDL)—WSDL, pronounced 'wiz-del' or spelled out as W-S-D-L, is

an XML-based language that provides a model for describing Web services. WSDL defines services as

collections of network endpoints or ports. The WSDL specification provides an XML format for documents

http://www.eloqua.com/

Eloqua® Web Services API v1.2 User Guide


for this purpose. The abstract definition of ports and messages is separated from their concrete use or

instance, allowing the reuse of these definitions.

Simple Object Access Protocol (SOAP)—SOAP is a protocol for exchanging XML-based messages over

computer networks, normally using HTTP/HTTPS. SOAP forms the foundation layer of the web services

protocol stack by providing a basic messaging framework upon which abstract layers can be built. Web

services messages are sent between the customer implementation of Web services and the SOAP

handler on the Eloqua web server.

For more information on Web services technologies, see http://www.w3.org/2002/ws.

Possible Uses of the API

The Web Services API allows companies to build programs to integrate with Eloqua. Some examples of web

services integrations include the following:

Integration between Eloqua and CRM System—You can create a connector that polls Eloqua on a regular

basis for new marketing activities and Contact record changes and updates your CRM system from

Eloqua. For example, instead of using flat file batch transfers for integrating Eloqua with your CRM

system, you can now have near real-time updates between your systems. In addition, your CRM system

can call out to Eloqua and update information in your marketing database.

Updating Data Warehouses for analytics—Using the Eloqua Data Export service, you can now export

historical transactional data about website activity, Form submissions, Email activity, and other details for

analysis on a regular basis.

Connectors to External Web Services—By creating a polling connector service that Polls Eloqua for

certain actions or activities, you can trigger a web services call to another service that may append data or

begin a secondary process in another system using data passed over from Eloqua.

Eloqua API

The Eloqua Web Services API is intended to provide the ability for developers to easily integrate their

existing systems to the Eloqua platform and leverage its rich data store to provide actionable marketing

intelligence to the enterprise. To use this document and the Eloqua API, you need to have a good grasp of

fundamental web programming techniques and tools. This document will serve as a guide to the Eloqua

Web Services API, but does not function as an overall guide for Eloqua and its capabilities in general.

Note: Development platforms vary in their SOAP implementations. These differences may prevent

access to some or all of the features in the API. We recommend that you use Visual Studio 2005 or

higher if you are using Visual Studio for .NET development.

This first version of the API is focused on providing access to the primary data entities within Eloqua and

allowing developers to Create, Update, Retrieve and Delete records programmatically, as well as allowing

bulk export or import of large datasets. Future versions of the API will focus on performing actions and

leveraging other capabilities such as management of Contact groups, Programs, and marketing activities.

http://www.w3.org/2002/ws



SUPPORTED PLATFORMS

The Web Services API was designed using common web technologies that allow for interoperability

between systems. Specifically, the API is directly supported within two primary technology stacks: .NET and

Java. The API is SOAP-based and should be accessible from other platforms not listed here, but may

require libraries or components to be installed that support the appropriate standards.

The API works with current SOAP development environments, including, but not limited to, Visual Studio

.NET 2008, Eclipse using Apache Axis 2 + Rampart, and NetBeans 6 using the WSIT libraries. In this

document, we provide examples in Java and .NET. The Java examples are created in NetBeans 6.0.1 using

the WSIT 1.1 libraries (See: https://wsit.dev.Java.net/).

For more information about Apache Axis 2, go to http://ws.apache.org/axis2/.

For more information about Rampart 1.3, go to http://ws.apache.org/axis2/modules/rampart/1_3/security-

module.html.

STANDARD TECHNOLOGIES

Standard web technologies that are implemented in the Eloqua web services API include the following:

Simple Object Access Protocol 1.1 http://www.w3.org/TR/2000/NOTE-SOAP-20000508/

Web Service Description Language (WSDL) 1.1 http://www.w3.org/TR/2001/NOTE-wsdl-20010315/

WSS (WS-Security, OASIS) 1.0 http://www.oasis-open.org/specs/index.php#wssv1.0

ELOQUA API SUPPORT POLICY

Eloqua suggests that any applications being written using the API use the latest release version of the API.

New functionality and enhanced performance will be included and supported only on new releases of the

web services API. When a new version of the API is released, you will need to retrieve a new version of the

WSDL to see the new functions and schemas.

Our technical support team can provide limited assistance with API development and are mainly focused on

troubleshooting and resolving errors or investigating potential bugs within the API. They cannot provide any

support or advice for programming logic nor assistance with creating programs that use the API.

RELATED RESOURCES

There are numerous web resources available for getting more familiar with Eloqua’s capabilities and

functions. Below, we have listed some Eloqua-specific resources that are available to users of the

application.

Eloqua Training Resources Once you have logged in to the application, click on

the Training button in the top right-hand corner.

Eloqua Online Help When you are logged in, click Help in the upper right-

hand corner to open the online Help system.

https://wsit.dev.java.net/

http://ws.apache.org/axis2/

http://ws.apache.org/axis2/modules/rampart/1_3/security-module.html

http://ws.apache.org/axis2/modules/rampart/1_3/security-module.html

http://www.w3.org/TR/2000/NOTE-SOAP-20000508/

http://www.w3.org/TR/2001/NOTE-wsdl-20010315/

http://www.oasis-open.org/specs/index.php#wssv1.0



Eloqua Community Forums Go to eloquacommunity.com. Log in using your

Eloqua password. There is a specific forum for API

support and help.

END OF LIFE

The intention is to provide a fully backwards-compatible web services layer. However, if a change is required

that would cause a loss of functionality, there would be a major API version release. Eloqua does not

guarantee that an application written against one API version will work with future API versions: Changes in

methods and data representations are often required to further enhance the functionality we provide.

However, we make significant efforts to ensure that the API is consistent from version to version.

Getting Started

The Section below is for getting a quick start with the Eloqua API and the basic steps needed to get your

first Eloqua program up and running. This first demonstration program will show an example where a Form

submission to a web page could be used to create a new Contact in Eloqua and return the new EntityID of

the Contact.

The steps outlined in the following sections are required for this demonstration program.

STEP 1: REQUEST THE WEB SERVICES API INTEGRATION

For security reasons, the capability to use the API is not automatically enabled for all implementations of the

Eloqua application. Upon request, your Customer Success Manager (CSM) will enable the Web Service

Integration for your company.

STEP 2: OBTAIN COMPANY NAME, USERNAME, AND PASSWORD

In order to use the API, you need to get login information for the Eloqua system. There are three elements

needed to log in to Eloqua: CompanyName, Username, and Password. Speak to the Eloqua administrator in

your organization who can create a new user account. They will need to place the username that will be

used for API calls into the security group called “API Users” in order for you to be able to access the system

programmatically.

After receiving your new login from your administrator, you must log in to https://secure.eloqua.com in order

to change the initially-assigned password. The password you specify will be used when authenticating using

the API.

It is recommended that you use a distinct user for API operations when possible to avoid administrative

hassles such as a user being disabled that was used for integration purposes.

STEP 3: RETRIEVE WSDL

To access the Eloqua Web service, you need a Web Service Description Language (WSDL) file. The WSDL

file defines the Web service that is available to you. Your development platform uses this WSDL to generate

an API to access the Eloqua Web service it defines.

Retrieve the WSDL (Web Services Description Language) from one of the following two sources:

For Low-volume queries and entity updates use this WSDL:

https://secure.eloqua.com/



https://secure.eloqua.com/API/1.2/Service.svc?wsdl

To use the Eloqua Data Import or Export engine for bulk transfer of flat files through the API use this WSDL:

https://secure.eloqua.com/API/1.2/DataTransferService.svc?wsdl

For more information about WSDL, see http://www.w3.org/TR/wsdl.

STEP 4: IMPORT WSDL

Once you have the WSDL file, you need to import it into your development platform so that your

development environment can generate the necessary objects for use in building client Web service

applications in that environment. This section provides sample instructions for Apache Axis (Java) and

Microsoft Visual Studio. For instructions about other development platforms, see your platform’s product

documentation.

FOR JAVA

To use the Eloqua API in a NetBeans project, do the following:

To install NetBeans:

1. Install the latest NetBeans with Java JDK (NetBeans 6.0.1 + JDK 6 Update 6 as of this writing).

2. Once NetBeans is installed, install the following plugins using the NetBeans Plugins module (click

Tools > Plugins):

a. Web Services

b. Web Applications

c. WSDL

d. JAX-RPM Web Services

3. Download WSIT 1.1 (https://wsit.dev.Java.net/) and extract to a preferred location on your hard drive.

To create a new WSIT-enabled project:

1. Create a Java Application project in NetBeans providing any name and location you wish.

2. In the Projects window, right click on the Libraries Folder and click Add JAR/Folder.

3. Navigate to the folder where you extracted WSIT and open the lib directory.

4. Highlight all the JAR files in that folder and add them.

5. You are now ready to generate your service proxy using Eloqua’s WSDL files.

To create the web service client:

1. In the projects window, right click on your project and select New > Web Service Client.

2. Select WSDL URL and put the Eloqua wsdl URL in the textbox

(https://secure.eloqua.com/API/1.2/Service.svc?wsdl).

3. Type in a package name for the Eloqua service proxy.

4. Click Finish.



http://www.w3.org/TR/wsdl

https://wsit.dev.java.net/




To set up authentication:

1. In the projects window, expand the Web Service references folder.

2. Right click on the Eloqua service and select Edit Web Service Attributes.

3. Under the Security section, select Static authentication credentials and type in your Eloqua login

credentials in the format:

Username: CompanyName/UserName

Password: Password

FOR VISUAL STUDIO

Visual Studio languages access the API through objects that serve as proxies for their server-side

counterparts. Before using the API, you must first generate these objects from your organization's WSDL

file.

Visual Studio provides two approaches for importing your WSDL file and generating an XML Web service

client: An IDE-based approach and a command-line approach.

Note: Before you begin, the first step is to create a new application or open an existing application in Visual

Studio. In addition, you need to point to the WSDL files in Eloqua.

An XML Web service client is any component or application that references and uses an XML Web service.

This does not necessarily need to be a client-based application. In fact, in many cases, your XML Web

service clients might be other Web applications, such as Web Forms or even other XML Web services.

When accessing XML Web services in managed code, a proxy class and the .NET Framework handle all of

the infrastructure coding.

To access an XML web service from managed code:

Adding a reference to a .NET project is very straightforward. Follow the steps below:

To add the Service Reference:

1. Create a new project in any .NET language you prefer.

2. In the Solution Explorer, right click on your project and select Add Service Reference.

3. Type in the URL to the Eloqua WSDL (https://secure.eloqua.com/API/1.2/Service.svc?wsdl)

4. Provide a namespace for the Service proxy and click OK.

To set up Authentication:

Once you have your proxy setup, simply set the credentials on the proxy object to setup authentication.

C# Sample:

Suppose you called the service namespace EloquaService; the code to create a new instance of the

proxy and setup authentication would look like:

EloquaService.EloquaServiceClient serviceProxy = new

EloquaService.EloquaServiceClient();




serviceProxy.ClientCredentials.UserName.UserName =

"Company\username";

serviceProxy.ClientCredentials.UserName.Password = "password";

STEP 5: WRITE THE CODE REQUIRED

Once you have completed the other steps, it’s time to write the code required to implement usage of the

selected Eloqua web service. You can find specific code sample to help you do this in the API Reference

beginning on page 22. The code samples are provided in both .NET and Java formats.

Eloqua Objects Overview

The diagram below shows the relationships between the data entities in Eloqua. See the Entities section of

the Object Model below for more information.

Object Model

The Eloqua API is separated into 3 main areas:

1. Entities

2. Assets

3. Data Services (DataExport and DataImport Functionality)

ENTITIES

The Eloqua marketing database is used for a variety of purposes including storing Contact data and

transactional records such as closed opportunities (ie: Data Cards) for list segmentation purposes. Some of

these entities are related to one another (ie: Companies and Contacts); others are simply transactional

storage silos (ie: Form Submissions). The Eloqua Entities are represented in the API and can be “described”

to determine their schema such as available fields, field types and required values.



There are two entities that are slightly different—Forms and Data Card Sets—for the reason that they

represent both an Entity in Eloqua and can also be described as an Asset (for example: you can pull data

from “Forms” as an Entity, but you could also configure how a Form operates or its properties because it is

also an Eloqua Asset).

The Eloqua API makes use of the following DynamicEntities to store the schema by which they store data

and the actual data itself:

Contacts

Prospects

Companies

Data Cards,

Form Submissions

Visitors

Object Relationships

ENTITY RELATIONSHIPS

The diagram below indicates the entity relationships available through the API. Note that some relationships

may not currently be visible in the API (such as a Prospect-to-Visitor relationship as the lookup tables are

not exposed via the API).

Contact

ContactID

VisitorID

C_DateCreated

C_DateModified

C_EmailAddress

ContactIDExt

ProspectID

CompanyID

C_EmailAddressDomain

C_StandardField1

C_CustomField1 ProfileFieldData

VisitorID

CustomerGUID

DateCreated

DateEdited

V_first_name

V_last_name

V_Total_Visits

V_IPAddress

LastPoll

V_Total_Pages

VisitorEntityTypeID

EntityID

CompanyID

V_StandardField1

V_CustomField1

ProspectID

DataCardID

Company

CompanyID

M_DateCreated

M_CompanyName

M_DateModified

CompanyIDExt

M_StandardField1

M_CustomField1

Prospect

ProspectID

P_DateCreated

P_EmailAddress

P_FirstName

P_LastName

CompanyID

ContactID

VisitorCompanyMap

CompanyID

VisitorID

VisitorProspectMap

ProspectID

VisitorID

DataCard

DataCardID

DataCardName

DataCardSet

DataCardStatus

UniqueCode

SalesProcessEntityType

SalesProcessEntity

DataCardIDExt

DateCreated

DateModified

DateCompleted

DataImportExecutionID

VisitorID

DataCardFieldValue

DataCardFieldValueID

DataCard

DataCardField

StringValue

IntegerValue

TextValue

DataImportSourceID

DateTimeValue

NumericValue

Form Data

FormSubmitID

DateSubmitted

VisitorID

CustomField1

StandardField1

InternalQueue

InternalQueueID

ExternalID

Date

EmailAddress

Priority

Status

Owner

Subject

Type

EntityID



ENTITY METADATA

The web service contains operations for discovering all the entities in the system as well as the metadata

information for each entity. The following operations are available:

Entity Metadata operations:

ListEntityTypes()

Retrieve all the entity types in your Eloqua database. This includes the Base type that contains the

Contact and Company entities. Only types available in the instance of Eloqua which you are logged into

are returned. Your application can parse the response and query for further information such as the

metadata for each Entity type.

DescribeEntityTypes()

Retrieve all the entities in a given Entity Type. For example: Contacts, Companies and Prospects are

entities contained in the Base Entity Type.

DescribeEntity()

Retrieve all the metadata for a specific Entity. The information returned also contains access permissions

on the entity (Readable, Createable, etc…)

Entity Metadata Diagram



ENTITY - GLOBAL TYPES

Base Objects are used to store data about marketing contacts and their related entities. These primary

(Base) objects include: Contacts, Prospects and Companies, Visitors and Processed Activity.

Eloqua Global Types (ListEntityTypes)

Base This type includes the 3 main Eloqua entities: Contact, Company and

Prospect. These entity types can be further described to identify the

metadata available (such as Field Names) and actions available.

DataCardSet DataCardSets is an entity that may have its own data model customization

(customized fields per set) and store many records that are related to a single

Contact record. This entity type will return a list of all the Data Card sets in

the current instance.

Forms Forms is a repository of all the Form submission data that is captured by the

Eloqua Form Processing engine before it is recorded into a Contact record

and processed. In the Eloqua interface, this data is equivalent to opening the

Form’s “Form Data Submission Report.”

BASE ENTITY TYPES

With Eloqua, built around a marketing-oriented database, there are primary or “Base” Data Objects

(including Contacts, Prospects, and Companies) that are used within the system to store data about

marketing contacts and their related entities.

Eloqua Base Entity Types (DescribeEntityTypes:Base)

Contacts Contacts are the most frequently used entity in the Eloqua system. A Contact

record typically represents a person that is either a customer or prospect who

has an email address. In Eloqua, the Contact table uses email as a unique

identifier to prevent duplicate Contacts from having the same email address.

Prospects Prospect records are similar to Contacts, but do not have the need to have

an email address. Prospect records typically contain records of Contacts or

Leads who do not have an email address. They can be converted into a

Contact record through Program Builder when they acquire an email address.

Companies Company records in Eloqua (sometimes referred to as Accounts in CRM

systems) represent an organization and act as a parent record to Contacts

and Prospects who can be linked to a Company record. A typical Company

record would contain information about the Company name, annual revenue,

trading symbol, etc.



Eloqua Base Entity Types (DescribeEntityTypes:Base)

Visitors Visitor records (sometimes referred to as ‘Visitor Profiles’) are the container

for each recorded visitor to your tracked website pages. Each record contains

information such as browser, IP address, Geo-IP information, Linked Contact

fields, Lat/Long, DNS Names, aggregated statistics about the visitor such as

total pages viewed, length of last visit, last search engine keyword, and many

other customizable fields.

Processed Activity

Queue

This object represents a queuing table that can hold marketing activities that

are trigged by custom events in Program Builder or via Integration Rules. Use

this mechanism to write marketing activities into your CRM system. Your

system will poll the marketing activities table for any new records since the

last check—the values returned will include the type of activity, date/time,

Related Contact/Lead ID, and a description field. Your connector program

can then write these activities as tasks into your CRM system that are related

to the Contact/Lead record. You need to request Processed Activity to be

turned on for a particular Eloqua instance. Speak to your CSM.

ASSETS

Assets are abstract representations of structured data in Eloqua, such as an Email Brochure or Data Import

settings (AutoSynch). Eventually, the API will begin to include other Assets that are currently only accessible

within the UI of the Eloqua platform. Assets are the tools that are used to make your marketing application

do soemthing: Send Emails, edit Email content, create Hypersites™, add to Programs, Data Import

mappings, Data Export settings and many others. In this current version of the API, only DataImport and

DataExport Settings are available as Assets.

ASSET METADATA

The web service contains operations for discovering all the assets in the system as well as the metadata

information for each asset. The following operations are available:

Asset Metadata operations:

ListAssetTypes()

Retrieve all the Asset Types in your Eloqua database. Only Types available in the instance of Eloqua

which you are logged into are returned.

DescribeAssetType()

Retrieve all the Assets in a given Asset Type.



Asset Metadata Diagram

CRM INTEGRATION CONSIDERATIONS

Eloqua has been integrated with a variety of different CRM systems with different data models and methods

of storing data and related records. Our Professional services team can help with guidance or direction with

integrating with your own particular data needs. Speak to your Account Manager for more details. Eloqua

supports many different methods of connecting to external systems such as batch file transfers over FTP,

HTTP, HTTPS using cookie or form based logins, the Eloqua DirectConnect integration engine, and our new

API.

For hosted CRM systems such as Salesforce.com®, Oracle® CRM OnDemand, Microsoft ® Dynamics

CRM 4.0, and NetSuite®, Eloqua’s DirectConnect has a suite of native adapters that are used for many of

our integrations. Creating your own connector using the Eloqua API for these systems is generally

unnecessary.

If you have a unique or non-native CRM system that you wish to connect with Eloqua, you will likely need to

build a connector that acts as the bridge between your CRM system and Eloqua using the API. The Eloqua

API has been designed to allow for regular polling by your CRM connector system to find newly updated

records or recently executed marketing activities.

There are three main components of data that are typically synchronized or exchanged between Eloqua and

a CRM or ERP program. Not all components are required as part of an integration:

1. Marketing Activity Data

Regular marketing activities such as Email Opens, click-throughs, unsubscribes, bouncebacks, website

visits, and Form submissions are typically made available to the CRM system and are sent with the



related Lead/Contact record ID so that a record can be created in the CRM that records the relationship.

These activities can be used for reporting (for example, to relate activities and closed opportunities).

2. New or Updated Lead/Contact Data

a. Outbound Data from Eloqua - As website visitors submit Forms, these will update/create the

Contact records in Eloqua based on the email address that is supplied with the Form submission. These

records should also be pushed into a “Program” within Eloqua that may score or dictate how a record is

handled after submission into the system (for example, should a record be passed to CRM only after it

is scored higher than 65).

b. Inbound Data to Eloqua - New Contact records created by your sales team in the CRM also should

flow into Eloqua on a regular basis so that they can be included as part of formal marketing efforts. This

is often achieved by either supplying Eloqua with a a CSV file, or using Eloqua web services to create a

new Contact record and passing the information from the CRM system into the new record.

3. Campaign Associations

a. Based on marketing activities, marketing teams may wish to associate a Contact or Lead record in

your CRM to a Campaign object within your CRM system for basic reporting purposes. This can include

creating basic ROI or influenced revenue reports within your CRM system, depending on your data

requirements.

b. Typically a Contact or Lead ID and a Campign Object ID from your CRM system are needed to

perform an association. This is mostly dependent on your CRM’s architecture and capabilities.

When developing an integration with Eloqua, you may choose to perform operations in Batch- or Event-

driven manner from your side. Eloqua does not currently support Event-driven integrations that push data

directly to an endpoint on your side, so you must poll Eloqua actively to pull down Events from the queue.

It is important that the Eloqua Entity ID is stored within your CRM system as part of the Contact or Lead

record as it is needed to perform API calls efficiently back to Eloqua. While Eloqua matches records in the

Contact table based on email address, the API requires the Entity ID to be used in API calls such as

updating a Contact record in Eloqua when a record change occurs within your CRM system.

SCENARIO 1: MARKETING ACTIVITY INTEGRATION

In a scenario where Marketing activities must be passed over to your CRM system, there is a facility called

the “Processed Activity Queue” that collects recently-triggered Eloqua marketing activities (such as Email

opens, website visits, form submissions,etc.) by Contacts within the Eloqua database. These activities are

polled by your code on a reguar basis and created as a records related to the Contact or Lead in your CRM

system or database. Your web service will need to match a record in your CRM to update using the related

records. It is possible to map your system’s Foreign Contact/Lead ID to each activity that is placed in the

Processed Activity Queue for easy mapping to the record in your CRM.



PROCESSED ACTIVITY QUEUE

The Processed Activity Queue is enabled by request by your Customer Success Manager for your Eloqua

instance. Processed Activity is not available if you have Instead of writing them to an external CRM system

as usual, you can direct these activities to be written to the Processed Activity Table (Part of the BASE

entity), which is accessible via the API and will store these records for a period of two weeks.

Before using this function, you must create an External API call that is mapped to the appropriate fields in

the Processed Activity Queue by creating a new External Call in the Outbound tab in the Integration area.



Note: Eloqua Internal will only be visible if it has been enabled for your instance of Eloqua and you have

Customer Administrator security rights. It is not available if you already have an integration using

DirectConnect to Salesforce.com®, Oracle® CRM OnDemand, Microsoft ® Dynamics CRM 4.0, and

NetSuite®.

When creating an external API call that will write to the table, you must map the fields that will be stored in

the queue. You can map fields by dragging fields from the right into the columns of the Processed Activity

Queue on the left:

You can run a test call that will write data to the Processed Activity Queue for testing purposes. You can

view the current Mapped External Calls for an Internal Event using the View Mapped External Calls option.

Once an External Call is mapped to an Internal Event, you can run the test.



For performing the test, you will be asked to choose a Contact record in Eloqua which will fire the External

Call you have specified.

SCENARIO 2: SYNCHRONIZE LEAD/CONTACT DATA

In a typical marketing database scenario, Eloqua is used as a centralized place to store and match incoming

requests, Form submissions, and list uploads from marketing events. This can help avoid entries in the CRM

system that may be considered to be “dirty” or duplicated. In most scenarios the CRM database is seen as

the “master” database with the most up to date information.

In any case, it is critical that you sit down and evaluate the needs of the sales and marketing teams

regarding what information must be exchanged between the two systems. Sales teams are generally

interested in receiving information about marketing activities and lead scores, while the marketing team will



generally have an interest in leveraging segmentation data contained within the CRM to create targeted

marketing campaigns.

In the diagram above, note that new Form submissions create Lead records that are pushed into the CRM

system. Updates and new records in the CRM system must be pushed into Eloqua to keep the databases

synchronized.

CRM/ELOQUA DATA MODEL

Each of the following Entities have their own set of fields that can be customized by the Administrator.

Contacts—The primary entity within Eloqua—Contact records—are deduplicated by their email address.

You cannot create multiple Contact records with the same email address. Contact records are typically used

to represent Leads and Contacts from a CRM system. You should be storing the unique identifying record ID

that your CRM system uses for Leads/Contacts in an Eloqua Contact field that has been created expressly

for this purpose. This can be used for rmatching purposes when exporting marketing activities.

Companies—Contacts can be linked to a Company record in Eloqua, and are typically equivalent to an

“account” or “company” record in a CRM system. It is recommended that you create a field to store the ID

that is used within your CRM system to identify Accounts/Company records.

Prospects—Similar to Contacts, but has no unique key requirements such as an email address. Prospects

are not deduplicated and generally represent Leads or Contacts with no email address associated to them.

Prospects can be linked to Companies in Eloqua. Prospect records can be converted to Contact records by

using a Program Builder step to map the fields between the two entities (Prospects and Contacts) and

performing the conversion.

Data Card Sets—A Data Card set typically represents an Event or series of records. Each Data Card set

has it’s own fields and settings. For example, Data Card Set A may have only three fields, but Data Card set

B has 20 fields. A Data Card set contains many Data Cards that may be linked to a Contact record.



Data Cards—A Data Card is the record that stores a transaction such such as an Event registration by a

Contact, or a purchase history record (opportunities). Each Data Card may or may not be linked to a Contact

record.

DATA WAREHOUSE INTEGRATION

Eloqua’s marketing activity data may be used to build or support a data warehouse by supplying insight into

prospect activities. In a data warehouse, relationships between prospect activities, purchase history and

other business variables can be measured and used in company level metrics. The Eloqua API supports the

model of supplying a data warehouse with information on a regular basis in bulk file downloads.

To define and configure a data export configuration that specifies what delimiters will be used in the file,

which type of information from Eloqua should be exported, and other settings, go to the Reporting Area in

Eloqua and create a new Data Export. This list of automated exports are visible via the API through a

describe call of the DataExportAsset.

When creating a connector for a data warehouse, the service will need to accept CSV files through a binary

SOAP call and be able to manipulate the file into a format that is importable to your data warehouse. The

field values that are passed over are configurable from within the Eloqua UI. Certain Reports are not

configurable and come with a set series of fields/columns. See the Scheduled Report Exports

documentation for more information.

Eloqua can export the following items from its historical tracking database into delimited files:

Call On Demand, Fax, Printmail, RSS, Data Card Activity

All Email Activity

All Form Submissions

Full Company/Contact/Prospect list

Marketing Campaign Activity

These exports can be done on a regular basis by the system and can be picked up remotely without using

the API. Using the API to trigger Data Exports from Eloqua allows for on-demand generation of these

Reports. Generally, Data Warehouses do not require up-to-the-minute updates of information. Using the

Data Export to URL functionality allows for this on a once daily basis. This would not require the use of the

API to get information from Eloqua. For more information, see Eloqua Scheduled Report Exports

documentation.

FIELD TYPES

The Field Types in Eloqua are configurable by the Customer Administrator and have certain attributes set for

each. The field types such as Picklist, Multi-select, and Text, are generally used to represent data within the

Eloqua UI. However, at the data layer in the Eloqua database, only the actual value is required and stored.

Picklist fields are represented as a standard text field via the API and allows up to 100 characters to be

stored. When communicating via the API, values will not be checked against the picklist values that have

been configured in the User Interface.



Multiselect fields allow up to 1000 characters to be stored and use double full colons (::) as a delimiter

when parsing values to be displayed in the Eloqua UI. These delimiters are converted on external API calls

according to the target system.

Large Text Fields are specially designated fields that can contain up to 32K of text. However, in this version

of the API, Large Text Fields are not accessible through the API and are not shown in the the description of

any objects. This is a planned addition to future versions of the API.

Date Fields store date and time values that can be evaluated against as “before or after” criteria.

Numeric Fields store integer values and allows for the avaluation of criteria such as “greater than” or “less

than” and other numeric operators that can be used in filtering.

Number fields are reference numbers to other records in Eloqua. For example a contact has a field called

“CompanyID” – this field represents the link to a company in Eloqua.

FIELD META DATA

Field Name is the backend name of the field in Eloqua’s database and is used in all API calls

Display name is the text label shown when this field is displayed within the Eloqua Application UI.

Field Type indicates the type of data that is stored in a field it is returned as a string

Default Value is a string that indicates the value that will automatically populate a record upon creation in

Eloqua

Length returns an integer that represents the maximum length of a stored string in a field.

Required is a Boolean value of TRUE/FALSE that determines if a field can remain blank when a record is

create dor updated.

Custom is a Boolean value indicated as part of the describe call and shows that a field was created by the

user and is not a system generated field.

Writeable is a Boolean value which indicates whether a field can be written or updated via the API.

SECURITY

When logging in, all security aspects are controlled by the UserID that was used to setup the session. Any

activity that the user is prohibited from doing through the regular interface will also be prohibited through the

API. In this manner the Eloqua Security model remains the same and security groups can effectively bar an

API user from logging in via the User Interface if desired.

Eloqua’s API security framework includes the following:

API calls will only be accepted through a secure HTTPS channel on port 443. These communications are

encrypted with Secure Sockets Layer (SSL) for security (minimum 128-bit).

Access is stateless, and requires authentication for each API call that is sent using a valid username and

password that has been placed into a security group that grants access to the API (WS-Security 1.0).

The same data visibility and access capabilities that apply to users in Eloqua are applied to users

connected through the Web services interface. Data visibility and access are restricted by the security

groups and asset based security. Permissions are checked for every data access.



Eloqua employs a variety of security measures and techniques to secure our production network and

infrastructure. These same precautions are used for our API infrastructure. These solutions are regularly

reviewed and improved as new technologies and techniques become available.

SYSTEM FIELDS

Several fields are included in each entity that are system fields and cannot be written to or updated with a

record. These system fields may act as reference fields between objects, or are the EntityID used to identify

objects in Eloqua when using the API. These fields are identified as ‘Writable = False’ when using the

describeEntity call.

API Call Basics

API calls represent specific operations that your client applications can invoke at runtime to perform tasks.

For example:

Add, update, and delete records in Eloqua

Query your organization’s information (retrieve calls) (query limit up to 2000 records)

Bulk retrieve records via API’s bulk data transfer service (no set record limit)

Using your development environment, you can construct web service client applications that use standard

web service protocols to run programmatically

Create, update, and delete data (using create, update, and delete calls)

Obtain and navigate metadata about your organization’s data (describeEntity,

describeEntityType, describeAsset, describeAssetType, List EntityTypes calls)

Import and export large datasets using the DataImport and DataExport services

API CALL CHARACTERISTICS

All API calls are:

Service Requests and Responses—Your application prepares and submits a service request to the

Eloqua Web Service via the API, the Web Service processes the request and returns a response, and the

client application handles the response.

Synchronous—When an Eloqua API call is invoked, your client application should wait for a response

from the service. The web service does not support asynchronous calls.

Limited in Length for the results—The return results from queries/retrieve are limited to 2000 records in

pages of 20 items. The Bulk Data Transfer service can be used for larger record sets.

Committed Automatically—Every operation that writes to an Eloqua object is committed automatically. For

example, if a client application attempts to create two new Contacts, they are created using mutually-

exclusive insert operations that succeed or fail individually, not as a group.

Note: This means that client applications may need to handle some failures.

ERROR HANDLING

When a call is invoked, a failure or success response is always provided. It is imperative that your

application be able to handle errors properly, whether returned by the Eloqua API or if because of a



malformed message. Service interruptions and regular maintenance times will return a message indicating

that status. Your application should be able to use the return message to handle the error and either re-try or

log the situation for manual intervention or troubleshooting:

For most calls, if the error occurs because of a problem specific to the query, the API returns an Error.

If an incorrectly-formatted SOAP message is causing the error, an exception is returned by the web

service.

See the API Reference area starting on page 22 for more details on Error Messages and how they are

returned via the API interface.

Additional Considerations

USAGE METERING

Eloqua provides a limiting infrastructure to make sure that some users do not consume a disproportionate

share of the web service infrastructure resources. These limiters constrain customer organizations’ use of

server-side resources to equitably share available resources among users and to minimize the possibility of

denial-of-service incidents. Eloqua reserves the right to throttle the use of the API at any time to preserve

the reliability and operation of the main Eloqua service. The following limitations apply:

24 hour limit on API calls—As follows:

Express and Team—Limited to performing X API calls per 24 hour period.

Enterprise—Limited to performing X API calls per 24 hour period.

If you require more than these limits on a regular basis please speak with your Account Manager

Export of Bulk data can be performed on a regular basis but may be throttled or queued depending on

load conditions.

Number of Sessions Limit—Under some circumstances, a server can be flooded with concurrent logins.

Eloqua provides session limiters that constrain the number of sessions an organization can have open at

any given time. This upper limit on the number of sessions applies to all open Web services sessions.

Request Rate—All integration requests (data exchange requests) in a session are subject to rate limiting.

Rate limiting is implemented for the following reasons:

A user can perform long-running operations on the server that result in complex and long running

queries on the database.

A user can perform constant operations on the server that constantly use resources.

Rate limiting can alleviate the previous problems to some extent. Eloqua applies a restriction to each

session to limit the number of requests per second that clients can make. The rate limit is set to 1

request every 1 seconds for QUERY calls. Other calls are allowed more often than once per second to

a reasonable level.

InitializeDataExport for data export functions are limited to run every 5 seconds – but generally should

not be run on a rapid interval.

Request Size Limit—The upper limit on the size of any incoming HTTP request is 1MB.

Maximum Records Returned—For return messages, the maximum number of records returned for each

query is limited to 2000. If you exceed the threshold of 2000 records as a result of your query, you will

receive an error (with no records returned) and will need to restrict it further so that it returns fewer than

2000 results(ie: add a condition to limit the set). If you need a larger record set than 2000 records, you



will need to perform a bulk data export function which will require you to parse an exported binary file

through the SOAP API.

COMPRESSION

HTTP Header compression is used for all outgoing traffic and should be supported by your development

environment as this can substantially improve performance versus using an uncompressed HTTP stream.

INTERNATIONAL CHARACTERS

Eloqua’s SOAP encoding allows for UTF-8 character encoding to be passed into the Eloqua system. Eloqua

fully supports UTF-8 character encoding in most fields natively. You need to ensure that you are passing the

values in their original encoding.

ELOQUA IDENTIFICATION CODES

Eloqua uses a series of unique IDs for each record in the system that is generated server-side for each

unique record. The API calls use these ID’s exclusively for executing their functionality. If there is a situation

where you require the ID of another entity, there are a variety of different ways of getting that information.

For example if you are given an email address to update a record, a query looking for a record with the

matching email address will return a Contact ID. This ID can then be used to update the record.

It is recommended that you create a Foreign ID field in your CRM to store the Eloqua Contact ID as it will be

used for all update sto the Eloqua database.

API Reference

METADATA

The metadata that describes the attributes and properties of objects in your Eloqua database is accessible

through describe calls. These methods allow you to discover information about Entities and Assets in your

system. Note that this information is read-only.

ENTITY METADATA

An Entity is an abstract representation of an object in Eloqua, such as a Contact, Company or Data Card

Set. Entity objects can have attributes. For example: A Contact entity has an Email Address and a First

Name.

The web service contains operations for discovering all the entities and entity types in the system as well as

the metadata information for each entity. The following operations are available:



ENTITY METADATA OPERATIONS

ListEntityTypes

Usage

Retrieve all the entity types in your Eloqua database. This includes the Base type that contains the Contact

and Company entities. Only types available in the instance of Eloqua which you are logged into are

returned. Your application can parse the response and query for further information such as the metadata

for each Entity type.

Arguments

None

Response

ListEntityTypesResult

Faults

UnexpectedErrorFault

Syntax

Service instance;

ListEntityTypesResult returnValue;

returnValue = instance.ListEntityTypes();



Sample Code - .NET

Sample Code – Java

try { // Set up the Eloqua API Service EloquaService.EloquaServiceClient service = new EloquaService.EloquaServiceClient(); service.ClientCredentials.UserName.UserName = "Company\\default.user"; service.ClientCredentials.UserName.Password = "test123"; // Execute the request EloquaService.ListEntityTypesResult result = service.ListEntityTypes(); // Extract the name of each Entity Type foreach (String entityType in result.EntityTypes) { Console.WriteLine(entityType); } } catch (System.ServiceModel.FaultException ex) { // Customize your own Error handling code. Console.WriteLine(String.Format("Reson: {0}", ex.Reason.ToString())); Console.WriteLine(String.Format("Fault Type: {0}", ex.GetType().ToString())); Console.WriteLine(String.Format("Fault Code: {0}", ex.Code.Name.ToString())); } catch (Exception ex) { // Customize your own Error handling code. Console.WriteLine(String.Format("Exception Message: {0}", ex.Message.ToString())); }

try { // Set up the Eloqua API Service EloquaService.Eloqua eloquaService = new EloquaService.Eloqua(); EloquaService.EloquaService service = eloquaService.getEloquaService(); // Execute the request EloquaService.ListEntityTypesResult result = service.listEntityTypes(); // Extract the name of each Entity Type for (String entityType : result.getEntityTypes().getValue().getString()) { System.out.println(entityType); } } catch (Javax.xml.ws.soap.SOAPFaultException ex) { // Customize your own Error handling code. System.out.println(String.format("Message: %s", ex.getMessage())); System.out.println(String.format("Fault Code: %s", ex.getFault().getFaultCode())); } catch (Exception ex) { // Customize your own Error handling code. System.out.println(ex.getMessage()); }



See Also

DescribeEntityType

DescribeEntity

WSDL Information

DescribeEntityType

Usage

Retrieve a list of all the entities in a given Entity Type. For example: Contacts, Companies and Prospects

are entities contained in the Base Entity Type.

Arguments

entityType (String)

Response

DescribeEntityTypeResult

Faults


ValidationFault

InvalidTypeFault

Syntax

Service instance;

String entityName;

DescribeEntityTypeResult returnValue;

returnValue = instance.DescribeEntityType(entityType);



Sample Code - .NET


try { // Set up the Eloqua API Service EloquaService.EloquaServiceClient service = new EloquaService.EloquaServiceClient(); service.ClientCredentials.UserName.UserName = "Company\\default.user"; service.ClientCredentials.UserName.Password = "test123"; // Execute the request EloquaService.DescribeEntityTypeResult result = service.DescribeEntityType("Base"); // Extract the ID, Name and Type of each Entity in the Base Type foreach (EloquaService.EntityType entityType in result.EntityTypes) { Console.WriteLine(String.Format("ID: {0}", entityType.ID)); Console.WriteLine(String.Format("Type: {0}", entityType.Type)); Console.WriteLine(String.Format("Name: {0}", entityType.Name)); } } catch (System.ServiceModel.FaultException ex) { // Customize your own Error handling code. Console.WriteLine(String.Format("Reson: {0}", ex.Reason.ToString())); Console.WriteLine(String.Format("Fault Type: {0}", ex.GetType().ToString())); Console.WriteLine(String.Format("Fault Code: {0}", ex.Code.Name.ToString())); } catch (Exception ex) { // Customize your own Error handling code. Console.WriteLine(String.Format("Exception Message: {0}", ex.Message.ToString())); }

try { // Set up the Eloqua API Service EloquaService.Eloqua eloquaService = new EloquaService.Eloqua(); EloquaService.EloquaService service = eloquaService.getEloquaService(); // Execute the request EloquaService.DescribeEntityTypeResult result = service.describeEntityType("Base"); // Extract the ID, Name and Type of each Entity Type for (EloquaService.EntityType entityType : result.getEntityTypes().getValue().getEntityType()) { System.out.println(String.format("ID: %s", String.valueOf(entityType.getID()))); System.out.println(String.format("Name %s", entityType.getName().getValue())); System.out.println(String.format("Type: %s", entityType.getType().getValue())); } } catch (Javax.xml.ws.soap.SOAPFaultException ex) { // Customize your own Error handling code. System.out.println(String.format("Message: %s", ex.getMessage())); System.out.println(String.format("Fault Code: %s", ex.getFault().getFaultCode())); } catch (Exception ex) { // Customize your own Error handling code. System.out.println(ex.getMessage()); }



See Also

DescribeEntity

ListEntityTypes

WSDL Information

DescribeEntity

Usage

Retrieve all the metadata for a specific Entity. The information returned also contains access permissions on

the entity (Readable, Createable, etc…)

Arguments

entityType (EntityType)

Response

DescribeEntityResult

Faults


ValidationFault

InvalidTypeFault

Syntax

Service instance;

EntityType entityType;

DescribeEntityResult returnValue;

returnValue = instance.DescribeEntity (entityType);



Sample Code - .NET

try { // Set up the Eloqua API Service EloquaService.EloquaServiceClient service = new EloquaService.EloquaServiceClient(); service.ClientCredentials.UserName.UserName = "Company\\default.user"; service.ClientCredentials.UserName.Password = "test123"; // Define a Contact Entity Type object EloquaService.EntityType entityType = new EloquaService.EntityType(); entityType.ID = 0; entityType.Name = "Contact"; entityType.Type = "Base"; // Execute the request EloquaService.DescribeEntityResult result = service.DescribeEntity(entityType); // Extract the Entity's Name Console.WriteLine(String.Format("Entity Name: {0}", result.Name)); // Extract the Entity's Properties Console.WriteLine(String.Format("Is Createable: {0}", result.IsCreateable)); Console.WriteLine(String.Format("Is Deletable: {0}", result.IsDeletable)); Console.WriteLine(String.Format("Is Queryable: {0}", result.IsQueryable)); Console.WriteLine(String.Format("Is Retrievable: {0}", result.IsRetrievable)); Console.WriteLine(String.Format("Is Updateable: {0}", result.IsUpdateable)); // Extract the Entity's Field Metadata foreach (EloquaService.DynamicEntityFieldDefinition fieldDef in result.Fields) { Console.WriteLine(String.Format("Data Type: {0}", fieldDef.DataType)); Console.WriteLine(String.Format("Default Value: {0}", fieldDef.DefaultValue)); Console.WriteLine(String.Format("Display Name: {0}", fieldDef.DisplayName)); Console.WriteLine(String.Format("Internal Name: {0}", fieldDef.InternalName)); Console.WriteLine(String.Format("Is Custom: {0}", fieldDef.IsCustom)); Console.WriteLine(String.Format("Is Required: {0}", fieldDef.IsRequired)); Console.WriteLine(String.Format("Is Writeable: {0}", fieldDef.IsWriteable)); Console.WriteLine(String.Format("Length: {0}", fieldDef.Length)); } } catch (System.ServiceModel.FaultException ex) { // Customize your own Error handling code. Console.WriteLine(String.Format("Reson: {0}", ex.Reason.ToString())); Console.WriteLine(String.Format("Fault Type: {0}", ex.GetType().ToString())); Console.WriteLine(String.Format("Fault Code: {0}", ex.Code.Name.ToString())); } catch (Exception ex) { // Customize your own Error handling code. Console.WriteLine(String.Format("Exception Message: {0}", ex.Message.ToString())); }




See Also

DescribeEntityType

ListEntityTypes

WSDL Information

try { // Set up the Eloqua API Service EloquaService.Eloqua eloquaService = new EloquaService.Eloqua(); EloquaService.EloquaService service = eloquaService.getEloquaService(); // Instantiate a new Eloqua Service object factory EloquaService.ObjectFactory serviceFactory = new EloquaService.ObjectFactory(); // Define a Contact Entity Type object EloquaService.EntityType entityType = new EloquaService.EntityType(); entityType.setID(0); entityType.setName(serviceFactory.createEntityTypeName("Contact")); entityType.setType(serviceFactory.createEntityTypeType("Base")); // Execute the request EloquaService.DescribeEntityResult result = service.describeEntity(entityType); // Extract the Entity's Properties System.out.println(String.format("Is Createable: %s", result.isIsCreateable())); System.out.println(String.format("Is Deleteable: %s", result.isIsDeletable())); System.out.println(String.format("Is Queryable: %s", result.isIsQueryable())); System.out.println(String.format("Is Retrievable: %s", result.isIsRetrievable())); System.out.println(String.format("Is Updateable: %s", result.isIsUpdateable())); // Extract the Entity's Field Metadata for (EloquaService.DynamicEntityFieldDefinition fieldDef : result.getFields().getValue().getDynamicEntityFieldDefinition()) { System.out.println(String.format("Data Type: %s", fieldDef.getDataType().value())); System.out.println(String.format("Default Value: %s", fieldDef.getDefaultValue().getValue())); System.out.println(String.format("Display Name: %s", fieldDef.getDisplayName().getValue())); System.out.println(String.format("Internal Name: %s", fieldDef.getInternalName().getValue())); System.out.println(String.format("Is Custom: %s", fieldDef.isIsCustom())); System.out.println(String.format("Is Required: %s", fieldDef.isIsRequired())); System.out.println(String.format("Is Writeable: %s", fieldDef.isIsWriteable())); System.out.println(String.format("Length: %s", String.valueOf(fieldDef.getLength()))); } } catch (Javax.xml.ws.soap.SOAPFaultException ex) { // Customize your own Error handling code. System.out.println(String.format("Message: %s", ex.getMessage())); System.out.println(String.format("Fault Code: %s", ex.getFault().getFaultCode())); } catch (Exception ex) { // Customize your own Error handling code. System.out.println(ex.getMessage()); }



ENTITY OPERATIONS

This section describes the operations that can be performed to retrieve and change an Entity’s data using

the API. When performing an operation it is important to use the Eloqua ID of the object you are attempting

to modify or delete. The following operations are available for most Entities (Visitor Profiles and Forms are

read-only):

Create

Usage

Create one or more new Entities in the Eloqua database.

Arguments

dynamicEntity[]

Response

CreateResult[]

Faults


ValidationFault

InvalidTypeFault

BatchSizeExceededFault

Syntax

Service instance;

DynamicEntity[] dynamicEntities;

CreateResult[] returnValue;

returnValue = instance.Create(dynamicEntities);



Sample Code - .NET

Note: .NET code sample concluded on next page.

try { // Set up the Eloqua API Service EloquaService.EloquaServiceClient service = new EloquaService.EloquaServiceClient(); service.ClientCredentials.UserName.UserName = "Company\\default.user"; service.ClientCredentials.UserName.Password = "test123"; // Build a Contact Entity Type object EloquaService.EntityType entityType = new EloquaService.EntityType(); entityType.ID = 0; entityType.Name = "Contact"; entityType.Type = "Base"; // Create a new Array of Dynamic Entities EloquaService.DynamicEntity[] dynamicEntities = new EloquaService.DynamicEntity[1]; // Create a new Dynamic Entity and add it to the Array of Entities dynamicEntities[0] = new EloquaService.DynamicEntity(); dynamicEntities[0].EntityType = entityType; // Create a Dynamic Entity's Field Value Collection dynamicEntities[0].FieldValueCollection = new EloquaService.DynamicEntityFields(); // Add the Contact's Email Address field to the Dynamic Entity’s field collection dynamicEntities[0].FieldValueCollection.Add("C_EmailAddress", "[email protected]"); // Add the Contact's First Name field to the Dynamic Entity’s field collection dynamicEntities[0].FieldValueCollection.Add("C_FirstName", "Support"); // Execute the request EloquaService.CreateResult[] result = service.Create(dynamicEntities); // Verify the status of each Contact Create request in the results for (int i = 0; i < result.Length; i++) { // Successfull requests return a positive integer value for ID if (result[i].ID != -1) { Console.WriteLine("Success"); } // Failed requests return a -1 integer value for ID else { Console.WriteLine("Failure"); // Extract the Error Message and Error Code for each failed Create request foreach (EloquaService.Error createError in result[i].Errors) { Console.WriteLine(String.Format("Code: {0}", createError.ErrorCode)); Console.WriteLine(String.Format("Message: {0}", createError.Message)); } } } } catch (System.ServiceModel.FaultException ex)



Sample Code - .NET (continued)


Note: Java code sample concluded on next page.

{ // Customize your own Error handling code. Console.WriteLine(String.Format("Reson: {0}", ex.Reason.ToString())); Console.WriteLine(String.Format("Fault Type: {0}", ex.GetType().ToString())); Console.WriteLine(String.Format("Fault Code: {0}", ex.Code.Name.ToString())); } catch (Exception ex) { // Customize your own Error handling code. Console.WriteLine(String.Format("Exception Message: {0}", ex.Message.ToString())); }

try { // Set up the Eloqua API Service EloquaService.Eloqua eloquaService = new EloquaService.Eloqua(); EloquaService.EloquaService service = eloquaService.getEloquaService(); // Instantiate a new Eloqua Service object factory EloquaService.ObjectFactory serviceFactory = new EloquaService.ObjectFactory(); // Define a Contact Entity Type object EloquaService.EntityType entityType = new EloquaService.EntityType(); entityType.setID(0); entityType.setName(serviceFactory.createEntityTypeName("Contact")); entityType.setType(serviceFactory.createEntityTypeType("Base")); // Create a new Array of Dynamic Entities EloquaService.ArrayOfDynamicEntity dynamicEntities = new EloquaService.ArrayOfDynamicEntity(); // Create a new Dynamic Entity and add it to the Array of Entities EloquaService.DynamicEntity dynamicEntity = new EloquaService.DynamicEntity(); dynamicEntity.setEntityType(serviceFactory.createEntityType(entityType)); // Create a Dynamic Entity's Field Value Collection EloquaService.DynamicEntityFields fieldValueCollection = new EloquaService.DynamicEntityFields(); fieldValueCollection = serviceFactory.createDynamicEntityFields(); // Add the Contact's Email Address field to the Dynamic Entity’s field collection EloquaService.DynamicEntityFields.EntityFields emailField = serviceFactory.createDynamicEntityFieldsEntityFields(); emailField.setInternalName("C_EmailAddress"); emailField.setValue("[email protected]"); fieldValueCollection.getEntityFields().add(emailField); // Add the Contact's First Name field to the Dynamic Entity’s field collection EloquaService.DynamicEntityFields.EntityFields firstNameField = serviceFactory.createDynamicEntityFieldsEntityFields(); firstNameField.setInternalName("C_FirstName"); firstNameField.setValue("Support"); fieldValueCollection.getEntityFields().add(firstNameField);



Sample Code – Java (continued)

See Also

Retrieve

Update

Delete

Query

WSDL Information

// Add the Dynamic Fields to the Dynamic Entitiy JAXBElement<EloquaService.DynamicEntityFields> fc; fc = serviceFactory.createDynamicEntityFieldValueCollection(fieldValueCollection); dynamicEntity.setFieldValueCollection(fc); // Add the Dynamic Entity (Contact) to the Array of Dynamic Entities dynamicEntities.getDynamicEntity().add(dynamicEntity); // Execute the request EloquaService.ArrayOfCreateResult result = service.create(dynamicEntities); // Verify the status of each Contact Create request in the results for (int i = 0; i < result.getCreateResult().size(); i++) { // Successfull requests return a positive integer value for ID if (result.getCreateResult().get(i).getID() != -1) { System.out.println("Success"); } // Failed requests return a -1 integer value for ID else { System.out.println("Failure"); // Extract the Error Message and Error Code for each failed Create request for (EloquaService.Error createError : result.getCreateResult().get(i).getErrors().getValue().getError()) { System.out.println(createError.getErrorCode().value()); System.out.println(createError.getMessage().getValue()); } } } } catch (Javax.xml.ws.soap.SOAPFaultException ex) { // Customize your own Error handling code. System.out.println(String.format("Message: %s", ex.getMessage())); System.out.println(String.format("Fault Code: %s", ex.getFault().getFaultCode())); } catch (Exception ex) { // Customize your own Error handling code. System.out.println(ex.getMessage()); }



Retrieve

Usage

Retrieve one or more Entities from the Eloqua database.

Arguments

EntityType

id[] (Integer)

String[] fieldList

Response

RetrieveResult[]

Faults


ValidationFault

InvalidTypeFault


Syntax

Service instance;

EntityType entityType;

int[] ids;

String[] fieldList;

DynamicEntity[] returnValue;

returnValue = instance.Retrieve(entityType, ids, fieldList);



Sample Code - .NET


try { // Set up the Eloqua API Service EloquaService.EloquaServiceClient service = new EloquaService.EloquaServiceClient(); service.ClientCredentials.UserName.UserName = "Company\\default.user"; service.ClientCredentials.UserName.Password = "test123"; // Build a Contact Entity Type object EloquaService.EntityType entityType = new EloquaService.EntityType(); entityType.ID = 0; entityType.Name = "Contact"; entityType.Type = "Base"; // Set the ID of the Contact Entity int[] ids = new int[1]; ids[0] = 1200846; // Create a new list containing the fields you want populated List<string> fieldList = new List<string>(); // Add the Contact’s Email Address to the field list fieldList.Add("C_EmailAddress"); // Add the Contact’s First Name to the field list fieldList.Add("C_FirstName"); // Build a Dynamic Entity array to store the results EloquaService.DynamicEntity[] retrievedEntities; // If the field list is empty - the request will return all Entity Fields // Otherwise, only fields defined in the field list are returned if (fieldList.Count == 0) { // Execute the request and return all of the Entity's fields retrievedEntities = service.Retrieve(entityType, ids, null); } else { // Execute the request and return only the selected Entity fields retrievedEntities = service.Retrieve(entityType, ids, fieldList.ToArray()); } // If a result was found, extract the field values for each Dynamic Entity if (retrievedEntities.Length > 0) { foreach (EloquaService.DynamicEntity dynamicEntity in retrievedEntities) { // Extract the Field Name and Value for each element in the collection foreach (KeyValuePair<string, string> keyValPair in dynamicEntity.FieldValueCollection) { Console.WriteLine(String.Format("Field Name: {0}", keyValPair.Key)); Console.WriteLine(String.Format("Field Value: {0}", keyValPair.Value)); } } } } catch (System.ServiceModel.FaultException ex)





Note: Java code sample concluded on next page.

{ // Customize your own Error handling code. Console.WriteLine(String.Format("Reson: {0}", ex.Reason.ToString())); Console.WriteLine(String.Format("Fault Type: {0}", ex.GetType().ToString())); Console.WriteLine(String.Format("Fault Code: {0}", ex.Code.Name.ToString())); } catch (Exception ex) { // Customize your own Error handling code. Console.WriteLine(String.Format("Exception Message: {0}", ex.Message.ToString())); }

try { // Set up the Eloqua API Service EloquaService.Eloqua eloquaService = new EloquaService.Eloqua(); EloquaService.EloquaService service = eloquaService.getEloquaService(); // Instantiate a new Eloqua Service object factory EloquaService.ObjectFactory serviceFactory = new EloquaService.ObjectFactory(); // Build a Contact Entity Type object EloquaService.EntityType entityType = new EloquaService.EntityType(); entityType.setID(0); entityType.setName(serviceFactory.createEntityTypeName("Contact")); entityType.setType(serviceFactory.createEntityTypeType("Base")); // Set the ID of the Contact Entity EloquaService.ArrayOfint ids = new EloquaService.ArrayOfint(); ids.getInt().add(1200846); // Create a new array containing the fields you want populated for this Entity EloquaService.ArrayOfstring fieldList = new EloquaService.ArrayOfstring(); // Add the Contact’s Email Address to the field list fieldList.getString().add("C_EmailAddress"); // Add the Contact’s First Name to the field list fieldList.getString().add("C_FirstName"); // Build a Dynamic Entity array to store the results EloquaService.ArrayOfDynamicEntity retrievedEntities; // If the field array is empty - the request will return all Entity Fields // Otherwise, only fields defined in the field list are returned if (fieldList.getString().size() == 0) { // Execute the request and return all of the Entity's fields retrievedEntities = service.retrieve(entityType, ids, null); } else { // Execute the request and return only the selected Entity fields retrievedEntities = service.retrieve(entityType, ids, fieldList); }




See Also

Create

Update

Delete

Query

WSDL Information

Update

Usage

Update one or more Entities in the Eloqua database.

Arguments

dynamicEntity[]

Response

UpdateResult[]

Faults


ValidationFault

InvalidTypeFault


// If a result was found, extract the field values for each Dynamic Entity if (retrievedEntities.getDynamicEntity().size() > 0) { for (EloquaService.DynamicEntity dynamicEntity : retrievedEntities.getDynamicEntity()) { // Extract the Field Name and Value for each element in the collection for (EloquaService.DynamicEntityFields.EntityFields field : dynamicEntity.getFieldValueCollection().getValue().getEntityFields()) { System.out.println(String.format("Field Name: %s", field.getInternalName())); System.out.println(String.format("Field Value: %s", field.getValue())); } } } } catch (Javax.xml.ws.soap.SOAPFaultException ex) { // Customize your own Error handling code. System.out.println(String.format("Message: %s", ex.getMessage())); System.out.println(String.format("Fault Code: %s", ex.getFault().getFaultCode())); } catch (Exception ex)

{ // Customize your own Error handling code. System.out.println(ex.getMessage()); }



Syntax

Sample Code - .NET


Service instance;

DynamicEntity[] dynamicEntities;

UpdateResult[] returnValue;

returnValue = instance.Update(dynamicEntities);

try { // Set up the Eloqua API Service EloquaService.EloquaServiceClient service = new EloquaService.EloquaServiceClient(); service.ClientCredentials.UserName.UserName = "Company\\default.user"; service.ClientCredentials.UserName.Password = "test123"; // Build a Contact Entity Type object EloquaService.EntityType entityType = new EloquaService.EntityType(); entityType.ID = 0; entityType.Name = "Contact"; entityType.Type = "Base"; // Create a new Array of Dynamic Entities EloquaService.DynamicEntity[] dynamicEntities = new EloquaService.DynamicEntity[1]; // Create a new Dynamic Entity and add it to the Array of Entities dynamicEntities[0] = new EloquaService.DynamicEntity(); // Set the Entity Type to Contact dynamicEntities[0].EntityType = entityType; // Set the Contact record's ID dynamicEntities[0].Id = 1; // Create a Dynamic Entity's Field Value Collection dynamicEntities[0].FieldValueCollection = new EloquaService.DynamicEntityFields(); // Add the Contact's Email Address to the Dynamic Entity's field collection dynamicEntities[0].FieldValueCollection.Add("C_EmailAddress", "[email protected]"); // Add the Contact's First Name to the Dynamic Entity's field collection dynamicEntities[0].FieldValueCollection.Add("C_FirstName", "Support"); // Execute the request EloquaService.UpdateResult[] result = service.Update(dynamicEntities);





Note: Java code sample continued on next page.

// Verify the status of each Contact Update request in the results for (int i = 0; i < result.Length; i++) { // Successfull requests return a positive integer value for ID if (result[i].ID != -1) { Console.WriteLine("Success"); } // Failed requests return a -1 integer value for ID else { Console.WriteLine("Failure"); // Extract the Error Message and Error Code for each failed Update request foreach (EloquaService.Error updateError in result[i].Errors) { Console.WriteLine(String.Format("Code: {0}", updateError.ErrorCode)); Console.WriteLine(String.Format("Message: {0}", updateError.Message)); } } } } catch (System.ServiceModel.FaultException ex) { // Customize your own Error handling code. Console.WriteLine(String.Format("Reson: {0}", ex.Reason.ToString())); Console.WriteLine(String.Format("Fault Type: {0}", ex.GetType().ToString())); Console.WriteLine(String.Format("Fault Code: {0}", ex.Code.Name.ToString())); } catch (Exception ex) {

// Customize your own Error handling code. Console.WriteLine(String.Format("Exception Message: {0}", ex.Message.ToString())); }

try { // Set up the Eloqua API Service EloquaService.Eloqua eloquaService = new EloquaService.Eloqua(); EloquaService.EloquaService service = eloquaService.getEloquaService(); // Instantiate a new Eloqua Service object factory EloquaService.ObjectFactory serviceFactory = new EloquaService.ObjectFactory(); // Define a Contact Entity Type object EloquaService.EntityType entityType = new EloquaService.EntityType(); entityType.setID(0); entityType.setName(serviceFactory.createEntityTypeName("Contact")); entityType.setType(serviceFactory.createEntityTypeType("Base")); // Create a new Array of Dynamic Entities EloquaService.ArrayOfDynamicEntity dynamicEntities = new EloquaService.ArrayOfDynamicEntity();




Note: Java code sample conclued on next page.

// Instantiate a new Dynamic Entity EloquaService.DynamicEntity dynamicEntity = new EloquaService.DynamicEntity(); dynamicEntity.setEntityType(serviceFactory.createEntityType(entityType)); // Create a Dynamic Entity's Field Value Collection EloquaService.DynamicEntityFields fieldValueCollection = new EloquaService.DynamicEntityFields(); fieldValueCollection = serviceFactory.createDynamicEntityFields(); // Add the Contact's Email Address to the Dynamic Entity's field collection EloquaService.DynamicEntityFields.EntityFields emailField = serviceFactory.createDynamicEntityFieldsEntityFields(); emailField.setInternalName("C_EmailAddress"); emailField.setValue("[email protected]"); fieldValueCollection.getEntityFields().add(emailField); // Add the Contact's First Name to the Dynamic Entity's field collection EloquaService.DynamicEntityFields.EntityFields firstNameField = serviceFactory.createDynamicEntityFieldsEntityFields(); firstNameField.setInternalName("C_FirstName"); firstNameField.setValue("Support"); fieldValueCollection.getEntityFields().add(firstNameField); // Add the Dynamic Entity's fields to the Dynamic Entitiy's field collection JAXBElement<EloquaService.DynamicEntityFields> fc; fc = serviceFactory.createDynamicEntityFieldValueCollection(fieldValueCollection); dynamicEntity.setFieldValueCollection(fc); // Add the Dynamic Entity (Contact) to the Array of Dynamic Entities dynamicEntities.getDynamicEntity().add(dynamicEntity); // Execute the request EloquaService.ArrayOfUpdateResult result = service.update(dynamicEntities); // Verify the status of each Contact Update request in the results for (int i = 0; i < result.getUpdateResult().size(); i++) { // Successfull requests return a positive integer value for ID if (result.getUpdateResult().get(i).getID() != -1) { System.out.println("Success"); } // Failed requests return a -1 integer value for ID else { System.out.println("Failure"); // Extract the Error Message and Error Code for each failed Update request for (EloquaService.Error UpdateError : result.getUpdateResult().get(i).getErrors().getValue().getError())

{ System.out.println(UpdateError.getErrorCode().value()); System.out.println(UpdateError.getMessage().getValue()); } } } }




See Also

Create

Retrieve

Delete

Query

WSDL Information

Delete

Usage

Delete one or more Entities in the Eloqua database.

Arguments

EntityType

id[] (Integer)

Response

DeleteResult[]

Faults


ValidationFault

InvalidTypeFault


Syntax

catch (Javax.xml.ws.soap.SOAPFaultException ex) { // Customize your own Error handling code. System.out.println(String.format("Message: %s", ex.getMessage())); System.out.println(String.format("Fault Code: %s", ex.getFault().getFaultCode())); } catch (Exception ex) { // Customize your own Error handling code. System.out.println(ex.getMessage()); }

Service instance;

entityType entityType;

int[] ids;

DeleteResult[] returnValue;

returnValue = instance.Delete(entityType, ids);



Sample Code - .NET

try { // Set up the Eloqua API Service EloquaService.EloquaServiceClient service = new EloquaService.EloquaServiceClient(); service.ClientCredentials.UserName.UserName = "Company\\default.user"; service.ClientCredentials.UserName.Password = "test123"; // Build a Contact Entity Type object EloquaService.EntityType entityType = new EloquaService.EntityType(); entityType.ID = 0; entityType.Name = "Contact"; entityType.Type = "Base"; // Set the ID of each Entity that you want to delete int[] ids = new int[1]; ids[0] = 1; // Execute the request EloquaService.DeleteResult[] deleteResults = service.Delete(entityType, ids); // Verify the status of each Delete request in the results for (int i = 0; i <= deleteResults.Length - 1; i++) { // Successfull requests will return a positive integer value for ID if (deleteResults[i].Success) { Console.WriteLine("Success"); } // Failed requests will return a -1 integer value for ID else { Console.WriteLine("Failure"); // Extract the Error Message and Error Code for each failed Delete request foreach (EloquaService.Error deleteError in deleteResults[i].Errors) { Console.WriteLine(String.Format("Code: {0}", deleteError.ErrorCode)); Console.WriteLine(String.Format("Message: {0}", deleteError.Message)); } } } } catch (System.ServiceModel.FaultException ex) { // Customize your own Error handling code. Console.WriteLine(String.Format("Reson: {0}", ex.Reason.ToString())); Console.WriteLine(String.Format("Fault Type: {0}", ex.GetType().ToString())); Console.WriteLine(String.Format("Fault Code: {0}", ex.Code.Name.ToString())); } catch (Exception ex) { // Customize your own Error handling code. Console.WriteLine(String.Format("Exception Message: {0}", ex.Message.ToString())); }




try { // Set up the Eloqua API Service EloquaService.Eloqua eloquaService = new EloquaService.Eloqua(); EloquaService.EloquaService service = eloquaService.getEloquaService(); // Instantiate a new Eloqua Service object factory EloquaService.ObjectFactory serviceFactory = new EloquaService.ObjectFactory(); // Define a Contact Entity Type object EloquaService.EntityType entityType = new EloquaService.EntityType(); entityType.setID(0); entityType.setName(serviceFactory.createEntityTypeName("Contact")); entityType.setType(serviceFactory.createEntityTypeType("Base")); // Set the ID of each Entity that you want to delete EloquaService.ArrayOfint ids = new EloquaService.ArrayOfint(); ids.getInt().add(1); // Execute the request EloquaService.ArrayOfDeleteResult deleteResults = service.delete(entityType, ids); // Verify the status of each Delete request in the results for (int i = 0; i <= deleteResults.getDeleteResult().size(); i++) { // Successfull requests return a positive integer value for ID if (deleteResults.getDeleteResult().get(i).isSuccess()) { System.out.println("Success"); } // Failed requests return a -1 integer value for ID else { System.out.println("Failure"); // Extract the Error Message and Error Code for each failed Delete request for (EloquaService.Error deleteError : deleteResults.getDeleteResult().get(i).getErrors().getValue().getError()) { System.out.println(String.format("Code: %s", deleteError.getErrorCode().value())); System.out.println(String.format("Message: %s", deleteError.getMessage().getValue())); } } } } catch (Javax.xml.ws.soap.SOAPFaultException ex) { // Customize your own Error handling code. System.out.println(String.format("Message: %s", ex.getMessage())); System.out.println(String.format("Fault Code: %s", ex.getFault().getFaultCode())); } catch (Exception ex) { // Customize your own Error handling code. System.out.println(ex.getMessage()); }



See Also

Create

Retrieve

Update

Query

WSDL Information

Query

Usage

Query one or more Entities from the Eloqua database.

Syntax

<SEARCH_TERM> <OPERATOR> ‘<VALUE>’ AND ‘<VALUE>’

Search Term—The field to search for, represented by a string with no spaces.

Value—The value to search for, represented by a string enclosed in quotes. This value can include the

wildcard: *

Boolean (AND) Operator—An optional Boolean operator equivalent to an intersection of the 2 search

values (see the List of Operators below).

Note: If you query the database and the resultset is greater than 2000 records, an error will be returned(with

no records). Your query needs to be adjusted to return fewer than 2000 records before you will receive any

results. You can page through the results 20 results at a time. Should you require a larger set of results, you

could setup a bulk download via the API.

List of Operators:

Operator Query Syntax

Equal To =

Not Equal To -

Greater Than >

Less Than <

Greater Than or Equal To >=

Less Than or Equal To <=

Arguments

EntityType[]

searchQuery (String)

fieldnames[] (String[])

pageNumber (Integer)

pageSize (Integer)



Response

DynamicEntityQueryResults

Faults


ValidationFault

InvalidTypeFault

QueryTooLargeFault

InvalidQueryFault

OperationTimeIntervalFault

Syntax

Sample Code - .NET


Service instance;

entityType entityType;

String searchQuery;

String[] fieldnames;

int pageNumber;

int pageSize;

queryResult[] returnValue;

returnValue = instance.Query(entityType, searchQuery, fieldList,

pageNumber, pageSize);

try { // Set up the Eloqua API Service EloquaService.EloquaServiceClient service = new EloquaService.EloquaServiceClient(); service.ClientCredentials.UserName.UserName = "Company\\default.user"; service.ClientCredentials.UserName.Password = "test123"; // Build a Contact Entity Type object EloquaService.EntityType entityType = new EloquaService.EntityType(); entityType.ID = 0; entityType.Name = "Contact"; entityType.Type = "Base"; // Create a new list containing the fields you want populated List<string> fieldList = new List<string>(); // Add the Contact's Email Address to the field list fieldList.Add("C_EmailAddress"); // Add the Contact's First Name to the field list fieldList.Add("C_FirstName"); // Build the Search Query String queryText = "C_EmailAddress ='*@eloqua.com'"; // Define a container for the Query results EloquaService.DynamicEntityQueryResults queryResult;




// Set the page number and size for the results int currentPage = 0; int pageSize = 20; // If the field list is empty - the request will return all Entity Fields // Otherwise, only fields defined in the field list are returned if (fieldList.Count == 0) { // Execute the request and return all of the Entity's fields queryResult = service.Query(entityType, queryText, null, currentPage, pageSize); } else { // Execute the request and return only the selected Entity fields queryResult = service.Query(entityType, queryText, fieldList.ToArray(), currentPage, pageSize); } if (queryResult.Entities.Length > 0) { // Extract the total number of pages and records Console.WriteLine(String.Format("Total number of pages: {0}", queryResult.TotalPages.ToString())); Console.WriteLine(String.Format("Total number of records: {0}", queryResult.TotalRecords.ToString())); // Extract each Dynamic Entity in the result foreach (EloquaService.DynamicEntity dynamicEntity in queryResult.Entities) { // Extract the Entity ID Console.WriteLine(String.Format("Entity ID: {0}", dynamicEntity.Id)); // Extract the field name and value of each field in the collection foreach (KeyValuePair<string, string> field in dynamicEntity.FieldValueCollection) { Console.WriteLine(String.Format("Field Name: {0}", field.Key)); Console.WriteLine(String.Format("Field Value: {0}", field.Value)); } } } } catch (System.ServiceModel.FaultException ex) { // Customize your own Error handling code. Console.WriteLine(String.Format("Reson: {0}", ex.Reason.ToString())); Console.WriteLine(String.Format("Fault Type: {0}", ex.GetType().ToString())); Console.WriteLine(String.Format("Fault Code: {0}", ex.Code.Name.ToString())); } catch (Exception ex) { // Customize your own Error handling code. Console.WriteLine(String.Format("Exception Message: {0}", ex.Message.ToString())); }




Note: Java code sample conclued on next page.

try { // Set up the Eloqua API Service EloquaService.Eloqua eloquaService = new EloquaService.Eloqua(); EloquaService.EloquaService service = eloquaService.getEloquaService(); // Instantiate a new Eloqua Service object factory EloquaService.ObjectFactory serviceFactory = new EloquaService.ObjectFactory(); // Define a Contact Entity Type object EloquaService.EntityType entityType = new EloquaService.EntityType(); entityType.setID(0); entityType.setName(serviceFactory.createEntityTypeName("Contact")); entityType.setType(serviceFactory.createEntityTypeType("Base")); // Create a new list containing the fields you want populated Java.util.List<String> fieldList = new Java.util.ArrayList<String>(); // Add the Contact's Email Address to the field list fieldList.add("C_EmailAddress"); // Add the Contact's First Name to the field list fieldList.add("C_FirstName"); // Build the Search Query String queryText = "C_EmailAddress ='*@eloqua.com'"; // Build a new container for the Query results EloquaService.DynamicEntityQueryResults queryResult; // Set the page number and size for the results int currentPage = 0; int pageSize = 20; // If the field list is empty - the request will return all Entity Fields // Otherwize, only fields defined in the field list are returned if (fieldList.size() == 0) { // Execute the request and return all of the Entity's fields queryResult = service.query(entityType, queryText, null, pageSize, pageSize); } else { // Execute the request and return only the selected fields queryResult = service.query(entityType, queryText, null, pageSize, pageSize); } if (queryResult.getEntities().getValue().getDynamicEntity().size() > 0) { // Extract the total number of pages and records System.out.println(String.format("Total number of pages: %s", queryResult.getTotalPages())); System.out.println(String.format("Total number of records: %s", queryResult.getTotalRecords()));




See Also

Create

Retrieve

Update

Delete

WSDL Information

ASSET METADATA

An Asset is an abstract representation of structured data in Eloqua, such as an Email Brochure or Data

Export. Assets can have attributes. Examples: An Email Brochure has a Subject and Body. DataImports

have a title and an ID.

The web service contains operations for discovering all the assets and asset types in the system. The

following operations are available:

1. ListAssetTypes()

This function will return a list of the currently accessible AssetTypes from within your instance of

Eloqua which can then be used as a parameter for DescribeAssetType.

2. DescribeAssetType()

This will return attributes of the AssetType that you specify

// Extract each Dynamic Entity in the result for (EloquaService.DynamicEntity dynamicEntity : queryResult.getEntities().getValue().getDynamicEntity()) { // Extract the Entity ID System.out.println(String.format("Entity ID: %s", dynamicEntity.getId()));

// Extract the field name and value of each field in the collection for (EloquaService.DynamicEntityFields.EntityFields field : dynamicEntity.getFieldValueCollection().getValue().getEntityFields()) { System.out.println(String.format("Field Name: %s", field.getInternalName()));

System.out.println(String.format("Field Value: %s", field.getValue())); } } } } catch (Javax.xml.ws.soap.SOAPFaultException ex) { // Customize your own Error handling code. System.out.println(String.format("Message: %s", ex.getMessage())); System.out.println(String.format("Fault Code: %s", ex.getFault().getFaultCode())); } catch (Exception ex) { // Customize your own Error handling code. System.out.println(ex.getMessage()); }



ASSET METADATA OPERATIONS

ListAssetTypes

Usage

Retrieve all the Asset Types in your Eloqua database. Only Types available in the instance of Eloqua which

you are logged into are returned. Your application can parse the response and query for further information

such as the metadata for each Asset Type.

Arguments

None

Response

ListAssetTypeResult

Faults


Syntax

Service instance;

ListAssetTypesResult returnValue;

returnValue = instance.ListAssetTypes();



Sample Code - .NET


try { // Set up the Eloqua API Service EloquaService.EloquaServiceClient service = new EloquaService.EloquaServiceClient(); service.ClientCredentials.UserName.UserName = "Company\\default.user"; service.ClientCredentials.UserName.Password = "test123"; // Execute the request EloquaService.ListAssetTypesResult result = service.ListAssetTypes(); // Extract the name of each Asset Type foreach (String AssetType in result.AssetTypes) { Console.WriteLine(AssetType); } } catch (System.ServiceModel.FaultException ex) { // Customize your own Error handling code. Console.WriteLine(String.Format("Reson: {0}", ex.Reason.ToString())); Console.WriteLine(String.Format("Fault Type: {0}", ex.GetType().ToString())); Console.WriteLine(String.Format("Fault Code: {0}", ex.Code.Name.ToString())); } catch (Exception ex) { // Customize your own Error handling code. Console.WriteLine(String.Format("Exception Message: {0}", ex.Message.ToString())); }

try { // Set up the Eloqua API Service EloquaService.Eloqua eloquaService = new EloquaService.Eloqua(); EloquaService.EloquaService service = eloquaService.getEloquaService(); // Execute the request EloquaService.ListAssetTypesResult result = service.listAssetTypes(); // Extract the name of each Asset Type for (String assetType : result.getAssetTypes().getValue().getString()) { System.out.println(assetType); } } catch (Javax.xml.ws.soap.SOAPFaultException ex) { // Customize your own Error handling code. System.out.println(String.format("Message: %s", ex.getMessage())); System.out.println(String.format("Fault Code: %s", ex.getFault().getFaultCode())); } catch (Exception ex) { // Customize your own Error handling code. System.out.println(ex.getMessage()); }



See Also

DescribeAssetType

WSDL Information

DescribeAssetType

Usage

Retrieve all the Assets in a given Asset Type.

Arguments

assetType (String)

Response

DescribeAssetTypeResult

Faults


ValidationFault

InvalidTypeFault

Syntax

Service instance;

String entityName;

DescribeAssetTypeResult returnValue;

returnValue = instance.DescribeAssetType(assetType);



Sample Code - .NET

try { // Set up the Eloqua API Service EloquaService.EloquaServiceClient service = new EloquaService.EloquaServiceClient(); service.ClientCredentials.UserName.UserName = "Company\\default.user"; service.ClientCredentials.UserName.Password = "test123"; // Execute the request EloquaService.DescribeAssetTypeResult result = service.DescribeAssetType("DataExport"); // Extract the ID, Name and Type of each Asset Type foreach (EloquaService.AssetType AssetType in result.AssetTypes) { Console.WriteLine(String.Format("ID: {0}", AssetType.ID)); Console.WriteLine(String.Format("Type: {0}", AssetType.Type)); Console.WriteLine(String.Format("Name: {0}", AssetType.Name)); } } catch (System.ServiceModel.FaultException ex) { // Customize your own Error handling code. Console.WriteLine(String.Format("Reson: {0}", ex.Reason.ToString())); Console.WriteLine(String.Format("Fault Type: {0}", ex.GetType().ToString())); Console.WriteLine(String.Format("Fault Code: {0}", ex.Code.Name.ToString())); } catch (Exception ex) { // Customize your own Error handling code. Console.WriteLine(String.Format("Exception Message: {0}", ex.Message.ToString())); }




See Also

ListAssetTypes

WSDL Information

Data Transfer Service

The Data Transfer service has also been referred to as “Bulk” data transfers in this guide. The data transfer

service allows for the updating of large numbers of records within Eloqua in a scalable fashion. It also allows

for bulk transfer of data from Eloqua to a streamlined file for download and manipulation. The data transfer

service is the preferred method of transferring records if the number of records will regularly exceed 2000

records as this is the current limit for any queries into the Eloqua system through the web services API.

The Data Export service will allow the export via the API of any saved report in the system that returns a list

of Contact, Prospect or Company entity records. It will also allow for the export of static reports that contain

contact activity data:

try { // Set up the Eloqua API Service EloquaService.Eloqua eloquaService = new EloquaService.Eloqua(); EloquaService.EloquaService service = eloquaService.getEloquaService(); // Execute the request EloquaService.DescribeAssetTypeResult result = service.describeAssetType("DataImport"); // Extract the ID, Name and Type of each Asset Type for (EloquaService.AssetType assetType : result.getAssetTypes().getValue().getAssetType()) { System.out.println(String.format("ID: %s", String.valueOf(assetType.getID()))); System.out.println(String.format("Name %s", assetType.getName().getValue())); System.out.println(String.format("Type: %s", assetType.getType().getValue())); } } catch (Javax.xml.ws.soap.SOAPFaultException ex) { // Customize your own Error handling code. System.out.println(String.format("Message: %s", ex.getMessage())); System.out.println(String.format("Fault Code: %s", ex.getFault().getFaultCode())); } catch (Exception ex) { // Customize your own Error handling code. System.out.println(ex.getMessage()); }



Running an export via the API will first trigger the Eloqua server to produce a Report and export it to a flat

file on our servers. This flat file can then be transferred via the API as a binary transfer to your web service.

The web service on your end is then responsible for parsing or transferring the contents of the file.

Running an import of a file must first be setup within the Eloqua User Interface to specify the following

settings into an “AutoSynch”: Field mappings, actions to perform after upload, notification of success or

failure. When importing via the API, you will need to specify the ID of one of these previously saved

“AutoSynchs” to be used when importing your file.

The Data Transfer services use the following WSDL:


Data Transfer Services support bulk transfer of flat files through the API. This particular API endpoint has

been optimized for transmitting binary files.

Note: Only Reports that are regular Contact/Prospect/Company record type of Reports are exportable

through the data transfer service. Some saved Reports will not be visible via the API because they are not

one of these standard types (ie: visitor reports).

DATA EXPORT OPERATIONS

Before you can export data through the bulk export system you will need to login to the Eloqua UI and create

some standard data extracts that you will be performing. You will need to create a “saved report” within

Eloqua – and then setup that saved report for export. Once that is performed – the newly created export

report will be shown when describing the DataIExport Assets via the API.

The following Data Export operations are available:

InitializeDataExport

Usage

Initialize a Data Export.




Arguments

AssetType

Response

DataExportExecution

Faults


ValidationFault

OperationTimeIntervalFault

Syntax

Sample Code - .NET

Service instance;

AssetType assetType;

instance.InitializeDataExport(assetType);

try { // Set up the Eloqua API Data Transfer Service EloquaDataService.DataTransferServiceClient service = new EloquaDataService.DataTransferServiceClient(); service.ClientCredentials.UserName.UserName = "Eloqua\\api.user"; service.ClientCredentials.UserName.Password = "test123"; // Build an Asset Type object EloquaDataService.AssetType assetType = new EloquaDataService.AssetType(); assetType.ID = 0; assetType.Name = "Sample Data Export"; assetType.Type = "DataExport"; // Execute the request service.InitializeDataExport(assetType); // Extract the ID of the Data Export Execution Console.WriteLine(String.Format("Data Export Initialized")); } catch (System.ServiceModel.FaultException ex) { // Customize your own Error handling code. Console.WriteLine(String.Format("Reson: {0}", ex.Reason.ToString())); Console.WriteLine(String.Format("Fault Type: {0}", ex.GetType().ToString())); Console.WriteLine(String.Format("Fault Code: {0}", ex.Code.Name.ToString())); } catch (Exception ex) { // Customize your own Error handling code. Console.WriteLine(String.Format("Exception Message: {0}", ex.Message.ToString())); }




See Also

DataExportStatus

GetDataExportFile

WSDL Information

try { // Set up the Eloqua API Data Transfer Service EloquaDataService.EloquaDataTransfer eloquaService = new EloquaDataService.EloquaDataTransfer(); EloquaDataService.DataTransferService service = eloquaService.getEloquaDataTransferService(); // Instantiate a new Eloqua Data Transfer Service object factory EloquaDataService.ObjectFactory serviceFactory = new EloquaDataService.ObjectFactory(); // Build an Asset Type object EloquaDataService.AssetType assetType = new EloquaDataService.AssetType(); assetType.setID(0); assetType.setName(serviceFactory.createAssetTypeName("Sample Data Export")); assetType.setType(serviceFactory.createAssetTypeType("DataExport")); // Execute the request service.initializeDataExport(assetType); // Extract the ID of the Data Export Execution System.out.println(String.format("Data Export Initialized",)); } catch (Javax.xml.ws.soap.SOAPFaultException ex) { // Customize your own Error handling code. System.out.println(String.format("Message: %s", ex.getMessage())); System.out.println(String.format("Fault Code: %s", ex.getFault().getFaultCode())); } catch (Exception ex) { // Customize your own Error handling code. System.out.println(ex.getMessage()); }



DataExportStatus

Usage

Retrieve the status of a Data Export execution.

Arguments

AssetType

Response

DataExportExecutionStatus

Faults


ValidationFault

Syntax

Service instance;


DataExportExecutionStatus returnValue;

returnValue = instance.DataExportStatus(assetType);



Sample Code - .NET

try { // Set up the Eloqua API Data Transfer Service EloquaDataService.DataTransferServiceClient service = new EloquaDataService.DataTransferServiceClient(); service.ClientCredentials.UserName.UserName = "Company\\default.user"; service.ClientCredentials.UserName.Password = "test123"; // Build a Data Export Asset Type object EloquaDataService.AssetType assetType = new EloquaDataService.AssetType(); assetType.ID = 0; assetType.Name = "Sample Data Export"; assetType.Type = "DataExport"; // Execute the request EloquaDataService.DataExportExecutionStatus status = service.DataExportStatus(assetType); // Extract the status of the Data Export switch (status) { case SampleCode.EloquaDataService.DataExportExecutionStatus.Complete: Console.WriteLine("Data Export is Complete"); break; case SampleCode.EloquaDataService.DataExportExecutionStatus.Failure: Console.WriteLine("Data Export Failed"); break; case SampleCode.EloquaDataService.DataExportExecutionStatus.InProgress: Console.WriteLine("Data Export in Progress"); break; } } catch (System.ServiceModel.FaultException ex) { // Customize your own Error handling code. Console.WriteLine(String.Format("Reson: {0}", ex.Reason.ToString())); Console.WriteLine(String.Format("Fault Type: {0}", ex.GetType().ToString())); Console.WriteLine(String.Format("Fault Code: {0}", ex.Code.Name.ToString())); } catch (Exception ex) { // Customize your own Error handling code. Console.WriteLine(String.Format("Exception Message: {0}", ex.Message.ToString())); }




See Also


GetDataExportFile

WSDL Information

GetDataExportFile

Usage

Retrieve the Data Export file.

Arguments

AssetType

try { // Set up the Eloqua API Data Transfer Service EloquaDataService.EloquaDataTransfer eloquaService = new EloquaDataService.EloquaDataTransfer(); EloquaDataService.DataTransferService service = eloquaService.getEloquaDataTransferService(); // Instantiate a new Eloqua Data Transfer Service object factory EloquaDataService.ObjectFactory serviceFactory = new EloquaDataService.ObjectFactory(); // Build a Data Export Asset Type object EloquaDataService.AssetType assetType = new EloquaDataService.AssetType(); assetType.setID(0); assetType.setName(serviceFactory.createAssetTypeName("Sample Data Export")); assetType.setType(serviceFactory.createAssetTypeType("DataExport")); // Execute the request EloquaDataService.DataExportExecutionStatus status = service.dataExportStatus(assetType); // Extract the status of the Data Export switch (status) { case COMPLETE: System.out.println("Data Export is Complete"); case FAILURE: System.out.println("Data Export Failed"); case IN_PROGRESS: System.out.println("Data Export in Progress"); } } catch (Javax.xml.ws.soap.SOAPFaultException ex) { // Customize your own Error handling code. System.out.println(String.format("Message: %s", ex.getMessage())); System.out.println(String.format("Fault Code: %s", ex.getFault().getFaultCode())); } catch (Exception ex) { // Customize your own Error handling code. System.out.println(ex.getMessage()); }



Response

Byte[]

Faults


ValidationFault

Syntax

Service instance;


Byte[] returnValue;

returnValue = instance.GetDataExportFile(assetType);



Sample Code - .NET

try { // Set up the Eloqua API Data Transfer Service EloquaDataService.DataTransferServiceClient service = new EloquaDataService.DataTransferServiceClient(); service.ClientCredentials.UserName.UserName = "Company\\default.user"; service.ClientCredentials.UserName.Password = "test123"; // Build a Data Export Asset Type object EloquaDataService.AssetType assetType = new EloquaDataService.AssetType(); assetType.ID = 0; assetType.Name = "Sample Data Export"; assetType.Type = "DataExport"; // Execute the request Byte[] byteData = service.GetDataExportFile(assetType); // Define the file and filestream String fileName = "c:\\fileName.txt"; System.IO.FileStream ioFileStream = null; // Try writing the bytes to a file try { // Instatiate a new file stream ioFileStream = new System.IO.FileStream(fileName, System.IO.FileMode.Create); // Try writing the bytes to the file ioFileStream.Write(byteData, 0, byteData.Length); } catch (Exception ex) { throw new System.Exception(String.Format("Unable to create file {0}", fileName)); } finally { // Close the file stream ioFileStream.Close(); } } catch (System.ServiceModel.FaultException ex) { // Customize your own Error handling code. Console.WriteLine(String.Format("Reson: {0}", ex.Reason.ToString())); Console.WriteLine(String.Format("Fault Type: {0}", ex.GetType().ToString())); Console.WriteLine(String.Format("Fault Code: {0}", ex.Code.Name.ToString())); } catch (Exception ex) { // Customize your own Error handling code. Console.WriteLine(String.Format("Exception Message: {0}", ex.Message.ToString())); }




See Also


DataExportStatus

WSDL Information

try { // Set up the Eloqua API Data Transfer Service EloquaDataService.EloquaDataTransfer eloquaService = new EloquaDataService.EloquaDataTransfer(); EloquaDataService.DataTransferService service = eloquaService.getEloquaDataTransferService(); // Instantiate a new Eloqua Data Transfer Service object factory EloquaDataService.ObjectFactory serviceFactory = new EloquaDataService.ObjectFactory(); // Build a Data Export Asset Type object EloquaDataService.AssetType assetType = new EloquaDataService.AssetType(); assetType.setID(0); assetType.setName(serviceFactory.createAssetTypeName("Sample Data Export")); assetType.setType(serviceFactory.createAssetTypeType("DataExport")); // Execute the request byte[] bytes = service.getDataExportFile(assetType); // Define the file String fileName = "c:\\fileName.txt"; // Try writing the bytes to a file try { // Instantiate a new file stream Java.io.FileOutputStream fileOutputStream = new Java.io.FileOutputStream(fileName); // Try writing the bytes to the file fileOutputStream.write(bytes); // Close the file stream fileOutputStream.close(); } catch (Exception ex) { throw new Exception(String.format("Unable to create file %s", fileName)); } } catch (Javax.xml.ws.soap.SOAPFaultException ex) { // Customize your own Error handling code. System.out.println(String.format("Message: %s", ex.getMessage())); System.out.println(String.format("Fault Code: %s", ex.getFault().getFaultCode())); } catch (Exception ex) { // Customize your own Error handling code. System.out.println(ex.getMessage()); }



DATA IMPORT OPERATIONS

The following Data Import operations are available:

InitializeDataImport

Usage

Initialize a Data Import.

Arguments

Byte[]

AssetType

DataSourceType

Response

DataImportExecution

Faults


ValidationFault

InvalidFileType

QueueLimitReachedFault

Syntax

Service instance;

Byte[] data;


DataSourceType dataSourceType;

Byte[] returnValue;

returnValue = instance.InitializeDataImport(data, assetType,

dataSourceType);



Sample Code - .NET

try { // Set up the Eloqua API Data Transfer Service EloquaDataService.DataTransferServiceClient service = new EloquaDataService.DataTransferServiceClient(); service.ClientCredentials.UserName.UserName = "Company\\default.user"; service.ClientCredentials.UserName.Password = "test123"; // Build a Data Import Asset Type object EloquaDataService.AssetType assetType = new EloquaDataService.AssetType(); assetType.ID = 0; assetType.Name = "Sample Data Import"; assetType.Type = "DataImport"; // Select a Delimited file for the Data Source Type EloquaDataService.DataSourceType dataSourceType = SampleCode.EloquaDataService.DataSourceType.DelimitedFile; // Set the filename String fileName = "c:\\fileName.txt"; // Instantiate a new file and binary reader FileInfo fileInfo = new FileInfo(fileName); BinaryReader binaryReader = new BinaryReader(new FileStream(fileName, FileMode.Open, FileAccess.Read)); // Read the file into a Byte array Byte[] data = binaryReader.ReadBytes(Convert.ToInt32(fileInfo.Length)); // Close the binary reader binaryReader.Close(); // Execute the request EloquaDataService.DataImportExecution dataImportExecution = service.InitializeDataImport(data, assetType, dataSourceType); // Extract the ID of the Data Import Execution Console.WriteLine(String.Format("Data Import Execution ID: {0}", dataImportExecution.ID.ToString())); } catch (System.ServiceModel.FaultException ex) { // Customize your own Error handling code. Console.WriteLine(String.Format("Reson: {0}", ex.Reason.ToString())); Console.WriteLine(String.Format("Fault Type: {0}", ex.GetType().ToString())); Console.WriteLine(String.Format("Fault Code: {0}", ex.Code.Name.ToString())); } catch (Exception ex) { // Customize your own Error handling code. Console.WriteLine(String.Format("Exception Message: {0}", ex.Message.ToString())); }




try { // Set up the Eloqua API Data Transfer Service EloquaDataService.EloquaDataTransfer eloquaService = new EloquaDataService.EloquaDataTransfer(); EloquaDataService.DataTransferService service = eloquaService.getEloquaDataTransferService(); // Instantiate a new Eloqua Data Transfer Service object factory EloquaDataService.ObjectFactory serviceFactory = new EloquaDataService.ObjectFactory(); // Build a Data Import Asset Type object EloquaDataService.AssetType assetType = new EloquaDataService.AssetType(); assetType.setID(0); assetType.setName(serviceFactory.createAssetTypeName("Sample Data Import")); assetType.setType(serviceFactory.createAssetTypeType("DataImport")); // Select a Delimited file for the Data Source Type EloquaDataService.DataSourceType dataSourceType = EloquaDataService.DataSourceType.DELIMITED_FILE; // Set the filename String fileName = "c:\\fileName.txt"; Java.io.File file = new Java.io.File(fileName); // Instantiate a new input stream Java.io.InputStream is = new Java.io.FileInputStream(fileName); byte[] byteData = new byte[(int) file.length()]; // Read the bytes to file int offset = 0; int numRead = 0; while (offset < file.length() && (numRead=is.read(byteData, offset, byteData.length-offset)) >= 0) { offset += numRead; } // Execute the request EloquaDataService.DataImportExecution dataImportExecution = service.initializeDataImport(byteData, assetType, dataSourceType); // Extract the Data Import Execution ID System.out.println(String.format("Data Import Execution ID: %s", dataImportExecution.getID().toString())); } catch (Javax.xml.ws.soap.SOAPFaultException ex) { // Customize your own Error handling code. System.out.println(String.format("Message: %s", ex.getMessage())); System.out.println(String.format("Fault Code: %s", ex.getFault().getFaultCode())); } catch (Exception ex) { // Customize your own Error handling code. System.out.println(ex.getMessage()); }



See Also

DataImportStatus

WSDL Information

DataImportStatus

Usage

Check the status of a Data Import.

Arguments

AssetType

DataImportExecution

Response

DataImportExecutionStatus

Faults


ValidationFault

Syntax

Service instance;


DataImportExecution dataImportExecution;

DataImportExecutionStatus returnValue;

returnValue = instance.DataImportStatus(assetType, dataImportExecution);



Sample Code - .NET

try { // Set up the Eloqua API Data Transfer Service EloquaDataService.DataTransferServiceClient service = new EloquaDataService.DataTransferServiceClient(); service.ClientCredentials.UserName.UserName = "Company\\default.user"; service.ClientCredentials.UserName.Password = "test123"; // Build a Data Import Asset Type object EloquaDataService.AssetType assetType = new EloquaDataService.AssetType(); assetType.ID = 0; assetType.Name = "Sample Data Import"; assetType.Type = "DataImport"; // Instantiate a new Data Import Execution object EloquaDataService.DataImportExecution dataImportExecution = new EloquaDataService.DataImportExecution(); // Set the Data Import Execution ID (see InitializeDataImport) dataImportExecution.ID = 1; // Execute the request EloquaDataService.DataImportExecutionStatus status = service.DataImportStatus(assetType, dataImportExecution); // Check the Data Import status if (status == SampleCode.EloquaDataService.DataImportExecutionStatus.Complete) { Console.WriteLine("Data Import is Complete"); } else { Console.WriteLine(String.Format("Status of the Data Import: {0}", status.ToString())); } } catch (System.ServiceModel.FaultException ex) { // Customize your own Error handling code. Console.WriteLine(String.Format("Reson: {0}", ex.Reason.ToString())); Console.WriteLine(String.Format("Fault Type: {0}", ex.GetType().ToString())); Console.WriteLine(String.Format("Fault Code: {0}", ex.Code.Name.ToString())); } catch (Exception ex) { // Customize your own Error handling code. Console.WriteLine(String.Format("Exception Message: {0}", ex.Message.ToString())); }




try { // Set up the Eloqua API Data Transfer Service EloquaDataService.EloquaDataTransfer eloquaService = new EloquaDataService.EloquaDataTransfer(); EloquaDataService.DataTransferService service = eloquaService.getEloquaDataTransferService(); // Instantiate a new Eloqua Data Transfer Service object factory EloquaDataService.ObjectFactory serviceFactory = new EloquaDataService.ObjectFactory(); // Build a Data Import Asset Type object EloquaDataService.AssetType assetType = new EloquaDataService.AssetType(); assetType.setID(0); assetType.setName(serviceFactory.createAssetTypeName("Sample Data Import")); assetType.setType(serviceFactory.createAssetTypeType("DataImport")); // Instantiate a new Data Import Execution object EloquaDataService.DataImportExecution dataImportExecution = new EloquaDataService.DataImportExecution(); // Set the Data Import Execution ID (see InitializeDataImport) dataImportExecution.setID(1); // Execute the request EloquaDataService.DataImportExecutionStatus status = service.dataImportStatus(assetType, dataImportExecution); // Check the Data Import status if (status == EloquaDataService.DataImportExecutionStatus.COMPLETE) { System.out.println("Data Import is complete"); } else { System.out.println(String.format("Status of the Data Import: %s", status.values().toString())); } } catch (Javax.xml.ws.soap.SOAPFaultException ex) { // Customize your own Error handling code. System.out.println(String.format("Message: %s", ex.getMessage())); System.out.println(String.format("Fault Code: %s", ex.getFault().getFaultCode())); } catch (Exception ex) { // Customize your own Error handling code. System.out.println(ex.getMessage()); }



See Also

InitializeDataImport

WSDL Information

Errors

BatchSizeExceededFault An operation tried to process more records than allowed by the

maximum batch size. Consider using the Data Transfer service

when working with large data sets.

DuplicateValue A duplicate value is not permitted.

InvalidDataType The data type is invalid.

ItemNotFound The item was not found.

MaximumLengthExceeded The maximum length was exceeded.

OperationTimeIntervalFault The operation was requested too many times within the specified

time interval.

QueryTooLargeFault Query results are too large. Consider using the Data Transfer

service when working with large data sets.

RequiredFieldNotSpecified The operation requires a field that was not supplied.

UnauthorizedAction The operation’s requestor was not authorized or does not have the

appropriate permission.

UnexpectedDataException The supplied data was not in the expected format.

UnexpectedException An unexpected error occurred. This represents an internal error in

Eloqua.

Engineering

Eloqua web services api 1.2 user guide v1.0.1