EloquaWebServicesAPI1.2DeveloperGuide

© 2008 Eloqua 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 DEVELOPER GUIDE WEB SERVICES API V1.2

VERSION 1.1

NOVEMBER 1, 2008

This page was intentionally left blank.

866 327 8764 · www.eloqua.com © 2008 Eloqua 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 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 ................................................................................................. 13 SCENARIO 2: SYNCHRONIZE LEAD/CONTACT DATA ............................................................ 16 CRM/ELOQUA DATA MODEL ...................................................................................................... 17 FIELD TYPES ................................................................................................................................ 18 SECURITY ..................................................................................................................................... 19 SYSTEM FIELDS ........................................................................................................................... 19

API Call Basics ................................................................................................... 19 API CALL CHARACTERISTICS ................................................................................................... 20

866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation

866 327 8764 · www.eloqua.com

ELOQUA IDENTIFICATION CODES ............................................................................................ 21

© 2008 Eloqua Corporation

ERROR HANDLING ...................................................................................................................... 20

Additional Considerations ................................................................................ 20 USAGE METERING....................................................................................................................... 20 COMPRESSION ............................................................................................................................ 21 INTERNATIONAL CHARACTERS ................................................................................................ 21

API Reference ..................................................................................................... 22 CODE SAMPLE CONVENTIONS ................................................................................................. 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 DESCRIBEASSET .................................................................................................................... 53

ASSET OPERATIONS................................................................................................................... 56 CREATEASSET ....................................................................................................................... 56 RETRIEVEASSET .................................................................................................................... 61 UPDATEASSET ....................................................................................................................... 65 DELETEASSET ........................................................................................................................ 69

GROUP MEMBERSHIP OPERATIONS ........................................................................................ 72 LISTGROUPMEMBERSHIP ..................................................................................................... 72 ADDGROUPMEMBER ............................................................................................................. 74 REMOVEGROUPMEMBER ..................................................................................................... 78

Data Transfer Service ........................................................................................ 81 DATA EXPORT OPERATIONS ..................................................................................................... 81

INITIALIZEDATAEXPORT ....................................................................................................... 82 DATAEXPORTSTATUS ........................................................................................................... 85 GETDATAEXPORTFILE .......................................................................................................... 87

DATA IMPORT OPERATIONS ..................................................................................................... 91 INITIALIZEDATAIMPORT ........................................................................................................ 91 DATAIMPORTSTATUS ............................................................................................................ 94

Errors................................................................................................................... 97

Conventions Used in This User Guide The following conventions are used in the Eloqua® Web Services API Phase 1 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

1 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation

http://www.eloqua.com/

Eloqua® Web Services API v1.2 Developer Guide

for this purpose. The abstract definition of ports and messages is separated from their concrete use or instance, allowing the reuse of these definitions.

• Simple Object Access Protocol (SOAP)—SOAP is a protocol for exchanging XML-based messages over computer networks, normally using HTTP/HTTPS. SOAP forms the foundation layer of the web services protocol stack by providing a basic messaging framework upon which abstract layers can be built. Web services messages are sent between the customer implementation of Web services and the SOAP handler on the Eloqua web server.

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

Possible Uses of the API The Web Services API allows companies to build programs to integrate with Eloqua. Some examples of web services integrations include the following:

• Integration between Eloqua and CRM System—You can create a connector that polls Eloqua on a regular basis for new marketing activities and Contact record changes and updates your CRM system from Eloqua. For example, instead of using flat file batch transfers for integrating Eloqua with your CRM system, you can now have near real-time updates between your systems. In addition, your CRM system can call out to Eloqua and update information in your marketing database.

• Updating Data Warehouses for analytics—Using the Eloqua Data Export service, you can now export historical transactional data about website activity, Form submissions, Email activity, and other details for analysis on a regular basis.

• Connectors to External Web Services—By creating a polling connector service that Polls Eloqua for certain actions or activities, you can trigger a web services call to another service that may append data or begin a secondary process in another system using data passed over from Eloqua.

Eloqua API The Eloqua Web Services API is intended to provide the ability for developers to easily integrate their existing systems to the Eloqua platform and leverage its rich data store to provide actionable marketing intelligence to the enterprise. To use this document and the Eloqua API, you need to have a good grasp of fundamental web programming techniques and tools. This document will serve as a guide to the Eloqua Web Services API, but does not function as an overall guide for Eloqua and its capabilities in general.

Note: Development platforms vary in their SOAP implementations. These differences may prevent access to some or all of the features in the API. We recommend that you use Visual Studio 2005 or higher if you are using Visual Studio for .NET development.

This first version of the API is focused on providing access to the primary data entities within Eloqua and allowing developers to Create, Update, Retrieve and Delete records programmatically, as well as allowing bulk export or import of large datasets. Future versions of the API will focus on performing actions and leveraging other capabilities such as management of Contact groups, Programs, and marketing activities.


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


SUPPORTED PLATFORMS

The Web Services API was designed using common web technologies that allow for interoperability between systems. Specifically, the API is directly supported within two primary technology stacks: .NET and Java. The API is SOAP-based and should be accessible from other platforms not listed here, but may require libraries or components to be installed that support the appropriate standards.

The API works with current SOAP development environments, including, but not limited to, Visual Studio .NET 2008, Eclipse using Apache Axis 2 + Rampart, and NetBeans 6 using the WSIT libraries. In this document, we provide examples in Java and .NET. The Java examples are created in NetBeans 6.0.1 using the WSIT 1.1 libraries (See: https://wsit.dev.Java.net/).

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

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

STANDARD TECHNOLOGIES

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

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

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

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

ELOQUA API SUPPORT POLICY

Eloqua suggests that any applications being written using the API use the latest release version of the API. New functionality and enhanced performance will be included and supported only on new releases of the web services API. When a new version of the API is released, you will need to retrieve a new version of the WSDL to see the new functions and schemas.

Our technical support team can provide limited assistance with API development and are mainly focused on troubleshooting and resolving errors or investigating potential bugs within the API. They cannot provide any support or advice for programming logic nor assistance with creating programs that use the API.

RELATED RESOURCES

There are numerous web resources available for getting more familiar with Eloqua’s capabilities and functions. Below, we have listed some Eloqua-specific resources that are available to users of the application.

Eloqua Training Resources Once you have logged in to the application, click on the Training button in the top right-hand corner.

Eloqua Online Help When you are logged in, click Help in the upper right-hand corner to open the online Help system.


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

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

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

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

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

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

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


Eloqua Community Forums Go to eloquacommunity.com. Log in using your Eloqua password. There is a specific forum for API support and help.

END OF LIFE

The intention is to provide a fully backwards-compatible web services layer. However, if a change is required that would cause a loss of functionality, there would be a major API version release. Eloqua does not guarantee that an application written against one API version will work with future API versions: Changes in methods and data representations are often required to further enhance the functionality we provide. However, we make significant efforts to ensure that the API is consistent from version to version.

Getting Started The Section below is for getting a quick start with the Eloqua API and the basic steps needed to get your first Eloqua program up and running. This first demonstration program will show an example where a Form submission to a web page could be used to create a new Contact in Eloqua and return the new EntityID of the Contact.

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

STEP 1: REQUEST THE WEB SERVICES API INTEGRATION

For security reasons, the capability to use the API is not automatically enabled for all implementations of the Eloqua application. Upon request, your Customer Success Manager (CSM) will enable the Web Service Integration for your company.

STEP 2: OBTAIN COMPANY NAME, USERNAME, AND PASSWORD

In order to use the API, you need to get login information for the Eloqua system. There are three elements needed to log in to Eloqua: CompanyName, Username, and Password. Speak to the Eloqua administrator in your organization who can create a new user account. They will need to place the username that will be used for API calls into the security group called “API Users” in order for you to be able to access the system programmatically.

After receiving your new login from your administrator, you must log in to https://secure.eloqua.com in order to change the initially-assigned password. The password you specify will be used when authenticating using the API.

It is recommended that you use a distinct user for API operations when possible to avoid administrative hassles such as a user being disabled that was used for integration purposes.

STEP 3: RETRIEVE WSDL

To access the Eloqua Web service, you need a Web Service Description Language (WSDL) file. The WSDL file defines the Web service that is available to you. Your development platform uses this WSDL to generate an API to access the Eloqua Web service it defines.

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

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


https://secure.eloqua.com/


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

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

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

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

STEP 4: IMPORT WSDL

Once you have the WSDL file, you need to import it into your development platform so that your development environment can generate the necessary objects for use in building client Web service applications in that environment. This section provides sample instructions for Apache Axis (Java) and Microsoft Visual Studio. For instructions about other development platforms, see your platform’s product documentation.

FOR JAVA

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

To install NetBeans:

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

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

a. Web Services

b. Web Applications

c. WSDL

d. JAX-RPM Web Services

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

To create a new WSIT-enabled project:

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

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

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

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

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

To create the web service client:

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

2. Select WSDL URL and put the Eloqua wsdl URL in the textbox (https://secure.eloqua.com/API/1.2/Service.svc?wsdl).

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

4. Click Finish.



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

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

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



To set up authentication:

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

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

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

Username: CompanyName/UserName

Password: Password

FOR VISUAL STUDIO

Visual Studio languages access the API through objects that serve as proxies for their server-side counterparts. Before using the API, you must first generate these objects from your organization's WSDL file.

Visual Studio provides two approaches for importing your WSDL file and generating an XML Web service client: An IDE-based approach and a command-line approach.

Note: Before you begin, the first step is to create a new application or open an existing application in Visual Studio. In addition, you need to point to the WSDL files in Eloqua.

An XML Web service client is any component or application that references and uses an XML Web service. This does not necessarily need to be a client-based application. In fact, in many cases, your XML Web service clients might be other Web applications, such as Web Forms or even other XML Web services.

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

To access an XML web service from managed code:

Adding a reference to a .NET project is very straightforward. Follow the steps below: To add the Service Reference:

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

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

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

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

To set up Authentication:

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

C# Sample:

Suppose you called the service namespace EloquaService; the code to create a new instance of the proxy and setup authentication would look like:

EloquaService.EloquaServiceClient serviceProxy = new EloquaService.EloquaServiceClient();




serviceProxy.ClientCredentials.UserName.UserName = "Company\username"; serviceProxy.ClientCredentials.UserName.Password = "password";

STEP 5: WRITE THE CODE REQUIRED

Once you have completed the other steps, it’s time to write the code required to implement usage of the selected Eloqua web service. You can find specific code sample to help you do this in the API Reference beginning on page 22. The code samples are provided in both .NET and Java formats.

Eloqua Objects Overview The diagram below shows the relationships between the data entities in Eloqua. See the Entities section of the Object Model below for more information.

Object Model a API is separated into 3 main areas:

ces (DataExport and DataImport Functionality)

ENTITIES

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

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

The Eloqu

1. Entities

2. Assets

3. Data Servi

The Eloquatransactional records such as closed opportunities (ie: Data Cards) for list segmentation purposes. Sothese 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 “descri



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

it is

API. Note that some relationships tionship as the lookup tables are

from “Forms” as an Entity, but you could also configure how a Form operates or its properties becausealso 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:

sions

The diagram below indicates the entity relationships available through then the API (such as a Prospect-to-Visitor rela

• Contacts

• Prospects

• Companies

• Data Cards,

• Form Submis

• Visitors

• Object Relationships

ENTITY RELATIONSHIPS

may not currently be visible inot exposed via the API).

Company

CompanyID

M_DateCreatedM_CompanyNameM_DateModifiedCompanyIDExtM_StandardField1M_CustomField1

Contact

ContactID

VisitorIDC_DateCreatedC_DateModifiedC_EmailAddressContactIDExtProspectIDCompanyIDC_EmailAddressDomainC_StandardField1C_CustomField1 ProfileFieldData

VisitorID

CustomerGUIDDateCreatedDateEditedV_first_nameV_last_nameV_Total_VisitsV_IPAddressLastPollV_Total_PagesVisitorEntityTypeIDEntityIDCompanyIDV_StandardField1V_CustomField1ProspectIDDataCardID

Prospect

ProspectID

P_DateCreatedP_EmailAddressP_FirstNameP_LastNameCompanyIDContactID

VisitorCompanyMap

CompanyIDVisitorID

VisitorProspectMap

ProspectIDVisitorID

DataCard

DataCardID

DataCardNameDataCardSetDataCardStatusUniqueCodeSalesProcessEntityTypeSalesProcessEntityDataCardIDExtDateCreatedDateModifiedDateCompletedDataImportExecutionIDVisitorID

DataCardFieldValue

DataCardFieldValueID

DataCardDataCardFieldStringValueIntegerValueTextValueDataImportSourceIDDateTimeValueNumericValue

Form Data

FormSubmitID

InternalQueue

InternalQueueID

DateSubmittedVisitorIDCustomField1StandardField1

ExternalIDDateEmailAddressPriorityStatusOwnerSubjectTypeEntityID



ENTITY METADATA

The web service contains operations for discovering all the entities in the system as well as the metadata information for each entity. The following operations are available:

Entity Metadata operations:

• ListEntityTypes() Retrieve all the entity types in your Eloqua database. This includes the Base type that contains the Contact and Company entities. Only types available in the instance of Eloqua which you are logged into are returned. Your application can parse the response and query for further information such as the metadata for each Entity type.

• DescribeEntityTypes() Retrieve all the entities in a given Entity Type. For example: Contacts, Companies and Prospects are entities contained in the Base Entity Type.

• DescribeEntity() Retrieve all the metadata for a specific Entity. The information returned also contains access permissions on the entity (Readable, Createable, etc…)

Entity Metadata Diagram



ENTITY - GLOBAL TYPES

Base Objects are used to store data about marketing contacts and their related entities. These primary (Base) objects include: Contacts, Prospects and Companies, Visitors and Processed Activity.

Eloqua Global Types (ListEntityTypes)

Base This type includes the 3 main Eloqua entities: Contact, Company and Prospect. These entity types can be further described to identify the metadata available (such as Field Names) and actions available.

DataCardSet DataCardSets is an entity that may have its own data model customization (customized fields per set) and store many records that are related to a single Contact record. This entity type will return a list of all the Data Card sets in the current instance.

Forms Forms is a repository of all the Form submission data that is captured by the Eloqua Form Processing engine before it is recorded into a Contact record and processed. In the Eloqua interface, this data is equivalent to opening the Form’s “Form Data Submission Report.”

BASE ENTITY TYPES

With Eloqua, built around a marketing-oriented database, there are primary or “Base” Data Objects (including Contacts, Prospects, and Companies) that are used within the system to store data about marketing contacts and their related entities.

Eloqua Base Entity Types (DescribeEntityTypes:Base)

Contacts Contacts are the most frequently used entity in the Eloqua system. A Contact record typically represents a person that is either a customer or prospecaddress. In Eloqua, the Contact table uses email as a unique ide prevent duplicate Contacts from having the same email address.

t who has an email ntifier to

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

They can be converted into a Contact record through Program Builder when they acquire an email address. have an email address.

Companies ct as a parent record to Contacts and Prospects who

can be linked to a Company record. A typical Company record would contain

Company records in Eloqua (sometimes referred to as Accounts in CRM systems) represent an organization and a

information about the Company name, annual revenue, trading symbol, etc.

Visitors recorded visitor to your tracked website pages. Each record contains information such Visitor records (sometimes referred to as ‘Visitor Profiles’) are the container for each

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

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

marketing activities into your CRM system. Your system will poll the marketing

stem d record. You need to request Processed Activity to

nce. Speak to your CSM.

This object represents

writeactivities table for any new records since the last check—the values returned willinclude 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 sythat are related to the Contact/Leabe turned on for a particular Eloqua insta

A

Assets are abstrac mport settings (AutoSync at are currently only accessible within the UI of the Eloqua platform. Assets are the tools that are used to make your marketing application d g: Senmappings, Data ExDataExport Setting

ASSET METADATA

T e coinformation for eac

Asset Metadata o

• setTypRetrieve all the Awhich you are lo

• DescribeAsseRetrieve all the A

Asset Metadata Diagram

SSETS

t representations of structured data in Eloqua, such as an Email Brochure or Data Ih). Eventually, the API will begin to include other Assets th

o soemthin d Emails, edit Email content, create Hypersites™, add to Programs, Data Import port settings and many others. In this current version of the API, only DataImport and s are available as Assets.

he web servic ntains operations for discovering all the assets in the system as well as the metadata h asset. The following operations are available:

perations:

ListAs es() sset Types in your Eloqua database. Only Types available in the instance of Eloqua

gged into are returned. tType() ssets in a given Asset Type.



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

wn particular data needs. Speak to your Account Manager for more details. Eloqua

Connect integration engine, and our new

uch as Salesforce.com®, Oracle® CRM OnDemand, Microsoft ® Dynamics

hat you wish to connect with Eloqua, you will likely need to s the bridge between your CRM system and Eloqua using the API. The Eloqua

API has been designed to allow for regular polling by your CRM connector system to find newly updated records or recently executed marketing activities.

There are three main components of data that are typically synchronized or exchanged between Eloqua and a CRM or ERP program. Not all components are required as part of an integration:

1. Marketing Activity Data

Regular marketing activities such as Email Opens, click-throughs, unsubscribes, bouncebacks, website visits, and Form submissions are typically made available to the CRM system and are sent with the related Lead/Contact record ID so that a record can be created in the CRM that records the relationship. These activities can be used for reporting (for example, to relate activities and closed opportunities).

2. New or Updated Lead/Contact Data

a. Outbound Data from Eloqua - As website visitors submit Forms, these will update/create the Contact records in Eloqua based on the email address that is supplied with the Form submission. These

am” within Eloqua that may score or dictate how a record is m (for example, should a record be passed to CRM only after it

is

aign Associations

e

nts.

integrating with your osupports 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 DirectAPI.

For hosted CRM systems sCRM 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 tbuild a connector that acts a

records should also be pushed into a “Progrhandled after submission into the systeis 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 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. Camp

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 includcreating basic ROI or influenced revenue reports within your CRM system, depending on your data requireme

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

e, so you must poll Eloqua actively to pull down Events from the queue.

It isrecoConupd

TEGRATION

In a lled the opepollesyst service will need to match a record in your CRM to update using the related recoProc

period of two weeks.

directly to an endpoint on your sid

important that the Eloqua Entity ID is stored within your CRM system as part of the Contact or Lead rd as it is needed to perform API calls efficiently back to Eloqua. While Eloqua matches records in the tact table based on email address, the API requires the Entity ID to be used in API calls such as ating a Contact record in Eloqua when a record change occurs within your CRM system.

SCENARIO 1: MARKETING ACTIVITY IN

scenario where Marketing activities must be passed over to your CRM system, there is a facility ca“Processed Activity Queue” that collects recently-triggered Eloqua marketing activities (such as Email ns, website visits, form submissions,etc.) by Contacts within the Eloqua database. These activities are d by your code on a reguar basis and created as a records related to the Contact or Lead in your CRM

em or database. Your webrds. It is possible to map your system’s Foreign Contact/Lead ID to each activity that is placed in the essed Activity Queue for easy mapping to the record in your CRM.

PROCESSED ACTIVITY QUEUE

The Processed Activity Queue is enabled by request by your Customer Success Manager for your Eloqua instance. Processed Activity is not available if you have Instead of writing them to an external CRM system as usual, you can direct these activities to be written to the Processed Activity Table (Part of the BASE entity), which is accessible via the API and will store these records for a



Before using this function, you must create an External API call that is mapped to the appropriate fields in the Processed Activity Queue by creating a new External Call in the Outbound tab in the Integration area.

Note: Eloqua Internal will only be visible if it has been enabled for your instance of Eloqua and you have Customer Administrator security rights. It is not available if you already have an integration using DirectConnect to Salesforce.com®, Oracle® CRM OnDemand, Microsoft ® Dynamics CRM 4.0, and

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.

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:



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

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



SCENARIO 2: SYNCHRONIZE LEAD/CONTACT DATA

d match incoming ests, 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.

It is critical that you sit down and evaluate the needs of the sales and marketing teams regarding what information must be exchanged between the two systems. Sales teams are generally interested in receiving information about marketing activities and lead scores, while the marketing team will generally have an interest in leveraging segmentation data contained within the CRM to create targeted marketing campaigns.

In a typical marketing database scenario, Eloqua is used as a centralized place to store anrequ



In the diagram above, note that new Form submissions create Lead record 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 tacts with no email address associated to them.

or series of records. Each Data Card set d set

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:

s

are not deduplicated and generally represent Leads or ConProspects 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 has it’s own fields and settings. For example, Data Card Set A may have only three fields, but Data CarB has 20 fields. A Data Card set contains many Data Cards that may be linked to a Contact record.

Data Cards—A Data Card is the record that stores a transaction such such as an Event registration by aContact, or a purchase history record (opportunities). Each Data Card may or may not be linked to a Contact record.



• 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

r

ever, 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 the API, values will not be checked against the picklist values that have

on of

The Field Types in Eloqua are configurable by the Customer Administrator and have certain attributes set foeach. The field types such as Picklist, Multi-select, and Text, are generally used to represent data within theEloqua UI. How

stored. When communicating viabeen configured in the User Interface.

Multiselect fields allow up to 1000 characters to be stored and use double full colons (::) as a delimiter when parsing values to be displayed in the Eloqua UI. These delimiters are converted on external API calls according to the target system.

Large Text Fields are specially designated fields that can contain up to 32K of text. However, in this version of the API, Large Text Fields are not accessible through the API and are not shown in the the descriptiany 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




the value that will automatically populate a record upon creation in

es whether a field can be written or updated via the API.

h the y bar an

e if desired.

nel on port 443. These communications are ure Sockets Layer (SSL) for security (minimum 128-bit).

d requires authentication for each API call that is sent using a valid username and security group that grants access to the API (WS-Security 1.0).

ccess capabilities that apply to users in Eloqua are applied to users

SYSTEM FIELDS

e 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.

(retrieve calls) (query limit up to 2000 records)

Default Value is a string that indicates 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 theuser and is not a system generated field.

Writeable is a Boolean value which indicat

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 througAPI. In this manner the Eloqua Security model remains the same and security groups can effectivelAPI user from logging in via the User Interfac

Eloqua’s API security framework includes the following:

• API calls will only encrypted with Sec

be accepted through a secure HTTPS chan

• Access is stateless, anpassword that has been placed into a

• The same data visibility and aconnected through the Web services interface. Data visibility and access are restricted by the security groups and asset based security. Permissions are checked for every data access.

• Eloqua employs a variety of security measures and techniques to secure our production network and infrastructure. These same precautions are used for our API infrastructure. These solutions are regularly reviewed and improved as new technologies and techniques become available.

Several fields ar

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

• 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)

est and returns a response, and the ndles the response.

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

rds in ts.

r le, 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.

• 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 requclient application ha

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

• Limited in Length for the results—The return results from queries/retrieve are limited to 2000 recopages of 20 items. The Bulk Data Transfer service can be used for larger record se

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

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

malformed message. Service interruptions and regular maintenance times will return a message indicating our application should be able to use the return message to handle the error and either re-try or

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

that status. Ylog 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

rganizations’ use of of

• 24 hour limit on API calls—As follows:

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 oserver-side resources to equitably share available resources among users and to minimize the possibilitydenial-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:



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

n

Limit—Under some circumstances, a server can be flooded with concurrent logins. ion limiters that constrain the number of sessions an organization can have open at

e—All integration requests (data exchange requests) in a session are subject to rate limiting. g reasons:

long running

cond that clients can make. The rate limit is set to 1 re often than once per second to

• Request Size Limit—The upper limit on the size of any incoming HTTP request is 1MB. or return messages, the maximum number of records returned for each

u exceed the threshold of 2000 records as a result of your query, you will an

d HTTP stream.

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

v

TION CODES

ach tuation

> 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 o

load conditions. • Number of Sessions

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

• Request RatRate limiting is implemented for the followin> A user can perform long-running operations on the server that result in complex and

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 serequest every 1 seconds for QUERY calls. Other calls are allowed moa reasonable level.

> InitializeDataExport for data export functions are limited to run every 5 seconds – but generally should not be run on a rapid interval.

• Maximum Records Returned—Fquery is limited to 2000. If yoreceive an error (with no records returned) and will need to restrict it further so that it returns fewer th2000 results(ie: add a condition to limit the set). If you need a larger record set than 2000 records, you will need to perform a bulk data export function which will require you to parse an exported binary file through the SOAP API.

COMPRESSION

HTTP Header compression is used for all outgoing traffic and should be supported by your development environment as this can substantially improve performance versus using an uncompresse

INTERNATIONAL CHARACTERS

Eloqua’s SOAP encoding allows for UTF-8 character encoding to be passed infullalues in their original encoding.

ELOQUA IDENTIFICA

Eloqua uses a series of unique IDs for each record in the system that is generated server-side for eunique record. The API calls use these ID’s exclusively for executing their functionality. If there is a siwhere 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 wused for all up

ill be date sto the Eloqua database.

In order to meet the conventions used in the code samples, the WSDL files must be imported into the IDE ckages/namespaces:

API Reference

CODE SAMPLE CONVENTIONS

using the following pa

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

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

METADATA

The metadata that describes the attributes through describe calls. These methods allo

and properties of objects in your Eloqua database is accessible w you to discover information about Entities and Assets in your

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

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 canName.

The web service contains operations for discovering all the entities and entity types in the system as well as the metadata information for each entity. The following operations are available:



ENTITY METADATA OPERATIONS

Usage

loqua database. This includes the Base type that contains the Contact

ListEntityTypes

Retrieve all the entity types in your Eand 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 instanListEntityType

ce; sResult returnValue;

returnValue = instance.ListEntityTypes();



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.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()));

at("Fault Type: {0}", ex.GetType().ToString())); at("Fault Code: {0}", ex.Code.Name.ToString()));

Customize your own Error handling code.

Console.WriteLine(String.Form Console.WriteLine(String.Form} catch (Exception ex) { // Console.WriteLine(String.Format("Exception Message: {0}", ex.Message.ToString())); }

Sample Code – Java

try { // Set up the Eloqua API Service

uaService.Eloqua eloquaService = new EloquaService.Eloqua(); EloquaService.EloquaService service = eloquaService.getEloquaService();

TypesResult result = service.listEntityTypes();

Extract the name of each Entity Type : result.getEntityTypes().getValue().getString())

System.out.println(entityType);

ssage())); 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()); }

Eloq // Execute the request EloquaService.ListEntity // for (String entityType { }} catch (javax.xml.ws.soap.SOAPFaultException ex) { // Customize your own Error handling code. System.out.println(String.format("Message: %s", ex.getMe



See Also

DescribeEntityType DescribeEntity WSDL Information

DU

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

AentityType (String)

RD

FUValidationFault I

S

escribeEntityType sage

re entities contained in the Base Entity Type.

rguments

esponse escribeEntityTypeResult

aults nexpectedErrorFault

nvalidTypeFault

yntax

Service instance; String entityName;

yTypeResult returnValue;

DescribeEntitreturnValue = instance.DescribeEntityType(entityType);



Sample Code - .NET

S

try { // Set up th EloquaServic

e Eloqua API Service e.EloquaServiceClient service = new EloquaService.EloquaServiceClient();

Name.UserName = "Company\\default.user"; Name.Password = "test123";

uaService.DescribeEntityTypeResult result = service.DescribeEntityType("Base");

ityType in result.EntityTypes)

sole.WriteLine(String.Format("ID: {0}", entityType.ID)); e(String.Format("Type: {0}", entityType.Type));

String.Format("Name: {0}", entityType.Name));

tException ex)

Customize your own Error handling code. ng.Format("Reson: {0}", ex.Reason.ToString())); ng.Format("Fault Type: {0}", ex.GetType().ToString())); ng.Format("Fault Code: {0}", ex.Code.Name.ToString()));

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

service.ClientCredentials.User service.ClientCredentials.User // Execute the request Eloq // Extract the ID, Name and Type of each Entity in the Base Type foreach (EloquaService.EntityType ent { Con Console.WriteLin Console.WriteLine( } } catch (System.ServiceModel.Faul{ // Console.WriteLine(Stri Console.WriteLine(Stri Console.WriteLine(Stri} catch (Exception ex) { // Console.WriteLine(Str}

ample Code – Java

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



See Also

DescribeEntity ListEntityTypes WSDL Information

DU

R tains access permissions on th

Ae

Response DescribeEntityResult

FUVInvalidTypeFault

S

escribeEntity sage

etrieve all the metadata for a specific Entity. The information returned also cone entity (Readable, Createable, etc…)

rguments ntityType (EntityType)

aults nexpectedErrorFault alidationFault

yntax

Service instance; EntityType entityType; DescribeEntityResult returnValue;

instance.DescribeEntity (entityType); returnValue =



Sample Code - .NET

try { // Set up th EloquaServic

e Eloqua API Service e.EloquaServiceClient service = new EloquaService.EloquaServiceClient();

als.UserName.UserName = "Company\\default.user"; als.UserName.Password = "test123";

Define a Contact Entity Type object uaService.EntityType entityType = new EloquaService.EntityType();

tyResult result = service.DescribeEntity(entityType);

xtract the Entity's Name ng.Format("Entity Name: {0}", result.Name));

Extract the Entity's Properties ng.Format("Is Createable: {0}", result.IsCreateable)); ng.Format("Is Deletable: {0}", result.IsDeletable)); ng.Format("Is Queryable: {0}", result.IsQueryable));

(String.Format("Is Retrievable: {0}", result.IsRetrievable)); (String.Format("Is Updateable: {0}", result.IsUpdateable));

Extract the Entity's Field Metadata e.DynamicEntityFieldDefinition fieldDef in result.Fields)

ype: {0}", fieldDef.DataType)); DefaultValue)); isplayName));

ternalName)); 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())); }

service.ClientCredenti service.ClientCredenti // Eloq entityType.ID = 0; entityType.Name = "Contact"; entityType.Type = "Base"; // Execute the request EloquaService.DescribeEnti // E Console.WriteLine(Stri // Console.WriteLine(Stri Console.WriteLine(Stri Console.WriteLine(Stri Console.WriteLine Console.WriteLine // foreach (EloquaServic { Console.WriteLine(String.Format("Data T Console.WriteLine(String.Format("Default Value: {0}", fieldDef. Console.WriteLine(String.Format("Display Name: {0}", fieldDef.D Console.WriteLine(String.Format("Internal Name: {0}", fieldDef.In




See Also

DescribeEntityType

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

= new EloquaService.ObjectFactory();

Entity Type object yType = new EloquaService.EntityType();

entityType.setName(serviceFactory.createEntityTypeName("Contact")); ceFactory.createEntityTypeType("Base"));

// Execute the request sult result = service.describeEntity(entityType);

// Extract the Entity's Properties Createable: %s", result.isIsCreateable()));

; ); e()));

EloquaService.ObjectFactory serviceFactory // Define a Contact EloquaService.EntityType entit entityType.setID(0); entityType.setType(servi EloquaService.DescribeEntityRe System.out.println(String.format("Is 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.isIsRetrievabl System.out.println(String.format("Is Updateable: %s", result.isIsUpdateable())); // Extract the Entity's Field Metadata

tion fieldDef :

.value()));

om())); System.out.println(String.format("Is Required: %s", fieldDef.isIsRequired()));

System.out.println(String.format("Is Writeable: %s", fieldDef.isIsWriteable())); h: %s", String.valueOf(fieldDef.getLength())));

}

System.out.println(String.format("Message: %s", ex.getMessage())); String.format("Fault Code: %s", ex.getFault().getFaultCode()));

for (EloquaService.DynamicEntityFieldDefiniresult.getFields().getValue().getDynamicEntityFieldDefinition()) { System.out.println(String.format("Data Type: %s", fieldDef.getDataType() 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.isIsCust System.out.println(String.format("Lengt } catch (javax.xml.ws.soap.SOAPFaultException ex) { // Customize your own Error handling code. System.out.println(} catch (Exception ex) { // Customize your own Error handling code. System.out.println(ex.getMessage()); }

ListEntityTypes WSDL Information



ENTITY OPERATIONS

T ction describes the operations that can be performed to retrieve and change an Entity’s data using the API. W mportant to use the Eloqua ID of the object you are attempting to itor Profiles and Forms are re

CU

C

Ad

RC

FUVIBatchSizeExceededFault

S

his sehen performing an operation it is i

modify or delete. The following operations are available for most Entities (Visad-only):

reate sage

reate one or more new Entities in the Eloqua database.

rguments ynamicEntity[]

esponse reateResult[]

aults nexpectedErrorFault alidationFault nvalidTypeFault

yntax

Service instance; DynamicEntity[] dynamicEntities; CreateResult[] returnValue;

stance.Create(dynamicEntities); returnValue = in



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 Eloq aService.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();

the Contact's Email Address field to the Dynamic Entity’s field collection Entities[0].FieldValueCollection.Add("C_EmailAddress", "[email protected]");

namic Entity’s field collection irstName", "Support");

ute the request

eateResult[] result = service.Create(dynamicEntities);

erify the status of each Contact Create request in the results i < result.Length; i++)

l requests return a positive integer value for ID if (result[i].ID != ‐1)

ine("Success");

urn a ‐1 integer value for ID

Console.WriteLine("Failure"); e Error Message and Error Code for each failed Create request

Error in result[i].Errors)

t("Code: {0}", createError.ErrorCode)); eError.Message));

} } } catch (System.ServiceModel.FaultException ex)

u

// Add dynamic // Add the Contact's First Name field to the Dy dynamicEntities[0].FieldValueCollection.Add("C_F

// Exec EloquaService.Cr // V for (int i = 0; { // Successful { Console.WriteL } // Failed requests ret else

{ // Extract th foreach (EloquaService.Error create {

ng.Forma Console.WriteLine(Stri Console.WriteLine(String.Format("Message: {0}", creat }



Sample Code - .NET (continued)

S

{ // Customize your own Error handling code.

eson: {0}", ex.Reason.ToString()));

()));

(Exception ex)

ring.Format("Exception Message: {0}", ex.Message.ToString()));

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

ample Code – Java

try { // Set up the Eloqua API Service EloquaService.Eloqua eloquaService = new Eloq

oquaService.EloquaService service = eloquaSeuaService.Eloqua(); rvice.getEloquaService();

oquaService.ObjectFactory serviceFactory = new EloquaService.ObjectFactory();

oquaService.EntityType entityType = new EloquaService.EntityType();

tityType.setType(serviceFactory.createEntityTypeType("Base"));

EloquaService.ArrayOfDynamicEntity dynamicEntities = new EloquaService.ArrayOfDynamicEntity();

to the Array of Entities quaService.DynamicEntity dynamicEntity = new EloquaService.DynamicEntity();

pe));

te a Dynamic Entity's Field Value Collection ValueCollection = new

ce.DynamicEntityFields(); elds();

the Contact's Email Address field to the Dynamic Entity’s field collection yFields emailField =

Contact's First Name field to the Dynamic Entity’s field collection ervice.DynamicEntityFields.EntityFields firstNameField =

Factory.createDynamicEntityFieldsEntityFields(); firstNameField.setInternalName("C_FirstName"); firstNameField.setValue("Support");

firstNameField);

El // Instantiate a new Eloqua Service object factory El // Define a Contact Entity Type object El entityType.setID(0); entityType.setName(serviceFactory.createEntityTypeName("Contact")); en // Create a new Array of Dynamic Entities // Create a new Dynamic Entity and add it Elo dynamicEntity.setEntityType(serviceFactory.createEntityType(entityTy // Crea EloquaService.DynamicEntityFields fieldEloquaServi fieldValueCollection = serviceFactory.createDynamicEntityFi // Add EloquaService.DynamicEntityFields.EntitserviceFactory.createDynamicEntityFieldsEntityFields(); emailField.setInternalName("C_EmailAddress");

setValue("[email protected]"); emailField. fieldValueCollection.getEntityFields().add(emailField); // Add the EloquaSservice fieldValueCollection.getEntityFields().add(

Note: Java code sample concluded on next page.



Sample Code – Java (continued)

S

R

ee Also

etrieve Update

eleteD Query WSDL Information

// Add the Dynamic Fields to the Dynamic Entitiy > fc;

ollection); JAXBElement<EloquaService.DynamicEntityFields fc = serviceFactory.createDynamicEntityFieldValueCollection(fieldValueC dynamicEntity.setFieldValueCollection(fc); // Add the Dynamic Entity (Contact) to the Array of Dynamic Entities

ynamicEntity().add(dynamicEntity);

// 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)

{

else

Error Code for each failed Create request

et(i).getErrors().getValue().getError())

System.out.println(createError.getMessage().getValue());

}

dynamicEntities.getD // Execute the request EloquaService.ArrayOfCreateResult result = service.create(dynamicEntities);

{ System.out.println("Success"); } // Failed requests return a ‐1 integer value for ID { System.out.println("Failure"); // Extract the Error Message and for (EloquaService.Error createError : result.getCreateResult().g { System.out.println(createError.getErrorCode().value()); } } } catch (javax.xml.ws.soap.SOAPFaultException ex) {

ssage())); getFaultCode()));

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



Retrieve U

R

A ments Eid[] (Integer) S

R R

FUValidationFault IBatchSizeExceededFault

S

sage

etrieve one or more Entities from the Eloqua database.

rguntityType

tring[] fieldList

esponseetrieveResult[]


nvalidTypeFault

yntax

Service instance; EntityType entityType; int[] ids; String[] fieldList; DynamicEntity[] returnValue;

List); returnValue = instance.Retrieve(entityType, ids, field



Sample Code - .NET


try { // Set up the Eloqua API Service EloquaService.EloquaServiceClient service = new EloquaService.EloquaServiceClient();

.ClientCredentials.UserName.UserName = "Company\\default.user"; lientCredentials.UserName.Password = "test123";

tity Type object Type entityType = new EloquaService.EntityType();

tyType.ID = 0; tyType.Name = "Contact";

"Base";

Set the ID of the Contact Entity ;

ist containing the fields you want populated new List<string>();

Add the Contact’s Email Address to the field list dList.Add("C_EmailAddress");

e to the field list

e the results vedEntities;

// 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)

service service.C // Build a Contact En EloquaService.Entity enti enti entityType.Type = // int[] ids = new int[1] ids[0] = 1200846; // Create a new l List<string> fieldList = // fiel // Add the Contact’s First Nam fieldList.Add("C_FirstName"); // Build a Dynamic Entity array to stor EloquaService.DynamicEntity[] retrie // If the field list is empty ‐ the request will return all Entity Fields




S



()));

tch (Exception ex)


Console.WriteLine(String.Format("R Console.WriteLine(String.Format("Fault Type: {0}", ex.GetType().ToString())); Console.WriteLine(String.Format("Fault Code: {0}", ex.Code.Name.ToString} ca{ // Customize your own Error handling code. Console.WriteLine(St}

ample Code – Java


aService.Eloqua(); EloquaService.Eloqua eloquaService = new Eloqu EloquaService.EloquaService service = eloquaSe

rvice.getEloquaService();

ceFactory = new EloquaService.ObjectFactory();

yType = new EloquaService.EntityType();

"Contact")); pe("Base"));

this Entity string();

d the Contact’s Email Address to the field list

dList.getString().add("C_FirstName");

retrievedEntities;

// Execute the request and return only the selected Entity fields retrievedEntities = service.retrieve(entityType, ids, fieldList);

object factory // Instantiate a new Eloqua Service EloquaService.ObjectFactory servi

object // Build a Contact Entity Type

EloquaService.EntityType entit entityType.setID(0);

Name( entityType.setName(serviceFactory.createEntityType entityType.setType(serviceFactory.createEntityTypeTy

// Set the ID of the Contact Entity

s = new EloquaService.ArrayOfint(); EloquaService.ArrayOfint id.getInt().add(1200846); ids

// Create a new array containing the fields you want populated for

quaService.ArrayOfstring fieldList = new EloquaService.ArrayOf Elo

Ad // fieldList.getString().add("C_EmailAddress");

Add the Contact’s First Name to the field list // fiel

store the results // Build a Dynamic Entity array to

quaService.ArrayOfDynamicEntity Elo

e field array is empty ‐ the request will return all Entity Fields // If th // 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 {

}





S

C

ee Also

reate Update Delete Query WSDL Information

UU

U one or more Entities in the Eloqua database.

Ad

RUpdateResult[]

FUnexpectedErrorFault ValidationFault IB

pdate sage

pdate

rguments ynamicEntity[]

esponse

aults

nvalidTypeFault atchSizeExceededFault

// If a result was found, extract the field values for each Dynamic Entity ) > 0)

ntity())

// Extract the Field Name and Value for each element in the collection ervice.DynamicEntityFields.EntityFields field :

amicEntity.getFieldValueCollection().getValue().getEntityFields())

())); System.out.println(String.format("Field Value: %s", field.getValue()));

}

(javax.xml.ws.soap.SOAPFaultException ex)

ode()));

if (retrievedEntities.getDynamicEntity().size( { for (EloquaService.DynamicEntity dynamicEntity : retrievedEntities.getDynamicE { for (EloquaSdyn { System.out.println(String.format("Field Name: %s", field.getInternalName

} } } catch{ // 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().getFaultC} catch (Exception ex) { ng code. // Customize your own Error handli System.out.println(ex.getMessage()); }



Syntax

S

le concluded on next page.

Service instance; DynamicEntity[] dynamicEntities; UpdateResult[] returnValue;

returnValue = instance.Update(dynamicEntities);

ample Code - .NET


quaService.EloquaServiceClient service = new EloquaService.EloquaServiceClient(); = "Company\\default.user"; "test123";

"Contact"; "Base";

es = 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 namicEntities[0].EntityType = entityType;

Set the Contact record's ID namicEntities[0].Id = 1;

Dynamic Entity's Field Value Collection es[0].FieldValueCollection = new EloquaService.DynamicEntityFields();

he Contact's Email Address to the Dynamic Entity's field collection tities[0].FieldValueCollection.Add("C_EmailAddress", "[email protected]");

mic Entity's field collection ("C_FirstName", "Support");

ute the request dateResult[] result = service.Update(dynamicEntities);

Elo service.ClientCredentials.UserName.UserName service.ClientCredentials.UserName.Password = // Build a Contact Entity Type object EloquaService.EntityType entityType = new EloquaService.EntityType(); entityType.ID = 0; entityType.Name = entityType.Type = // Create a new Array of Dynamic Entities EloquaService.DynamicEntity[] dynamicEntiti

// dy // dy // Create a dynamicEntiti // Add t dynamicEn // Add the Contact's First Name to the Dyna dynamicEntities[0].FieldValueCollection.Add // Exec EloquaService.Up

Note: code samp .NET




S

ote: Java code sample continued on next page.

// Verify the status for (int i = 0; i < result.Length; i++)

of each Contact Update request in the results

r ID

Console.WriteLine("Success"); }

requests return a ‐1 integer value for ID

{ Console.WriteLine("Failure");

updateError.ErrorCode)); rmat("Message: {0}", updateError.Message));

ltException ex)

ring())); ing()));

{ // Successfull requests return a positive integer value fo if (result[i].ID != ‐1) {

// Failed else

// 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}",

Console.WriteLine(String.Fo } } } } tch (System.ServiceModel.Fauca

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

Console.WriteLine(String.Format("Fault Type: {0}", ex.GetType().ToStName.ToStr Console.WriteLine(String.Format("Fault Code: {0}", ex.Code.

} catch (Exception ex) {

// Customize your own Error handling co de. mat("Exception Message: {0}", ex.Message.ToString())); Console.WriteLine(String.For

}

ample Code – Java


qua Service object factory tory();

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();

EloquaService.Eloqua eloquaService = new EloquaService.Eloqua(); EloquaService.EloquaService service = eloquaService.getEloquaService(); // Instantiate a new Elo EloquaService.ObjectFactory serviceFactory = new EloquaService.ObjectFac // Define a Contact Entity Type object EloquaService.EntityType entityType = new

N




Note: Java code sample conclued on next page.

// Instantiate a new Dynamic Entity and set it’s ID EloquaService.DynamicEntity dynamicEntity = new EloquaService.DynamicEntity();

amicEntity.setId(1); pe));

te a Dynamic Entity's Field Value Collection ValueCollection = new

ce.DynamicEntityFields(); elds();

the Contact's Email Address to the Dynamic Entity's field collection yFields emailField =

rviceFactory.createDynamicEntityFieldsEntityFields();

ollection.getEntityFields().add(emailField);

ce.DynamicEntityFields.EntityFields firstNameField = ory.createDynamicEntityFieldsEntityFields();

stNameField.setInternalName("C_FirstName"); firstNameField.setValue("Support");

firstNameField);

mic Entitiy's field collection

Entity (Contact) to the Array of Dynamic Entities dynamicEntities.getDynamicEntity().add(dynamicEntity);

EloquaService.ArrayOfUpdateResult result = service.update(dynamicEntities);

// Verify the status of each Contact Update request in the results 0; i < result.getUpdateResult().size(); i++)

// Successfull requests return a positive integer value for ID if (result.getUpdateResult().get(i).getID() != ‐1)

// Failed requests return a ‐1 integer value for ID

System.out.println("Failure");

ate request vice.Error UpdateError :

System.out.println(UpdateError.getErrorCode().value());

}

}

dyn dynamicEntity.setEntityType(serviceFactory.createEntityType(entityTy // Crea EloquaService.DynamicEntityFields fieldEloquaServi fieldValueCollection = serviceFactory.createDynamicEntityFi // Add EloquaService.DynamicEntityFields.Entitse emailField.setInternalName("C_EmailAddress"); emailField.setValue("[email protected]"); fieldValueC // Add the Contact's First Name to the Dynamic Entity's field collection EloquaServiserviceFact fir fieldValueCollection.getEntityFields().add( // Add the Dynamic Entity's fields to the Dyna JAXBElement<EloquaService.DynamicEntityFields> fc; fc = serviceFactory.createDynamicEntityFieldValueCollection(fieldValueCollection); dynamicEntity.setFieldValueCollection(fc); // Add the Dynamic // Execute the request

for (int i = { { System.out.println("Success"); } else { // Extract the Error Message and Error Code for each failed Upd for (EloquaSerresult.getUpdateResult().get(i).getErrors().getValue().getError()) { System.out.println(UpdateError.getMessage().getValue()); } }




S

Create

catch (javax.xml.ws.soap.SOAPFaultException ex) { // Customize your own Error handling code. System.out.println(String.format("Message: %s", ex.getMessage()));

", ex.getFault().getFaultCode()));

/ Customize your own Error handling code.

System.out.println(String.format("Fault Code: %s} catch (Exception ex) { / System.out.println(ex.getMessage()); }

ee Also

Retrieve Delete Query WSDL Information

DU

Delete one or more Entities in the Eloqua database.

AEi

RD

FUnexpectedErrorFault VInvalidTypeFault B

S

elete sage

rguments ntityType d[] (Integer)

esponse eleteResult[]

aults

alidationFault

atchSizeExceededFault

yntax

Service instance;

[] returnValue;

entityType entityType; int[] ids; DeleteResultreturnValue = instance.Delete(entityType, ids);



Sample Code - .NET


ntity Type object EloquaService.EntityType entityType = new EloquaService.EntityType();

// Set the ID of each Entity that you want to delete [] ids = new int[1]; 0] = 1;

Execute the request quaService.DeleteResult[] deleteResults = service.Delete(entityType, ids);

Verify the status of each Delete request in the results 0; i <= deleteResults.Length ‐ 1; i++)

Successfull requests will return a positive integer value for ID (deleteResults[i].Success)


teger value for ID else

onsole.WriteLine("Failure");

ract the Error Message and Error Code for each failed Delete request foreach (EloquaService.Error deleteError in deleteResults[i].Errors) {

nsole.WriteLine(String.Format("Code: {0}", deleteError.ErrorCode)); nsole.WriteLine(String.Format("Message: {0}", deleteError.Message));

}

Model.FaultException ex)

or handling code. nsole.WriteLine(String.Format("Reson: {0}", ex.Reason.ToString()));

Console.WriteLine(String.Format("Fault Type: {0}", ex.GetType().ToString())); ing.Format("Fault Code: {0}", ex.Code.Name.ToString()));

age.ToString()));

service.ClientCredentials.UserName.UserName = "Company\\default.user"; service.ClientCredentials.UserName.Password = "test123"; // Build a Contact E entityType.ID = 0; entityType.Name = "Contact";

entityType.Type = "Base";

int ids[ // Elo // for (int i = { // if { // Failed requests will return a ‐1 in

{ C // Ext Co Co } } } catch (System.Service{ // Customize your own Err Co

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





ory = new EloquaService.ObjectFactory();


entityType.setName(serviceFactory.createEntityTypeName("Contact")); ("Base"));

of each Entity that you want to delete EloquaService.ArrayOfint ids = new EloquaService.ArrayOfint();

// Execute the request ete(entityType, ids);

Verify the status of each Delete request in the results

Successfull requests return a positive integer value for ID .get(i).isSuccess())

Failed requests return a ‐1 integer value for ID

{

Extract the Error Message and Error Code for each failed Delete request

System.out.println(String.format("Code: %s", deleteError.getErrorCode().value())); System.out.println(String.format("Message: %s",

eteError.getMessage().getValue()));

}

EloquaService.ObjectFactory serviceFact // Define a Contact EloquaService.EntityType entit entityType.setID(0); entityType.setType(serviceFactory.createEntityTypeType // Set the ID ids.getInt().add(1); EloquaService.ArrayOfDeleteResult deleteResults = service.del // for (int i = 0; i <= deleteResults.getDeleteResult().size(); i++) { // if (deleteResults.getDeleteResult() { System.out.println("Success"); } // else System.out.println("Failure"); // for (EloquaService.Error deleteError : deleteResults.getDeleteResult().get(i).getErrors().getValue().getError()) { del } } } catch (Javax.xml.ws.soap.SOAPFaultException ex) { // Customize your own Error handling code.

String.format("Message: %s", ex.getMessage())); System.out.println(String.format("Fault Code: %s", ex.getFault().getFaultCode()));

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

System.out.println( } catch (Exception ex) {



See Also

Create Retrieve Update Query WSDL Information

Query U

Q

S tax

< S esented by a string with no spaces.

V the wi

B on of the 2 search v

N uery the database and the resultset is greater than 2000 records, an error will be returned(with n wer than 2000 records before you will receive any re you require a larger set of results, you c wnload via the API. L s:

sage

uery one or more Entities from the Eloqua database.

yn

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

earch Term—The field to search for, repr

alue—The value to search for, represented by a string enclosed in quotes. This value can includeldcard: *

oolean (AND) Operator—An optional Boolean operator equivalent to an intersectialues (see the List of Operators below).

ote: If you qo records). Your query needs to be adjusted to return fesults. You can page through the results 20 results at a time. Should

ould setup a bulk do

ist of Operator

Operator Query Syntax

Equal To =

Not Equal To -

Greater Than >

Less Than <

Greater Than or Equal To >=

Less Than or Equal To <=

AEsearchQuery (String) fieldnames[] (String[]) pageNumber (Integer) pageSize (Integer)

rguments ntityType[]



Response cEntityQueryResults

ctedErrorFault ationFault

lt rgeFault ryFault imeIntervalFault

n next page.

Dynami

Faults UnexpeValidInvalidTypeFauQueryTooLaInvalidQueOperationT

Syntax

Service instance; tyType entityType;

alue = instance.Query(entityType, searchQuery, fieldList, pageNumber, pageSize);

entiString searchQuery; String[] fieldnames; int pageNumber; int pageSize; queryResult[] returnValue; returnV

Sample Code - .NET

try { // Set up the Eloqua API Service EloquaService service.Clien

.EloquaServiceClient service = new EloquaService.EloquaServiceClient(); tCredentials.UserName.UserName = "Company\\default.user";

service.ClientCredentials.UserName.Password = "test123";

ld a Contact Entity TService.EntityType entityType = new EloquaService.EntityType(); Type.ID = 0;

entityType.Name = "Contact"; pe = "Base";

a new list containing the fields you want populated > fieldList = ne ist<string>();

the Contact's Email ress to the field list

fieldList.Add("C_EmailAddress");

First e to the field list rstName"

// Build the Search Query queryText = "C_EmailAddress ='*@eloqua.com'";

container for the Query results ntityQueryResults queryResult;

// Bui ype object Eloqua entity

entityType.Ty

// Create List<string w L

// Add Add

// Add the Contact's Nam

fieldList.Add("C_Fi

);

String // Define a EloquaService.DynamicE

Note: .NET code sample concluded o




// Set the page number and size for the results int currentPage = 0;

pageSize = 20;

s empty ‐ the request will return all Entity Fields y fields defined in the field list are returned

== 0)

return all of the Entity's fields y(entityType, queryText, null, currentPage, pageSize);

se

quest and return only the selected Entity fields ery(entityType, queryText, fieldList.ToArray(), currentPage,

ities.Length > 0)

pages and records

g.Format("Total number of records: {0}", ueryResult.TotalRecords.ToString()));

int // If the field list i // Otherwise, onl if (fieldList.Count { // Execute the request and queryResult = service.Quer } el { // Execute the re queryResult = service.QupageSize); } if (queryResult.Ent { // Extract the total number of Console.WriteLine(String.Format("Total number of pages: {0}", queryResult.TotalPages.ToString())); Console.WriteLine(Strin q // Extract each Dynamic Entity in the result foreach (EloquaService.DynamicEntity dynamicEntity in queryResult.Entities)

tract the Entity ID Console.WriteLine(String.Format("Entity ID: {0}", dynamicEntity.Id));

and value of each field in the collection

on)

)); Console.WriteLine(String.Format("Field Value: {0}", field.Value));

ception ex)

{0}", ex.Reason.ToString())); Console.WriteLine(String.Format("Fault Type: {0}", ex.GetType().ToString()));

}", ex.Code.Name.ToString()));

{ // Ex // Extract the field name foreach (KeyValuePair<string, string> field in dynamicEntity.FieldValueCollecti {

}", field.Key Console.WriteLine(String.Format("Field Name: {0 } } } } catch (System.ServiceModel.FaultEx{ // Customize your own Error handling code. Console.WriteLine(String.Format("Reson: Console.WriteLine(String.Format("Fault Code: {0} catch (Exception ex) { handling code.

g.Format("Exception Message: {0}", ex.Message.ToString())); // Customize your own Error

Console.WriteLine(Strin}





try { // Set up the Eloqua API Service EloquaService.Eloqua eloquaService = new EloquaService.Eloqua();

Service object factory quaService.ObjectFactory serviceFactory = new EloquaService.ObjectFactory();

quaService.EntityType entityType = new EloquaService.EntityType(); Type.setID(0);

ityType.setName(serviceFactory.createEntityTypeName("Contact"));

a new list containing the fields you want populated quaService.ArrayOfstring fieldList = serviceFactory.createArrayOfstring();

the field list ldList.getString().add("C_EmailAddress");

'*@eloqua.com'";

results EloquaService.DynamicEntityQueryResults queryResult;

rentPage = 1;

field list is empty ‐ the request will return all Entity Fields

ze);

// Execute the request and return only the selected fields queryText, fieldList, currentPage, pageSize);

}

s())); ln(String.format("Total number of records: %s",

EloquaService.EloquaService service = eloquaService.getEloquaService(); // Instantiate a new Eloqua Elo // Define a Contact Entity Type object Elo entity ent entityType.setType(serviceFactory.createEntityTypeType("Base")); // Create Elo // Add the Contact's Email Address to fie // Build the Search Query String queryText = "C_EmailAddress= // Build a new container for the Query // Set the page number and size for the results int cur int pageSize = 20; // If the // Otherwize, 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 queryResult = service.query(entityType, queryText, null, currentPage, pageSi } else { queryResult = service.query(entityType, 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.getTotalPage System.out.printqueryResult.getTotalRecords()));




See A

C

// Extract each Dynamic Entity in the result for (EloquaService.DynamicEntity dynamicEntity :

tDynamicEntity())

System.out.println(String.format("Entity ID: %s", dynamicEntity.getId()));

for (EloquaService.DynamicEntityFields.EntityFields field : e().getEntityFields())

.println(String.format("Field Name: %s", field.getInternalName())); .getValue()));

}

tch (javax.xml.ws.soap.SOAPFaultException ex)

em.out.println(String.format("Message: %s", ex.getMessage())); at("Fault Code: %s", ex.getFault().getFaultCode()));

tch (Exception ex)

System.out.println(ex.getMessage());

queryResult.getEntities().getValue().ge { // Extract the Entity ID // Extract the field name and value of each field in the collection dynamicEntity.getFieldValueCollection().getValu { System.out System.out.println(String.format("Field Value: %s", field } } } ca{ // Customize your own Error handling code. Syst System.out.println(String.form} ca{ // Customize your own Error handling code. }

lso

reate Retrieve Update Delete WSDL Information

A

An Asset is an abstract representation of structured data in Eloqua, such as an Email or Data Export. Assets can hav title and an ID.

T asset types in the system. The fo

1

This function will return a list of the currently accessible AssetTypes from within your instance of er for DescribeAssetType.

DescribeAssetType()

This will return attributes of the AssetType that you specify

SSET METADATA

e attributes. Examples: An Email has a Subject and Body. DataImports have a

he web service contains operations for discovering all the assets and llowing operations are available:

. ListAssetTypes()

Eloqua which can then be used as a paramet

2.



A ADATA OPERATIONS

ListAssetTypes U

Retrieve all the Asset Types in your Eloqua database. Only Types available in the instance of Eloqua which y turned. Your application can parse the response and query for further information s

A ments

None

setTypeResult

ctedErrorFault

SSET MET

sage

ou are logged into are reuch as the metadata for each Asset Type.

rgu

ResponseListAs

Faults Unexpe

Syntax

Service instanListAssetTypes

ce; Result returnValue;

returnValue = instance.ListAssetTypes();



Sample Code - .NET


try { // Set up the Eloqua API Service EloquaService.EloquaServiceClient service = new EloquaService.EloquaServiceClient(); service.ClientCredentials.UserName.UserName = "Company\\default.user"; service.ClientCredentials.UserName.Password = "test123"; // Execute the request EloquaService.ListAssetTypesResult result = service.ListAssetTypes(); // Extract the name of each Asset Type foreach (String AssetType in result.AssetTypes) { Console.WriteLine(AssetType); } }

ultException ex)

r handling code. .Format("Reson: {0}", ex.Reason.ToString()));

ole.WriteLine(String.Format("Fault Type: {0}", ex.GetType().ToString())); ole.WriteLine(String.Format("Fault Code: {0}", ex.Code.Name.ToString()));

ng code. xception Message: {0}", ex.Message.ToString()));

catch (System.ServiceModel.Fa{ // Customize your own Erro Console.WriteLine(String Cons Cons} catch (Exception ex) { // Customize your own Error handli Console.WriteLine(String.Format("E}

try { Eloq

// Set up the Eloqua API Service uaService.Eloqua eloquaService = new EloquaService.Eloqua();

rvice service = eloquaService.getEloquaService();

Execute the request uaService.ListAssetTypesResult result = service.listAssetTypes();

lue().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()); }

EloquaService.EloquaSe // Eloq // Extract the name of each Asset Type for (String assetType : result.getAssetTypes().getVa {



See Also

DescribeAsset DescribeAssetType WSDL Information

DU

Retrieve all the Assets in a given Asset Type.

Aa

Respo D

FUVInvalidTypeFault

S x

escribeAssetType sage

rguments ssetType (String)

nseescribeAssetTypeResult


ynta

Service instance; String entityName; DescribeAssetTypeResult returnValue;

instance.DescribeAssetType(assetType); returnValue =



Sample Code - .NET

try { // Set up the EloquaServic

Eloqua API Service e.EloquaServiceClient service = new EloquaService.EloquaServiceClient();

Name.UserName = "Company\\default.user"; Name.Password = "test123";

Execute the request uaService.DescribeAssetTypeResult result = service.DescribeAssetType("DataExport");

// Extract the ID, Name and Type of each Asset Type (EloquaService.AssetType AssetType in result.AssetTypes)

e(String.Format("ID: {0}", AssetType.ID)); Console.WriteLine(String.Format("Type: {0}", AssetType.Type)); Console.WriteLine(String.Format("Name: {0}", AssetType.Name));

(System.ServiceModel.FaultException ex)

Error handling code. (String.Format("Reson: {0}", ex.Reason.ToString())); (String.Format("Fault Type: {0}", ex.GetType().ToString())); (String.Format("Fault Code: {0}", ex.Code.Name.ToString()));

r handling code. age: {0}", ex.Message.ToString()));

service.ClientCredentials.User service.ClientCredentials.User // Eloq

foreach { Console.WriteLin } } catch{ // Customize your own Console.WriteLine Console.WriteLine Console.WriteLine} catch (Exception ex) { // Customize your own Erro Console.WriteLine(String.Format("Exception Mess}




See Also

ListAssetTypes

try { // Set up the Eloqua API Service EloquaService.Eloqua eloquaService = new EloquaService.Eloqua(); EloquaService.EloquaService service = eloquaService.getEloquaService(); // Execute the request

setTypeResult result = service.describeAssetType("DataImport"); EloquaService.DescribeAs // Extract the ID, Name and Type of each Asset Type

Types().getValue().getAssetType())

System.out.println(String.format("ID: %s", String.valueOf(assetType.getID()))); e().getValue()));

.getValue()));

ch (javax.xml.ws.soap.SOAPFaultException ex)

for (EloquaService.AssetType assetType : result.getAsset { System.out.println(String.format("Name %s", assetType.getNam System.out.println(String.format("Type: %s", assetType.getType() } } cat{ // Customize your own Error handling code.

, ex.getMessage())); ltCode()));

own Error handling code. System.out.println(ex.getMessage());

System.out.println(String.format("Message: %s" System.out.println(String.format("Fault Code: %s", ex.getFault().getFau} catch (Exception ex) { // Customize your }

DescribeAsset WSDL Information

DescribeAsset Usage

Retrieve all the metadata for a specific Asset. The information returned also contains access permissions on the asset (Readable, Createable, etc…).

Arguments assetType (AssetType)

Response DescribeAssetResult

Faults UnexpectedErrorFault ValidationFault InvalidTypeFault



Syntax

S

Service instance; AssetType assetType; DescribeAssetResult returnValue; returnValue = instance.DescribeAsset(assetType);

ample 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 Group Asset Type object

aService.AssetType(); EloquaService.AssetType AssetType = new Eloqu AssetType.ID = 1;

AssetType.Name = "ContactGroupName"; AssetType.Type = "ContactGroup"; // Execute the request

beAssetResult result = service.DescribeAsset(AssetType);

{0}", result.Name));

EloquaService.Descri // Extract the Asset's Name

t Name: Console.WriteLine(String.Format("Asse // Extract the Asset's Properties Console.WriteLine(String.Format("Is Createable: {0}", result.IsCreateable));

sole.WriteLine(String.Format("Is Deletable: {0}", result.IsDeletable)); ole.WriteLine(String.Format("Is Queryable: {0}", result.IsQueryable));

riteLine(String.Format("Is Retrievable: {0}", result.IsRetrievable)); riteLine(String.Format("Is Updateable: {0}", result.IsUpdateable));

he Asset's Field Metadata e.DynamicAssetFieldDefinition fieldDef in result.Fields)

(String.Format("Data Type: {0}", fieldDef.DataType)); Console.WriteLine(String.Format("Display Name: {0}", fieldDef.DisplayName)); Console.WriteLine(String.Format("Internal Name: {0}", fieldDef.InternalName));

mat("Length: {0}", fieldDef.Length));

ltException ex)

ustomize your own Error handling code. ng.Format("Reson: {0}", ex.Reason.ToString())); ng.Format("Fault Type: {0}", ex.GetType().ToString()));

ole.WriteLine(String.Format("Fault Code: {0}", ex.Code.Name.ToString()));

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

}

Con Cons Console.W Console.W // Extract t foreach (EloquaServic { Console.WriteLine Console.WriteLine(String.Format("Is Required: {0}", fieldDef.IsRequired)); Console.WriteLine(String.Format("Is Writeable: {0}", fieldDef.IsWriteable)); Console.WriteLine(String.For } } catch (System.ServiceModel.Fau{ // C Console.WriteLine(Stri Console.WriteLine(Stri Cons} catch (Exception ex) { // Customize your Console.WriteLine




try { // Set up the Eloqua API Service EloquaService.Eloqua eloquaService = new EloquaService.Eloqua() EloquaService.EloquaService service = eloquaService.getEloquaSe

; rvice();

e a new Eloqua Service object factory .ObjectFactory serviceFactory = new EloquaService.ObjectFactory();

// Instantiat EloquaService // Define a Contact Group Asset Type object

= new EloquaService.AssetType();

etType);

t Name: %s", result.getName()));

perties ); ;

mat("Is Queryable: %s", result.isIsQueryable())); etrievable())); dateable()));

ue()));

d())); ); ())));

%s", ex.getMessage())); %s", ex.getFault().getFaultCode()));

EloquaService.AssetType AssetType AssetType.setID(1); AssetType.setName(serviceFactory.createAssetTypeName(""));

tactGroup")); AssetType.setType(serviceFactory.createAssetTypeType("Con // Execute the request EloquaService.DescribeAssetResult result = service.describeAsset(Ass // Extract the Asset's Name

"Asse System.out.println(String.format( // Extract the Asset's Pro System.out.println(String.format("Is Createable: %s", result.isIsCreateable()) System.out.println(String.format("Is Deleteable: %s", result.isIsDeletable())) System.out.println(String.for System.out.println(String.format("Is Retrievable: %s", result.isIsR System.out.println(String.format("Is Updateable: %s", result.isIsUp // Extract the Asset's Field Metadata for (EloquaService.DynamicAssetFieldDefinition fieldDef : result.getFields().getValue().getDynamicAssetFieldDefinition()) {

val System.out.println(String.format("Data Type: %s", fieldDef.getDataType(). System.out.println(String.format("Display Name: %s",

fieldDef.getDisplayName().getValue())); System.out.println(String.format("Internal Name: %s",

ef.getInternalName().getValue())); fieldD System.out.println(String.format("Is Required: %s", fieldDef.isIsRequire System.out.println(String.format("Is Writeable: %s", fieldDef.isIsWriteable()) System.out.println(String.format("Length: %s", String.valueOf(fieldDef.getLength } }

(javax.xml.ws.soap.SOAPFaultException ex) catch { // Customize your own Error handling code. System.out.println(String.format("Message:

System.out.println(String.format("Fault Code:} catch (Exception ex) {

n(ex.getMessage()); // Customize your own Error handling code.

System.out.printl}



See Also

ListAssetTypes DescribeAssetType WSDL Information

A

T ata using the API. W e the Eloqua ID of the object you are attempting to

C

Ad

Response C

FUVInvalidTypeFault BatchSizeExceededFault

S

SSET OPERATIONS

his section describes the operations that can be performed to retrieve and change an Asset’s dhen performing an operation it is important to us

modify or delete. The following operations are available for Assets:

AssetCreate

Retrieve Update

CU

reateAsset sage

reate one or more new Assets in the Eloqua database.

rguments ynamicAsset[]

reateAssetResult[]


yntax

Delete

Service instance; DynamicAsset[] dynamicAssets; CreateAssetResult[] returnValue; returnValue = instance.CreateAsset(dynamicAssets);



Sample Code - .NET

N

try { // Set up the EloquaServic

Eloqua API Service e.EloquaServiceClient service = new EloquaService.EloquaServiceClient();

service.ClientCredentials.UserName.UserName = "Company\\default.user"; dentials.UserName.Password = "test123";

AssetType.Type = "ContactGroup"; // Create a new Array of Dynamic Assets EloquaService.DynamicAsset[] dynamicAssets = new EloquaService.DynamicAsset[1]; // Create a new Dynamic Asset dynamicAssets[0] = new EloquaService.DynamicAsset(); dynamicAssets[0].AssetType = AssetType; // Create a Dynamic Asset's Field Value Collection dynamicAssets[0].FieldValueCollection = new EloquaService.DynamicAssetFields(); // Add the Contact Group's Name field to the Field Collection dynamicAssets[0].FieldValueCollection.Add("name", "group name"); // Add the Contact Group's Description field to the Field Collection dynamicAssets[0].FieldValueCollection.Add("description", "group description"); // Execute the request EloquaService.CreateAssetResult[] result = se ce.CreateAsset(dynamicAssets);

tus of each Contact Group Create request in the results (int i = 0; i < result.Length; i++)

teger value for ID

Console.WriteLine("Success");

requests return a ‐1 integer value for ID else

ine("Failure");

Error Message and Error Code for each failed Create request aService.Error createError in result[i].Errors)

le.WriteLine(String.Format("Code: {0}", createError.ErrorCode)); Line(String.Format("Message: {0}", createError.Message));

}

service.ClientCre // Build a Contact Group Asset Type object EloquaService.AssetType AssetType = new EloquaService.AssetType(); AssetType.ID = 0; AssetType.Name = "ContactGroupName";

rvi // Verify the sta for { // Successfull requests return a positive in if (result[i].ID != ‐1) { } // Failed { Console.WriteL // Extract the foreach (Eloqu { Conso Console.Write } }}

ote: .NET code sample concluded on next page.




catch (System.ServiceModel.FaultException ex)

ype().ToString())); nsole.WriteLine(String.Format("Fault Code: {0}", ex.Code.Name.ToString()));

de. xception Message: {0}", ex.Message.ToString()));

{ // Customize your own Error handling code. Console.WriteLine(String.Format("Reson: {0}", ex.Reason.ToString())); Console.WriteLine(String.Format("Fault Type: {0}", ex.GetT Co} catch (Exception ex) { // Customize your own Error handling co Console.WriteLine(String.Format("E}






aService.Eloqua();

EloquaService.ObjectFactory serviceFactory = new EloquaService.ObjectFactory();

// Define a Contact Asset Type object Service.AssetType();

AssetType.setName(serviceFactory.createAssetTypeName("ContactGroupName")); AssetType.setType(serviceFactory.createAssetTypeType("ContactGroup")); // Create a new Array of Dynamic Entities EloquaService.ArrayOfDynamicAsset dynamicAssets = new EloquaService.ArrayOfDynamicAsset(); // Create a new Dynamic Asset and add it to the Array of Entities EloquaService.DynamicAsset dynamicAsset = new EloquaService.DynamicAsset(); dynamicAsset.setAssetType(serviceFactory.createAssetType(AssetType)); // Create a Dynamic Asset's Field Value Collection EloquaService.DynamicAssetFields fieldValueCollection = new EloquaService.DynamicAssetFields(); fieldValueCollection = serviceFactory.createDynamicAssetFields(); // Add the Contact's Email Address field to the Dynamic Asset's field collection EloquaService.DynamicAssetFields.AssetFields nameField = serviceFactory.createDynamicAssetFieldsAssetFields(); nameField.setInternalName("name"); nameField.setValue("group name"); fieldValueCollection.getAssetFields().add(nameField); // Add the Contact's First Name field to the Dynamic Asset's field collection EloquaService.DynamicAssetFields.AssetFields descriptionField = serviceFactory.createDynamicAssetFieldsAssetFields(); descriptionField.setInternalName("description"); descriptionField.setValue("group description"); fieldValueCollection.getAssetFields().add(descriptionField); // Add the Dynamic Fields to the Dynamic Entitiy JAXBElement<EloquaService.DynamicAssetFields> fc; fc = serviceFactory.createDynamicAssetFieldValueCollection(fieldValueCollection); dynamicAsset.setFieldValueCollection(fc); // Add the Dynamic Asset (Contact) to the Array of Dynamic Entities dynamicAssets.getDynamicAsset().add(dynamicAsset); // Execute the request EloquaService.ArrayOfCreateAssetResult result = service.createAsset(dynamicAssets);

EloquaService.Eloqua eloquaService = new Eloqu EloquaService.EloquaService service = eloquaService.getEloquaService(); // Instantiate a new Eloqua Service object factory EloquaService.AssetType AssetType = new Eloqua AssetType.setID(0);





// Verify the status of each Contact Create request in the results

// Successfull requests return a positive integer value for ID != ‐1)

System.out.println("Success");

// Extract the Error Message and Error Code for each failed Create request r :

{

tch (javax.xml.ws.soap.SOAPFaultException ex)

ge: %s", ex.getMessage())); ault Code: %s", ex.getFault().getFaultCode()));

tch (Exception ex)

XBElement<EloquaService.DynamicEntityFields> fc; ollection(fieldValueCollection);

Array of Dynamic Entities namicEntities.getDynamicEntity().add(dynamicEntity);

oquaService.ArrayOfCreateResult result = service.create(dynamicEntities);

for (int i = 0; i < result.getCreateAssetResult().size(); i++) { if (result.getCreateAssetResult().get(i).getID() { } // Failed requests return a ‐1 integer value for ID else { System.out.println("Failure"); for (EloquaService.Error createErroresult.getCreateAssetResult().get(i).getErrors().getValue().getError()) System.out.println(createError.getErrorCode().value()); System.out.println(createError.getMessage().getValue()); } } } } ca{ // Customize your own Error handling code. System.out.println(String.format("Messa System.out.println(String.format("F} ca{ // Customize your own Error handling code. System.out.println(ex.getMessage()); } // Add the Dynamic Fields to the Dynamic Entitiy JA fc = serviceFactory.createDynamicEntityFieldValueC dynamicEntity.setFieldValueCollection(fc); // Add the Dynamic Entity (Contact) to the dy // Execute the request El




See Also

U

// Verify the status of each Contact Create request in the results

// Successfull requests return a positive integer value for ID

System.out.println("Success");


System.out.println("Failure");

}


for (int i = 0; i < result.getCreateResult().size(); i++) { if (result.getCreateResult().get(i).getID() != ‐1) { } // else { // 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()); } } } cat{ // Customize your own Error handling code.

stem.out.println(String.format("Message: %s", ex.getMessage())); %s", ex.getFault().getFaultCode()));

Error handling code. System.out.println(ex.getMessage());

Sy System.out.println(String.format("Fault Code:} catch (Exception ex) { // Customize your own }

pdateAsset RetrieveAsset DeleteAsset WSDL Information

RetrieveAssetU

Retrieve one or more Assets from the Eloqua database.

ssetType id[] (Integer) String[] fieldList

Response DynamicAsset[]

sage

Arguments A



Faults UnexpectedErrorFault VIBatchSizeExceededFault

S

alidationFault nvalidTypeFault

yntax

Service instance; AssetType assetType;

int[] ids;String[] fieldList;

e = instance.RetrieveAsset(assetType, ids, fieldList); DynamicAsset[] returnValue; returnValu



Sample Code - .NET


try { // Set up the Elo EloquaService.EloquaServi service.ClientCredentials

qua API Service ceClient service = new EloquaService.EloquaServiceClient(); .UserName.UserName = "Company\\default.user";

rvice.ClientCredentials.UserName.Password = "test123";

oup Asset Type object ssetType = new EloquaService.AssetType();

tGroupName";

ids[0] = 1; // Create a new list containing the fields you want populated List<string> fieldList = new List<string>(); // Add the Contact Group's Name to the field list fieldList.Add("name"); // Add the Contact Group's Description to the field list fieldList.Add("description"); // Build a Dynamic Asset array to store the results EloquaService.DynamicAsset[] retrievedAssets; // If the field list is empty ‐ the request will return all Asset Fields // Otherwise, only fields defined in the field list are returned if (fieldList.Count == 0) { // Execute the request and return all of the Asset's fields retrievedAssets = service.RetrieveAsset(AssetType, ids, null); } else { // Execute the request and return only the selected Asset fields retrievedAssets = service.RetrieveAsset(AssetType, ids, fieldList.ToArray()); } // If a result was found, extract the field values for each Dynamic Asset if (retrievedAssets.Length > 0) { foreach (EloquaService.DynamicAsset dynamicAsset in retrievedAssets) { // Extract the Field Name and Value for each element in the collection foreach (KeyValuePair<string, string> keyValPair in dynamicAsset.FieldValueCollection) { Console.WriteLine(String.Format("Field Name: {0}", keyValPair.Key)); Console.WriteLine(String.Format("Field Value: {0}", keyValPair.Value)); } } } } catch (System.ServiceModel.FaultException ex)

se // Build a Contact Gr EloquaService.AssetType A AssetType.ID = 0; AssetType.Name = "Contac AssetType.Type = "ContactGroup"; // Set the ID of the Contact Group Asset int[] ids = new int[1];




S



()));

tch (Exception ex)


Console.WriteLine(String.Format("R Console.WriteLine(String.Format("Fault Type: {0}", ex.GetType().ToString())); Console.WriteLine(String.Format("Fault Code: {0}", ex.Code.Name.ToString} ca{ // Customize your own Error handling code. Console.WriteLine(St}

ample Code – Java


aService.Eloqua(); EloquaService.Eloqua eloquaService = new Eloqu EloquaService.EloquaService service = eloquaSe

rvice.getEloquaService();

y serviceFactory = new EloquaService.ObjectFactory();

ype = new EloquaService.AssetType();

("ContactGroupName")); peType("ContactGroup"));

ng();

d the Contact Group's name to the field list

dList.getString().add("description");

retrievedAssets;

// Execute the request and return only the selected Asset fields (AssetType, ids, fieldList);

qua Service object factory // Instantiate a new Elo EloquaService.ObjectFactor

Type object // Build a Contact Group Asset

EloquaService.AssetType AssetT AssetType.setID(0);

Name AssetType.setName(serviceFactory.createAssetType AssetType.setType(serviceFactory.createAssetTy

// Set the ID of the Contact Group Asset

s = new EloquaService.ArrayOfint(); EloquaService.ArrayOfint id.getInt().add(25217); ids

// Create a new array containing the fields you want populated

quaService.ArrayOfstring fieldList = new EloquaService.ArrayOfstri Elo

Ad // fieldList.getString().add("name");

Add the Contact Group's description to the field list // fiel

store the results // Build a Dynamic Asset array to

quaService.ArrayOfDynamicAsset Elo

e field array is empty ‐ the request will return all Asset Fields // If th // Otherwise, only fields defined in the field list are returned if (fieldList.getString().size() == 0) { // Execute the request and return all of the Asset's fields retrievedAssets = service.retrieveAsset(AssetType, ids, null); } else {

retrievedAssets = service.retrieveAsset }





S

C

ee Also

reateAsset UpdateAsset D sseteleteA WSDL Information

UU

U

Ad

RU

FUValidationFault InvalidTypeFault B

pdateAsset sage

pdate one or more Assets in the Eloqua database.

rguments ynamicAsset[]

esponse pdateAssetResult[]



// If a result was found, extract the field values for each Dynamic Entity ) > 0)

ntity())

// Extract the Field Name and Value for each element in the collection ervice.DynamicEntityFields.EntityFields field :

amicEntity.getFieldValueCollection().getValue().getEntityFields())

())); System.out.println(String.format("Field Value: %s", field.getValue()));

}

(javax.xml.ws.soap.SOAPFaultException ex)

ode()));

if (retrievedEntities.getDynamicEntity().size( { for (EloquaService.DynamicEntity dynamicEntity : retrievedEntities.getDynamicE { for (EloquaSdyn { System.out.println(String.format("Field Name: %s", field.getInternalName

} } } catch{ // 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().getFaultC} catch (Exception ex) { de. // Customize your own Error handling co System.out.println(ex.getMessage()); }



Syntax

S

cluded on next page.

Service instance; DynamicAsset[] dynamicAssets; UpdateAssetResult[] returnValue;

returnValue = instance.UpdateAsset(dynamicAssets);

ample Code - .NET


quaService.EloquaServiceClient service = new EloquaService.EloquaServiceClient(); = "Company\\default.user"; "test123";

"ContactGroupName"; ntactGroup";

= new EloquaService.DynamicAsset[1];

// Create a new Dynamic Asset and add it to the Array of Entities dynamicAssets[0] = new EloquaService.DynamicAsset();

the Asset Type to Contact Group Assets[0].AssetType = AssetType;

the Contact record's ID [0].Id = 26197;

c Asset's Field Value Collection ieldValueCollection = new EloquaService.DynamicAssetFields();

Add the Contact Group's Name to the Dynamic Asset's field collection micAssets[0].FieldValueCollection.Add("name", "group name");

the Dynamic Asset's field collection Assets[0].FieldValueCollection.Add("description", "group description");

request uaService.UpdateAssetResult[] result = service.UpdateAsset(dynamicAssets);

Elo service.ClientCredentials.UserName.UserName service.ClientCredentials.UserName.Password = // Build a Contact Group Asset Type object EloquaService.AssetType AssetType = new EloquaService.AssetType(); AssetType.ID = 0; AssetType.Name = AssetType.Type = "Co // Create a new Array of Dynamic Entities EloquaService.DynamicAsset[] dynamicAssets

// Set dynamic // Set dynamicAssets // Create a Dynami dynamicAssets[0].F // dyna // Add the Contact Group's Description to dynamic // Execute the Eloq

Note: .NET code sample con




S

ote: Java code sample continued on next page.

// Verify the status for (int i = 0; i < result.Length; i++

of each Contact Group Update request in the results )


requests return a ‐1 integer value for ID

{ Console.WriteLine("Failure");

updateError.ErrorCode)); "Message: {0}", updateError.Message));

tring())); ing()));

{ // Successfull requests return a positive integer value for ID if (result[i].ID != ‐1) {

// Failed else

// 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}",

Console.WriteLine(String.Format( } } } } tch (FaultException ex) ca

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

Console.WriteLine(String.Format("Fault Type: {0}", ex.GetType().ToSCode.Name.ToStr Console.WriteLine(String.Format("Fault Code: {0}", ex.

} catch (Exception ex) {

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

Console.WriteLine(String.Format(}

ample Code – Java


qua Service object factory

quaService.AssetType();

AssetType.setID(0); AssetType.setName(serviceFactory.createAssetTypeName("ContactGroupName")); AssetType.setType(serviceFactory.createAssetTypeType("ContactGroup")); // Create a new Array of Dynamic Assets EloquaService.ArrayOfDynamicAsset dynamicAssets = new EloquaService.ArrayOfDynamicAsset();

EloquaService.Eloqua eloquaService = new EloquaService.Eloqua(); EloquaService.EloquaService service = eloquaService.getEloquaService(); // Instantiate a new Elo EloquaService.ObjectFactory serviceFactory = new EloquaService.ObjectFactory();

// Define a Contact Group Asset Type object EloquaService.AssetType AssetType = new Elo

N





// Instantiate a new Dynamic Asset EloquaService.DynamicAsset dynamicAsset = new EloquaService.DynamicAsset();

amicAsset.setAssetType(serviceFactory.createAssetType(AssetType));

te a Dynamic Asset's Field Value Collection alueCollection = new EloquaService.DynamicAssetFields();

lueCollection = serviceFactory.createDynamicAssetFields();

Contact Group's Name to the Dynamic Asset's field collection ervice.DynamicAssetFields.AssetFields nameField =

tFields(); nameField.setInternalName("name");

createDynamicAssetFieldsAssetFields(); tionField.setInternalName("description");

criptionField.setValue("group description"); fieldValueCollection.getAssetFields().add(descriptionField);

dyn dynamicAsset.setId(1); // Crea EloquaService.DynamicAssetFields fieldV fieldVa // Add the EloquaSserviceFactory.createDynamicAssetFieldsAsse nameField.setValue("group name"); fieldValueCollection.getAssetFields().add(nameField); // Add the Contact Group's Description to the Dynamic Asset's field collection EloquaService.DynamicAssetFields.AssetFields descriptionField = serviceFactory. descrip des // Add the Dynamic Asset's fields to the Dynamic Asset's field collection

> fc; llection);

JAXBElement<EloquaService.DynamicAssetFields fc = serviceFactory.createDynamicAssetFieldValueCollection(fieldValueCo dynamicAsset.setFieldValueCollection(fc); // Add the Dynamic Asset (Contact Group) to the Array of Dynamic Assets

amicAsset().add(dynamicAsset);

// Verify the status of each Contact Update request in the results for (int i = 0; i < result.getUpdateAssetResult().size(); i++)

sfull requests return a positive integer value for ID if (result.getUpdateAssetResult().get(i).getID() != ‐1)

{ ");

else

r Code for each failed Update request

t().get(i).getErrors().getValue().getError())

System.out.println(UpdateError.getMessage().getValue());

}

dynamicAssets.getDyn // Execute the request EloquaService.ArrayOfUpdateAssetResult result = service.updateAsset(dynamicAssets);

{ // Succes System.out.println("Success } // Failed requests return a ‐1 integer value for ID { System.out.println("Failure"); // Extract the Error Message and Erro for (EloquaService.Error UpdateError : result.getUpdateAssetResul { System.out.println(UpdateError.getErrorCode().value()); } }

}




S

CreateAss

catch (javax.xml.ws.soap.SOAPFaultException ex)

g.format("Message: %s", ex.getMessage())); System.out.println(String.format("Fault Code: %s", ex.getFault().getFaultCode()));

Customize your own Error handling code.

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

ee Also

et RetrieveAsset DeleteAsset WSDL Information

DU

D

AAid[] (Integer)

RD

FUVInvalidTypeFault B

S

eleteAsset sage

elete one or more Assets in the Eloqua database.

rguments ssetType

esponse eleteAssetResult[]



yntax

Service instance; assetType; assetType

int[] ids; DeleteAssetResult[] returnValue; returnValue = instance.DeleteAsset(assetType, ids);



Sample Code - .NET


service.ClientCredentials.UserName.Password = "test123"; service.ClientCredentials.UserName.UserName = "Company\\default.user"; // Build a Contact Group Asset Type object

Service.AssetType();

AssetType.Name = "ContactGroupName"; AssetType.Type = "ContactGroup";

Set the ID of each Asset that you want to delete s = new int[1]; = 26197;

ute the request .DeleteAssetResult[] deleteResults = service.DeleteAsset(AssetType, ids);

tus of each Delete request in the results <= deleteResults.Length ‐ 1; i++)

// Successfull requests will return a positive integer value for ID if (deleteResults[i].Success)

iled requests will return a ‐1 integer value for ID

.WriteLine("Failure");

e Error Message and Error Code for each failed Delete request aService.Error deleteError in deleteResults[i].Errors)

{ iteLine(String.Format("Code: {0}", deleteError.ErrorCode)); iteLine(String.Format("Message: {0}", deleteError.Message));

(FaultException ex)

Error handling code. Format("Reson: {0}", ex.Reason.ToString())); Format("Fault Type: {0}", ex.GetType().ToString()));

: {0}", ex.Code.Name.ToString()));

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

EloquaService.AssetType AssetType = new Eloqua AssetType.ID = 0;

// int[] id ids[0] // Exec EloquaService // Verify the sta for (int i = 0; i { { Console.WriteLine("Success"); } // Fa else { Console // Extract th foreach (Eloqu Console.Wr Console.Wr } } } } catch { // Customize your own Console.WriteLine(String. Console.WriteLine(String. Console.WriteLine(String.Format("Fault Code} catch (Exception ex) {





new EloquaService.ObjectFactory();

Group Asset Type object w EloquaService.AssetType();

AssetType.setName(serviceFactory.createAssetTypeName("ContactGroupName")); "ContactGroup"));

each Asset that you want to delete EloquaService.ArrayOfint ids = new EloquaService.ArrayOfint();

// Execute the request e.deleteAsset(AssetType, ids);

Verify the status of each Delete request in the results

Successfull requests return a positive integer value for ID ult().get(i).isSuccess())


{

Extract the Error Message and Error Code for each failed Delete request

System.out.println(String.format("Code: %s", deleteError.getErrorCode().value())); System.out.println(String.format("Message: %s",

eteError.getMessage().getValue()));

}

EloquaService.ObjectFactory serviceFactory = // Define a Contact EloquaService.AssetType AssetType = ne AssetType.setID(0); AssetType.setType(serviceFactory.createAssetTypeType( // Set the ID of ids.getInt().add(1); EloquaService.ArrayOfDeleteAssetResult deleteResults = servic // for (int i = 0; i <= deleteResults.getDeleteAssetResult().size(); i++) { // if (deleteResults.getDeleteAssetRes { System.out.println("Success"); } // else System.out.println("Failure"); // for (EloquaService.Error deleteError : deleteResults.getDeleteAssetResult().get(i).getErrors().getValue().getError()) { del } } } catch (javax.xml.ws.soap.SOAPFaultException ex) { // Customize your own Error handling code.






See Also

CreateAsset UpdateAsset RetrieveAsset WSDL Information

G

T le:

ListGroupMembership U

Li

ADynamicEntity

RD

FUVIInvalidEntityFault

S

ROUP MEMBERSHIP OPERATIONS

he following Group Membership operations are availab

sage

st group membership.

rguments

esponse ynamicAsset[]


nFault alidationvalidTypeFault

yntax

Service instance; DynamicEntity entity;

DynamicAsset[] returnValue; returnValue = instance.ListGroupMembership(entity);



Sample Code - .NET

try { // Set u EloquaSe service.Clie

p the Eloqua API Service rvice.EloquaServiceClient service = new EloquaService.EloquaServiceClient();

ntCredentials.UserName.UserName = "Company\\default.user"; service.ClientCredentials.UserName.Password = "test123";

ject ice.EntityType();

Instantiate a new Dynamic Entity of type Contact and supply the EntityID amicEntity entity = new EloquaService.DynamicEntity { EntityType = entityType,

ute the request

.DynamicAsset[] result = service.ListGroupMembership(entity);

xtract the name of each Asset rvice.DynamicAsset asset in result)

Line(asset.AssetType.Name);

.FaultException ex)

n Error handling code. ring.Format("Reson: {0}", ex.Reason.ToString())); ring.Format("Fault Type: {0}", ex.GetType().ToString()));

nsole.WriteLine(String.Format("Fault Code: {0}", ex.Code.Name.ToString()));

g code. e.ToString()));

// Build a Contact Entity Type ob EloquaService.EntityType entityType = new EloquaServ entityType.ID = 0; entityType.Name = "Contact"; entityType.Type = "Base"; // EloquaService.DynId = 1 };

// Exec EloquaService // E foreach (EloquaSe {

Console.Write }} catch (System.ServiceModel{ // Customize your ow Console.WriteLine(St

ole.WriteLine(St Cons Co} catch (Exception ex) { // Customize your own Error handlin Console.WriteLine(String.Format("Exception Message: {0}", ex.Messag}







entityType.setName(serviceFactory.createEntityTypeName("Contact"));

antiate a new Dynamic Entity of type Contact and supply the EntityID EloquaService.DynamicEntity entity = new EloquaService.DynamicEntity();

tGroupMembership(entity);

.getDynamicAsset())

System.out.println(asset.getAssetType().getValue().getName().getValue());

System.out.println(String.format("Fault Code: %s", ex.getFault().getFaultCode()));

ch (Exception ex)

System.out.println(ex.getMessage()); }

EloquaService.ObjectFactory serviceFact // Define a Contact EloquaService.EntityType entit entityType.setID(0); entityType.setType(serviceFactory.createEntityTypeType("Base")); // Inst entity.setId(1); entity.setEntityType(serviceFactory.createEntityType(entityType)); // Execute the request EloquaService.ArrayOfDynamicAsset result = service.lis for (EloquaService.DynamicAsset asset : result { } } catch (javax.xml.ws.soap.SOAPFaultException ex) { // Customize your own Error handling code. System.out.println(String.format("Message: %s", ex.getMessage())); } cat{ // Customize your own Error handling code.

See Also

AddGroupMember RemoveGroupMember WSDL Information

AddGroupMember Usage

Add a member to a group.

Arguments DynamicEntity DynamicAsset

Response GroupMemberResult



Faults UnexpectedErrorFault ValidationFault III

S

nvalidTypeFault nvalidAssetFault nvalidEntityFault

yntax


DynamicAsset asset;GroupMemberResult returnValue; returnValue = instance.AddGroupMember(entity, asset);



Sample Code - .NET

try { // Set up the Elo EloquaService.Eloq service.ClientCreden service.ClientCreden

qua API Service uaServiceClient service = new EloquaService.EloquaServiceClient();

tials.UserName.UserName = "Company\\default.user"; tials.UserName.Password = "test123";

Build a Contact Entity Type object ype entityType = new EloquaService.EntityType();

;

yID { EntityType = entityType,

Id = 1 }; // Build a Contact Group Asset Type object EloquaService.AssetType assetType = new EloquaService.AssetType(); assetType.ID = 0; assetType.Type = "ContactGroup"; assetType.Name = "ContactGroupName"; // Instantiate a new Dynamic Asset of type ContactGroup and supply the AssetID EloquaService.DynamicAsset asset = new EloquaService.DynamicAsset { AssetType = assetType, Id = 1 }; // Execute the request EloquaService.GroupMemberResult result = service.AddGroupMember(entity, asset); // Verify the Result if (result.Success) { Console.WriteLine("Success"); } else { foreach (EloquaService.Error error in result.Errors) { Console.WriteLine(error.ErrorCode); Console.WriteLine(error.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())); }

// EloquaService.EntityT entityType.ID = 0; entityType.Name = "Contact" entityType.Type = "Base"; // Instantiate a new Dynamic Entity of type Contact and supply the Entit EloquaService.DynamicEntity entity = new EloquaService.DynamicEntity









object w EloquaService.AssetType();

assetType.setID(0);

// Instantiate a new Dynamic Asset of type Contact Group and supply the AssetID et asset = new EloquaService.DynamicAsset();

asset.setAssetType(serviceFactory.createAssetType(assetType));

quaService.GroupMemberResult result = service.addGroupMember(entity, asset);

Verify the result sult.isSuccess())

(EloquaService.Error error : result.getErrors().getValue().getError()) {

System.out.println(error.getErrorCode()); ().getValue());

}

EloquaService.ObjectFactory serviceFact // Define a Contact EloquaService.EntityType entit entityType.setID(0); entityType.setType(serviceFactory.createEntityTypeType("Base")); // Inst entity.setId(1); entity.setEntityType(serviceFactory.createEntityType(entityType)); // Define a ContactGroup Asset Type EloquaService.AssetType assetType = ne assetType.setName(serviceFactory.createAssetTypeName("ContactGroupName")); assetType.setType(serviceFactory.createAssetTypeType("ContactGroup")); EloquaService.DynamicAss asset.setId(1); // Execute the request Elo // if (re { System.out.println("Success"); } else { for System.out.println(error.getMessage } } catch (javax.xml.ws.soap.SOAPFaultException ex) { // Customize your own Error handling code.






See Also

ListGroupMembership RemoveGroupMember WSDL Information

RemoveGroupMember U

R

ADDynamicAsset

RG

FUVIIInvalidEntityFault

S

sage

emove a member from a group.

rguments ynamicEntity

esponse roupMemberResult

aults nexpectedErrorFault alidationFault nvalidFileType nvalidAssetFault

yntax


pMemberResult returnValue; nce.RemoveGroupMember(entity, asset);

DynamicAsset asset; GroureturnValue = insta



Sample Code - .NET

try { // Set up the Elo EloquaServic

qua API Service e.EloquaServiceClient service = new EloquaService.EloquaServiceClient();

UserName = "Company\\default.user"; Password = "test123";

Build a Contact Entity Type object uaService.EntityType entityType = new EloquaService.EntityType();

entityType.Name = "Contact"; ype.Type = "Base";

e a new Dynamic Entity of type Contact and supply the EntityID e.DynamicEntity entity = new EloquaService.DynamicEntity { EntityType = entityType,

Group Asset Type object tType assetType = new EloquaService.AssetType();

tType.ID = 0; actGroup"; actGroupName";

new Dynamic Asset of type ContactGroup and supply the AssetID micAsset asset = new EloquaService.DynamicAsset { AssetType = assetType, Id =

Execute the request uaService.GroupMemberResult result = service.RemoveGroupMember(entity, asset);

{ foreach (EloquaService.Error error in result.Errors) { Console.WriteLine(error.ErrorCode); Console.WriteLine(error.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())); }

service.ClientCredentials.UserName. service.ClientCredentials.UserName. // Eloq entityType.ID = 0;

entityT // Instantiat EloquaServicId = 1 }; // Build a Contact EloquaService.Asse asse assetType.Type = "Cont assetType.Name = "Cont // Instantiate a EloquaService.Dyna1 }; // Eloq // Verify the Result if (result.Success) { Console.WriteLine("Success"); } else









object w EloquaService.AssetType();

assetType.setID(0);

// Instantiate a new Dynamic Asset of type Contact Group and supply the AssetID et asset = new EloquaService.DynamicAsset();

asset.setAssetType(serviceFactory.createAssetType(assetType));

quaService.GroupMemberResult result = service.removeGroupMember(entity, asset);

Verify the result sult.isSuccess())

(EloquaService.Error error : result.getErrors().getValue().getError()) {

System.out.println(error.getErrorCode()); ().getValue());

}

EloquaService.ObjectFactory serviceFact // Define a Contact EloquaService.EntityType entit entityType.setID(0); entityType.setType(serviceFactory.createEntityTypeType("Base")); // Inst entity.setId(1); entity.setEntityType(serviceFactory.createEntityType(entityType)); // Define a ContactGroup Asset Type EloquaService.AssetType assetType = ne assetType.setName(serviceFactory.createAssetTypeName("ContactGroupName")); assetType.setType(serviceFactory.createAssetTypeType("ContactGroup")); EloquaService.DynamicAss asset.setId(1); // Execute the request Elo // if (re { System.out.println("Success"); } else { for System.out.println(error.getMessage } } catch (javax.xml.ws.soap.SOAPFaultException ex) { // Customize your own Error handling code.


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


}



See Also

ListGroupMembership AddGroupMember WSDL Information

Data Transfer Service T ata transfer s records within Eloqua in a scalable fashion. It also allows fo ion. The data transfer s regularly exceed 2000 re h the web services API.

T st o reports that contain c

R a server to produce a Report and export it to a flat fil nsfer to your web service. T the file.

R ify the following s cess or fa reviously saved “A

T the following WSDL:

https://secure.eloqua.c

he Data Transfer service has also been referred to as “Bulk” data transfers in this guide. The dervice allows for the updating of large numbers ofr bulk transfer of data from Eloqua to a streamlined file for download and manipulat

ervice is the preferred method of transferring records if the number of records willcords as this is the current limit for any queries into the Eloqua system throug

he Data Export service will allow the export via the API of any saved report in the system that returns a lif Contact, Prospect or Company entity records. It will also allow for the export of staticontact activity data:

unning an export via the API will first trigger the Eloque on our servers. This flat file can then be transferred via the API as a binary trahe web service on your end is then responsible for parsing or transferring the contents of

unning an import of a file must first be setup within the Eloqua User Interface to specettings into an “AutoSynch”: Field mappings, actions to perform after upload, notification of sucilure. When importing via the API, you will need to specify the ID of one of these putoSynchs” to be used when importing your file.

he Data Transfer services use

om/API/1.2/DataTransferService.svc?wsdl

D lk transfer of flat files through the API. This particular API endpoint has b mized for transmitting binary files.

N ly Reports that are regular Contact/Prospect/Company record type of Reports are exportable th data transfer service. Some saved Reports will not be visible via the API because they are not o

D

B n 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 E nce that is performed – the newly created export re ssets via the API.

ata Transfer Services support bueen opti

ote: Onrough the ne of these standard types (ie: visitor reports).

ATA EXPORT OPERATIONS

efore you ca

loqua – and then setup that saved report for export. Oport will be shown when describing the DataIExport A



The following Data Export operations are available:

Faults

InitializeDataExport Usage

Initialize a Data Export.

Arguments AssetType

Response DataExportExecution

UnexpectedErrorFault ValidationFault OperationTimeIntervalFault

Syntax

Service instance; AssetType assetType;

instance.InitializeDataExport(assetType);



Sample Code - .NET

try { // Set up the Eloqua API Data Transfer Service EloquaDataService.DataTransferServiceClient service = new EloquaDataService.DataTransferServiceClient(); service.ClientCredentials.UserName.UserName = "Company\\default.user"; service.ClientCredentials.UserName.Password = "test123"; // Build an Asset Type object EloquaDataService.AssetType assetType = new EloquaDataService.AssetType();

Export"; ;

quest eDataExport(assetType);

act the ID of the Data Export Execution riteLine(String.Format("Data Export Initialized"));

ystem.ServiceModel.FaultException ex)

Error handling code. Console.WriteLine(String.Format("Reson: {0}", ex.Reason.ToString()));

ole.WriteLine(String.Format("Fault Type: {0}", ex.GetType().ToString())); ng.Format("Fault Code: {0}", ex.Code.Name.ToString()));

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

assetType.ID = 0; assetType.Name = "Sample Data assetType.Type = "DataExport" // Execute the re service.Initializ // Extr Console.W} catch (S{ // Customize your own Cons Console.WriteLine(Stri} catch (Exception ex) { // Co}




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

serviceFactory = new EloquaDataService.ObjectFactory();

pe object new EloquaDataService.AssetType();

assetType.setName(serviceFactory.createAssetTypeName("Sample Data Export")); eFactory.createAssetTypeType("DataExport"));

// Execute the request

// Extract the ID of the Data Export Execution rt Initialized",));


ch (Exception ex)

System.out.println(ex.getMessage()); }

EloquaDataService.ObjectFactory // Build an Asset Ty EloquaDataService.AssetType assetType = assetType.setID(0); assetType.setType(servic service.initializeDataExport(assetType); System.out.println(String.format("Data Expo} catch (javax.xml.ws.soap.SOAPFaultException ex) { // Customize your own Error handling code. System.out.println(String.format("Message: %s", ex.getMessage())); } cat{ // Customize your own Error handling code.

See Also

DataExportStatus GetDataExportFile WSDL Information



DataExportStatus Usage

R

AAssetType

RD

FUV

S

etrieve the status of a Data Export execution.

rguments

esponse ataExportExecutionStatus


yntax

Service instance; AssetType assetType; taExportExecutionStatus returnValue; Da

returnValue = instance.DataExportStatus(assetType);




Sample Code - .NET

try { // Set up the Eloqua API Data Transfer EloquaDataService.DataTransferServiceC

Service lient service = new

ervice.DataTransferServiceClient(); .ClientCredentials.UserName.UserName = "Company\\default.user";

lientCredentials.UserName.Password = "test123";

uild a Data Export Asset Type object setType = new EloquaDataService.AssetType();

tType.Name = "Sample Data Export"; tType.Type = "DataExport";

e.DataExportExecutionStatus status = service.DataExportStatus(assetType);

Extract the status of the Data Export

ecutionStatus.Complete:

re: 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())); }

EloquaDataS service service.C // B EloquaDataService.AssetType as assetType.ID = 0; asse asse // Execute the request EloquaDataServic // switch (status) { case SampleCode.EloquaDataService.DataExportEx Console.WriteLine("Data Export is Complete"); break; case SampleCode.EloquaDataService.DataExportExecutionStatus.Failu



See Also

InitializeDataExport


tory = new EloquaDataService.ObjectFactory();

ort Asset Type object new EloquaDataService.AssetType();


EloquaDataService.ObjectFactory serviceFac // Build a Data Exp EloquaDataService.AssetType assetType = assetType.setID(0); assetType.setType(servic // Execute the request

s status = service.dataExportStatus(assetType);

Extract the status of the Data Export

E:

t.println("Data Export Failed");


EloquaDataService.DataExportExecutionStatu // switch (status) { case COMPLET System.out.println("Data Export is Complete"); case FAILURE: System.ou case IN_PROGRESS: System.out.println("Data Export in Progress"); } } cat{ // Customize your own Error handling code.

, ex.getMessage())); ltCode()));

own Error handling code. System.out.println(ex.getMessage());

System.out.println(String.format("Message: %s" System.out.println(String.format("Fault Code: %s", ex.getFault().getFau} catch (Exception ex) { // Customize your }

GetDataExportFile WSDL Information

GetDataExportFile Usage

Retrieve the Data Export file.

Arguments AssetType



Response Byte[]

FUV

S


yntax

Service instance; AssetType assetType; Byte[] returnValue;

returnValue = instance.GetDataExportFile(assetType);



Sample Code - .NET

try { // Set up the Eloqua API Data Transfer Service

TransferServiceClient service = new sferServiceClient();

edentials.UserName.UserName = "Company\\default.user"; rvice.ClientCredentials.UserName.Password = "test123";

t Asset Type object pe assetType = new EloquaDataService.AssetType();

// 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())); }

EloquaDataService.DataEloquaDataService.DataTran service.ClientCr se // Build a Data Expor EloquaDataService.AssetTy assetType.ID = 0; assetType.Name = "Sample Data Export"; assetType.Type = "DataExport";





tory = new EloquaDataService.ObjectFactory();

ort Asset Type object new EloquaDataService.AssetType();


EloquaDataService.ObjectFactory serviceFac // Build a Data Exp EloquaDataService.AssetType assetType = assetType.setID(0); assetType.setType(servic // Execute the request

tFile(assetType);

String fileName = "c:\\fileName.txt";

antiate a new file stream a.io.FileOutputStream fileOutputStream = new Java.io.FileOutputStream(fileName);

try

fileOutputStream.write(bytes);

new Exception(String.format("Unable to create file %s", fileName));

// Close the file stream fileOutputStream.close();


ch (Exception ex)

System.out.println(ex.getMessage());

byte[] bytes = service.getDataExpor // Define the file // Inst Jav // Try writing the bytes to a file { // Try writing the bytes to the file } catch (Exception ex) { throw } finally { } } catch (javax.xml.ws.soap.SOAPFaultException ex) { // Customize your own Error handling code. System.out.println(String.format("Message: %s", ex.getMessage())); } cat{ // Customize your own Error handling code. }



See Also

In eDataExportitializ DataExportStatus WSDL Information

D

T

IU

In

AByte[] ADataSourceType

RDataImportExecution

FUnexpectedErrorFault VIQueueLimitReachedFault

S

ATA IMPORT OPERATIONS

he following Data Import operations are available:

nitializeDataImport sage

itialize a Data Import.

rguments

ssetType

esponse

aults

alidationFault nvalidFileType

yntax

Service instance; Byte[] data; AssetType assetType; DataSourceType dataSourceType; te[] returnValue;

taImport(data, assetType, ByreturnValue = instance.InitializeDadataSourceType);



Sample Code - .NET

try { // Set up th EloquaDataS

e Eloqua API Data Transfer Service ervice.DataTransferServiceClient service = new

ferServiceClient(); ls.UserName.UserName = "Company\\default.user";

ssword = "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;

leName.txt";

a new file and binary reader fo = new FileInfo(fileName);

ryReader binaryReader = new BinaryReader(new FileStream(fileName, FileMode.Open, ess.Read));

file into a Byte array = binaryReader.ReadBytes(Convert.ToInt32(fileInfo.Length));

y reader ();

est ataImportExecution dataImportExecution =

ataImport(data, assetType, dataSourceType);

e Data Import Execution nsole.WriteLine(String.Format("Data Import Execution ID: {0}", mportExecution.ID.ToString()));

del.FaultException ex)

ng code. eson: {0}", ex.Reason.ToString()));

g())); g()));

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

EloquaDataService.DataTrans service.ClientCredentia service.ClientCredentials.UserName.Pa

// Set the filename String fileName = "c:\\fi // Instantiate FileInfo fileIn BinaFileAcc // Read the Byte[] data // Close the binar binaryReader.Close // Execute the requ EloquaDataService.Dservice.InitializeD // Extract the ID of th CodataI} catch (System.ServiceMo{ // Customize your own Error handli

g.Format("R Console.WriteLine(Strin Console.WriteLine(String.Format("Fault Type: {0}", ex.GetType().ToStrin Console.WriteLine(String.Format("Fault Code: {0}", ex.Code.Name.ToStrin}




try { // Set up the Eloqua API Data Transfer Service EloquaDataService.EloquaDataTransfer eloquaService = new EloquaDataService.EloquaDataTransfer(); EloquaDataService.DataTransferService service = eloquaService.getEloquaDataTransfe

rService();

EloquaDataService.ObjectFactory serviceFactory = new EloquaDataService.ObjectFactory();

ypeName("Sample Data Import")); ateAssetTypeType("DataImport"));

;

m(fileName);

// Read the bytes to file

h‐offset)) >=

}

n Error handling code. System.out.println(ex.getMessage());

// Instantiate a new Eloqua Data Transfer Service object factory // Build a Data Import Asset Type object

tType assetType = new EloquaDataService.AssetType(); EloquaDataService.Asse assetType.setID(0);

ateAssetT assetType.setName(serviceFactory.cre assetType.setType(serviceFactory.cre // 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.FileInputStrea byte[] byteData = new byte[(int) file.length()]; int offset = 0; int numRead = 0; while (offset < file.length() && (numRead=is.read(byteData, offset, byteData.lengt 0) { offset += numRead; // Execute the request EloquaDataService.DataImportExecution dataImportExecution = rvice.initializeDataImport(byteData, assetType, dataSourceType); se

// 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 ow }



See Also

DataImportStatus WSDL Information

DUsage

C

AAD

RD

FUnexpectedErrorFault V

S

ataImportStatus

heck the status of a Data Import.

rguments ssetType ataImportExecution

esponse ataImportExecutionStatus

aults

alidationFault

yntax

Service instance; AssetType assetType; DataImportExecution dataImportExecution;

us returnValue; stance.DataImportStatus(assetType, dataImportExecution);

DataImportExecutionStatreturnValue = in



Sample Code - .NET

try { // Set up the Eloqua AP EloquaDataService.DataTEloquaDataService.DataTrans

I Data Transfer Service ransferServiceClient service = new ferServiceClient();

ervice.ClientCredentials.UserName.UserName = "Company\\default.user"; ls.UserName.Password = "test123";

ild a Data Import Asset Type object DataService.AssetType assetType = new EloquaDataService.AssetType();

.ID = 0; Sample Data Import"; ataImport";

Import Execution object ortExecution dataImportExecution = new

uaDataService.DataImportExecution();

t Execution ID (see InitializeDataImport) ution.ID = 1;

est ImportExecutionStatus status =

tion);

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())); }

s service.ClientCredentia // Bu Eloqua assetType assetType.Name = "

tType.Type = "D asse // Instantiate a new Data EloquaDataService.DataImpEloq // Set the Data Impor dataImportExec // Execute the requ EloquaDataService.Dataservice.DataImportStatus(assetType, dataImportExecu // Check the Data Import status if (status == SampleCode.EloquaDataService.DataImportExecutionStatus.Complete) {





tFactory();

e object EloquaDataService.AssetType assetType = new EloquaDataService.AssetType();

Import")); AssetTypeType("DataImport"));

xecution dataImportExecution = new oquaDataService.DataImportExecution();

Import)

.dataImportStatus(assetType, dataImportExecution);

EloquaDataService.ObjectFactory serviceFactory = new EloquaDataService.Objec // Build a Data Import Asset Typ assetType.setID(0); assetType.setName(serviceFactory.createAssetTypeName("Sample Data assetType.setType(serviceFactory.create // Instantiate a new Data Import Execution object EloquaDataService.DataImportEEl // Set the Data Import Execution ID (see InitializeData dataImportExecution.setID(1); // Execute the request EloquaDataService.DataImportExecutionStatus status = service Check the Data Import status

tus == EloquaDataService.DataImportExecutionStatus.COMPLETE)

{

s of the Data Import: %s", tus.values().toString()));

// if (sta { System.out.println("Data Import is complete"); } else System.out.println(String.format("Statusta } } catch (javax.xml.ws.soap.SOAPFaultException ex) { // Customize your own Error handling code.

(String.format("Message: %s", ex.getMessage())); System.out.println(String.format("Fault Code: %s", ex.getFault().getFaultCode()));


System.out.println } catch (Exception ex) {



See Also

In ataImportitializeD WSDL Information

E

B to process more records than allowed by the maximum batch size. Consider using the Data Transfer service

rrors

atchSizeExceededFault An operation tried

when working with large data sets.

DuplicateValue A duplicate value is not permitted.

I The supplied asset is invalid or does not exist. nvalidAssetFault

InvalidDataType The data type is invalid.

I t. nvalidEntityFault The supplied entity is invalid or does not exis

I an input for a Query .

nvalidQueryFault An operation

invalid query expression was provided as

I the expected type. nvalidTypeFault The type provided did not match

I temNotFound em was not found. The it

M eeded. aximumLengthExceeded The maximum length was exc

OperationTimeIntervalFault The operation was requested too many times within the specified time interval.

QueryTooLargeFault Query results are too large. Consider using the Data Transfer with large data sets. service when working

R d. equiredFieldNotSpecified The operation requires a field that was not supplie

U The operation’s requestor was not authorized or does not have the appropriate permission.

nauthorizedAction

UnexpectedDataException The supplied data was not in the expected format.



98 © 2008 Eloqua Corporation

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

866 327 8764 · www.eloqua.com

UnexpectedErrorFault

ValidationFault Indicates that a supplied value is not valid.

EloquaWebServicesAPI1.2DeveloperGuide

Documents

Transcript of EloquaWebServicesAPI1.2DeveloperGuide