eloqua web services api 1.2 user guide v1.0.1
Post on 22-Nov-2014
237 Views
Preview:
DESCRIPTION
TRANSCRIPT
© 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.
866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
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
866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
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
Eloqua® Web Services API v1.2 User Guide
2 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
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.
Eloqua® Web Services API v1.2 User Guide
3 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
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.
Eloqua® Web Services API v1.2 User Guide
4 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
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:
Eloqua® Web Services API v1.2 User Guide
5 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
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.
Eloqua® Web Services API v1.2 User Guide
6 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
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();
Eloqua® Web Services API v1.2 User Guide
7 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
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.
Eloqua® Web Services API v1.2 User Guide
8 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
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
Eloqua® Web Services API v1.2 User Guide
9 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
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
Eloqua® Web Services API v1.2 User Guide
10 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
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® Web Services API v1.2 User Guide
11 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
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.
Eloqua® Web Services API v1.2 User Guide
12 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
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
Eloqua® Web Services API v1.2 User Guide
13 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
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.
Eloqua® Web Services API v1.2 User Guide
14 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
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.
Eloqua® Web Services API v1.2 User Guide
15 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
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.
Eloqua® Web Services API v1.2 User Guide
16 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
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
Eloqua® Web Services API v1.2 User Guide
17 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
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.
Eloqua® Web Services API v1.2 User Guide
18 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
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.
Eloqua® Web Services API v1.2 User Guide
19 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
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® Web Services API v1.2 User Guide
20 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
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
Eloqua® Web Services API v1.2 User Guide
21 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
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
Eloqua® Web Services API v1.2 User Guide
22 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
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:
Eloqua® Web Services API v1.2 User Guide
23 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
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();
Eloqua® Web Services API v1.2 User Guide
24 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
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()); }
Eloqua® Web Services API v1.2 User Guide
25 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
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
UnexpectedErrorFault
ValidationFault
InvalidTypeFault
Syntax
Service instance;
String entityName;
DescribeEntityTypeResult returnValue;
returnValue = instance.DescribeEntityType(entityType);
Eloqua® Web Services API v1.2 User Guide
26 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
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.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()); }
Eloqua® Web Services API v1.2 User Guide
27 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
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
UnexpectedErrorFault
ValidationFault
InvalidTypeFault
Syntax
Service instance;
EntityType entityType;
DescribeEntityResult returnValue;
returnValue = instance.DescribeEntity (entityType);
Eloqua® Web Services API v1.2 User Guide
28 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
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())); }
Eloqua® Web Services API v1.2 User Guide
29 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
Sample Code – Java
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()); }
Eloqua® Web Services API v1.2 User Guide
30 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
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
UnexpectedErrorFault
ValidationFault
InvalidTypeFault
BatchSizeExceededFault
Syntax
Service instance;
DynamicEntity[] dynamicEntities;
CreateResult[] returnValue;
returnValue = instance.Create(dynamicEntities);
Eloqua® Web Services API v1.2 User Guide
31 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
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", "support@eloqua.com"); // 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)
Eloqua® Web Services API v1.2 User Guide
32 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
Sample Code - .NET (continued)
Sample Code – Java
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("support@eloqua.com"); 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);
Eloqua® Web Services API v1.2 User Guide
33 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
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()); }
Eloqua® Web Services API v1.2 User Guide
34 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
Retrieve
Usage
Retrieve one or more Entities from the Eloqua database.
Arguments
EntityType
id[] (Integer)
String[] fieldList
Response
RetrieveResult[]
Faults
UnexpectedErrorFault
ValidationFault
InvalidTypeFault
BatchSizeExceededFault
Syntax
Service instance;
EntityType entityType;
int[] ids;
String[] fieldList;
DynamicEntity[] returnValue;
returnValue = instance.Retrieve(entityType, ids, fieldList);
Eloqua® Web Services API v1.2 User Guide
35 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
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"; // 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)
Eloqua® Web Services API v1.2 User Guide
36 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
Sample Code - .NET (continued)
Sample Code – Java
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); }
Eloqua® Web Services API v1.2 User Guide
37 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
Sample Code – Java (continued)
See Also
Create
Update
Delete
Query
WSDL Information
Update
Usage
Update one or more Entities in the Eloqua database.
Arguments
dynamicEntity[]
Response
UpdateResult[]
Faults
UnexpectedErrorFault
ValidationFault
InvalidTypeFault
BatchSizeExceededFault
// 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()); }
Eloqua® Web Services API v1.2 User Guide
38 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
Syntax
Sample Code - .NET
Note: .NET code sample concluded on next page.
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", "support@eloqua.com"); // 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);
Eloqua® Web Services API v1.2 User Guide
39 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
Sample Code - .NET (continued)
Sample Code – Java
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();
Eloqua® Web Services API v1.2 User Guide
40 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
Sample Code – Java (continued)
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("support@eloqua.com"); 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()); } } } }
Eloqua® Web Services API v1.2 User Guide
41 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
Sample Code – Java (continued)
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
UnexpectedErrorFault
ValidationFault
InvalidTypeFault
BatchSizeExceededFault
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);
Eloqua® Web Services API v1.2 User Guide
42 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
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())); }
Eloqua® Web Services API v1.2 User Guide
43 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
Sample Code – Java
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()); }
Eloqua® Web Services API v1.2 User Guide
44 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
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)
Eloqua® Web Services API v1.2 User Guide
45 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
Response
DynamicEntityQueryResults
Faults
UnexpectedErrorFault
ValidationFault
InvalidTypeFault
QueryTooLargeFault
InvalidQueryFault
OperationTimeIntervalFault
Syntax
Sample Code - .NET
Note: .NET code sample concluded on next page.
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;
Eloqua® Web Services API v1.2 User Guide
46 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
Sample Code - .NET (continued)
// 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())); }
Eloqua® Web Services API v1.2 User Guide
47 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
Sample Code – Java
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()));
Eloqua® Web Services API v1.2 User Guide
48 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
Sample Code – Java (continued)
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()); }
Eloqua® Web Services API v1.2 User Guide
49 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
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
UnexpectedErrorFault
Syntax
Service instance;
ListAssetTypesResult returnValue;
returnValue = instance.ListAssetTypes();
Eloqua® Web Services API v1.2 User Guide
50 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
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.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()); }
Eloqua® Web Services API v1.2 User Guide
51 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
See Also
DescribeAssetType
WSDL Information
DescribeAssetType
Usage
Retrieve all the Assets in a given Asset Type.
Arguments
assetType (String)
Response
DescribeAssetTypeResult
Faults
UnexpectedErrorFault
ValidationFault
InvalidTypeFault
Syntax
Service instance;
String entityName;
DescribeAssetTypeResult returnValue;
returnValue = instance.DescribeAssetType(assetType);
Eloqua® Web Services API v1.2 User Guide
52 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
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())); }
Eloqua® Web Services API v1.2 User Guide
53 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
Sample Code – Java
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()); }
Eloqua® Web Services API v1.2 User Guide
54 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
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:
https://secure.eloqua.com/API/1.2/DataTransferService.svc?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.
Eloqua® Web Services API v1.2 User Guide
55 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
Arguments
AssetType
Response
DataExportExecution
Faults
UnexpectedErrorFault
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())); }
Eloqua® Web Services API v1.2 User Guide
56 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
Sample Code – Java
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()); }
Eloqua® Web Services API v1.2 User Guide
57 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
DataExportStatus
Usage
Retrieve the status of a Data Export execution.
Arguments
AssetType
Response
DataExportExecutionStatus
Faults
UnexpectedErrorFault
ValidationFault
Syntax
Service instance;
AssetType assetType;
DataExportExecutionStatus returnValue;
returnValue = instance.DataExportStatus(assetType);
Eloqua® Web Services API v1.2 User Guide
58 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
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())); }
Eloqua® Web Services API v1.2 User Guide
59 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
Sample Code – Java
See Also
InitializeDataExport
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()); }
Eloqua® Web Services API v1.2 User Guide
60 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
Response
Byte[]
Faults
UnexpectedErrorFault
ValidationFault
Syntax
Service instance;
AssetType assetType;
Byte[] returnValue;
returnValue = instance.GetDataExportFile(assetType);
Eloqua® Web Services API v1.2 User Guide
61 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
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())); }
Eloqua® Web Services API v1.2 User Guide
62 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
Sample Code – Java
See Also
InitializeDataExport
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()); }
Eloqua® Web Services API v1.2 User Guide
63 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
DATA IMPORT OPERATIONS
The following Data Import operations are available:
InitializeDataImport
Usage
Initialize a Data Import.
Arguments
Byte[]
AssetType
DataSourceType
Response
DataImportExecution
Faults
UnexpectedErrorFault
ValidationFault
InvalidFileType
QueueLimitReachedFault
Syntax
Service instance;
Byte[] data;
AssetType assetType;
DataSourceType dataSourceType;
Byte[] returnValue;
returnValue = instance.InitializeDataImport(data, assetType,
dataSourceType);
Eloqua® Web Services API v1.2 User Guide
64 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
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())); }
Eloqua® Web Services API v1.2 User Guide
65 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
Sample Code – Java
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()); }
Eloqua® Web Services API v1.2 User Guide
66 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
See Also
DataImportStatus
WSDL Information
DataImportStatus
Usage
Check the status of a Data Import.
Arguments
AssetType
DataImportExecution
Response
DataImportExecutionStatus
Faults
UnexpectedErrorFault
ValidationFault
Syntax
Service instance;
AssetType assetType;
DataImportExecution dataImportExecution;
DataImportExecutionStatus returnValue;
returnValue = instance.DataImportStatus(assetType, dataImportExecution);
Eloqua® Web Services API v1.2 User Guide
67 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
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())); }
Eloqua® Web Services API v1.2 User Guide
68 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
Sample Code – Java
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()); }
Eloqua® Web Services API v1.2 User Guide
69 866 327 8764 · www.eloqua.com © 2008-2014 Oracle Corporation
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.
top related