View
784
Download
2
Category
Tags:
Preview:
Citation preview
© 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
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.
2 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
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.
3 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
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:
4 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
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.
5 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
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();
6 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
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
7 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
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
8 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
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
9 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
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.
10 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
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.
11 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
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.
12 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
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
13 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
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:
14 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
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.
15 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
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
16 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
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.
17 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
• 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
18 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
19 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
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
Eloqua® Web Services API v1.2 Developer Guide
• 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:
20 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
> 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.
21 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
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:
22 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
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();
23 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
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
24 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
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);
25 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
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()); }
26 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
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 =
27 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
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
28 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
Sample Code – Java
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
29 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
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
30 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
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", "support@eloqua.com");
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 }
31 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
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("support@eloqua.com"); emailField. fieldValueCollection.getEntityFields().add(emailField); // Add the EloquaSservice fieldValueCollection.getEntityFields().add(
Note: Java code sample concluded on next page.
32 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
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()); }
33 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
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[]
aults nexpectedErrorFault
nvalidTypeFault
yntax
Service instance; EntityType entityType; int[] ids; String[] fieldList; DynamicEntity[] returnValue;
List); returnValue = instance.Retrieve(entityType, ids, field
34 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
Sample Code - .NET
Note: .NET code sample concluded on next page.
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
35 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
Sample Code - .NET (continued)
S
{ // Customize your own Error handling code.
eson: {0}", ex.Reason.ToString()));
()));
tch (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} ca{ // Customize your own Error handling code. Console.WriteLine(St}
ample Code – Java
try { // Set up the Eloqua API Service
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 {
}
Note: Java code sample concluded on next page.
36 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
Sample Code – Java (continued)
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()); }
37 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
Syntax
S
le concluded on next page.
Service instance; DynamicEntity[] dynamicEntities; UpdateResult[] returnValue;
returnValue = instance.Update(dynamicEntities);
ample Code - .NET
try { // Set up the Eloqua API Service
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", "support@eloqua.com");
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
38 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
Sample Code - .NET (continued)
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
try { // Set up the Eloqua API Service
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
39 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
Sample Code – Java (continued)
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("support@eloqua.com"); 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()); } }
40 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
Sample Code – Java (continued)
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);
41 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
Sample Code - .NET
try { // Set up the Eloqua API Service EloquaService.EloquaServiceClient service = new EloquaService.EloquaServiceClient();
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)
Console.WriteLine("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 }
42 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
Sample Code – Java
try { // Set up the Eloqua API Service EloquaService.Eloqua eloquaService = new EloquaService.Eloqua(); EloquaService.EloquaService service = eloquaService.getEloquaService(); // Instantiate a new Eloqua Service object factory
ory = new EloquaService.ObjectFactory();
Entity Type object yType = new EloquaService.EntityType();
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) {
43 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
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[]
44 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
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
45 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
Sample Code - .NET (continued)
// 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}
46 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
Sample Code – Java
Note: Java code sample conclued on next page.
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()));
47 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
Sample Code – Java (continued)
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.
48 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
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();
49 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
Sample Code - .NET
Sample Code – Java
try { // Set up the Eloqua API Service EloquaService.EloquaServiceClient service = new EloquaService.EloquaServiceClient(); service.ClientCredentials.UserName.UserName = "Company\\default.user"; service.ClientCredentials.UserName.Password = "test123"; // Execute the request EloquaService.ListAssetTypesResult result = service.ListAssetTypes(); // Extract the name of each Asset Type foreach (String AssetType in result.AssetTypes) { Console.WriteLine(AssetType); } }
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 {
50 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
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
aults nexpectedErrorFault alidationFault
ynta
Service instance; String entityName; DescribeAssetTypeResult returnValue;
instance.DescribeAssetType(assetType); returnValue =
51 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
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}
52 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
Sample Code – Java
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
53 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
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
54 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
Sample Code – Java
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}
55 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
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[]
aults nexpectedErrorFault alidationFault
yntax
Delete
Service instance; DynamicAsset[] dynamicAssets; CreateAssetResult[] returnValue; returnValue = instance.CreateAsset(dynamicAssets);
56 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
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.
57 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
Sample Code - .NET (continued)
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}
58 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
Sample Code – Java
Note: Java code sample concluded on next page.
try { // Set up the Eloqua API Service
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);
59 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
Sample Code – Java (continued)
Note: Java code sample concluded on next page.
// 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
60 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
Sample Code – Java (continued)
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");
Failed requests return a ‐1 integer value for ID
System.out.println("Failure");
}
ch (javax.xml.ws.soap.SOAPFaultException ex)
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
61 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
Faults UnexpectedErrorFault VIBatchSizeExceededFault
S
alidationFault nvalidTypeFault
yntax
Service instance; AssetType assetType;
int[] ids;String[] fieldList;
e = instance.RetrieveAsset(assetType, ids, fieldList); DynamicAsset[] returnValue; returnValu
62 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
Sample Code - .NET
Note: .NET code sample concluded on next page.
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];
63 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
Sample Code - .NET (continued)
S
{ // Customize your own Error handling code.
eson: {0}", ex.Reason.ToString()));
()));
tch (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} ca{ // Customize your own Error handling code. Console.WriteLine(St}
ample Code – Java
try { // Set up the Eloqua API Service
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 }
Note: Java code sample concluded on next page.
64 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
Sample Code – Java (continued)
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[]
aults nexpectedErrorFault
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) { de. // Customize your own Error handling co System.out.println(ex.getMessage()); }
65 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
Syntax
S
cluded on next page.
Service instance; DynamicAsset[] dynamicAssets; UpdateAssetResult[] returnValue;
returnValue = instance.UpdateAsset(dynamicAssets);
ample Code - .NET
try { // Set up the Eloqua API Service
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
66 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
Sample Code - .NET (continued)
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 )
Console.WriteLine("Success"); }
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
try { // Set up the Eloqua API Service
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
67 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
Sample Code – Java (continued)
Note: Java code sample conclued on next page.
// 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()); } }
}
68 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
Sample Code – Java (continued)
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[]
aults nexpectedErrorFault alidationFault
atchSizeExceededFault
yntax
Service instance; assetType; assetType
int[] ids; DeleteAssetResult[] returnValue; returnValue = instance.DeleteAsset(assetType, ids);
69 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
Sample Code - .NET
try { // Set up the Eloqua API Service EloquaService.EloquaServiceClient service = new EloquaService.EloquaServiceClient();
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) {
70 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
Sample Code – Java
try { // Set up the Eloqua API Service EloquaService.Eloqua eloquaService = new EloquaService.Eloqua(); EloquaService.EloquaService service = eloquaService.getEloquaService(); // Instantiate a new Eloqua Service object factory
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())
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 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.
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) {
71 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
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[]
aults nexpectedErrorFault
nFault alidationvalidTypeFault
yntax
Service instance; DynamicEntity entity;
DynamicAsset[] returnValue; returnValue = instance.ListGroupMembership(entity);
72 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
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}
73 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
Sample Code – Java
try { // Set up the Eloqua API Service EloquaService.Eloqua eloquaService = new EloquaService.Eloqua(); EloquaService.EloquaService service = eloquaService.getEloquaService(); // Instantiate a new Eloqua Service object factory
ory = new EloquaService.ObjectFactory();
Entity Type object yType = new EloquaService.EntityType();
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
74 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
Faults UnexpectedErrorFault ValidationFault III
S
nvalidTypeFault nvalidAssetFault nvalidEntityFault
yntax
Service instance; DynamicEntity entity;
DynamicAsset asset;GroupMemberResult returnValue; returnValue = instance.AddGroupMember(entity, asset);
75 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
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
76 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
Sample Code – Java
try { // Set up the Eloqua API Service EloquaService.Eloqua eloquaService = new EloquaService.Eloqua(); EloquaService.EloquaService service = eloquaService.getEloquaService(); // Instantiate a new Eloqua Service object factory
ory = new EloquaService.ObjectFactory();
Entity Type object yType = new EloquaService.EntityType();
entityType.setName(serviceFactory.createEntityTypeName("Contact"));
antiate a new Dynamic Entity of type Contact and supply the EntityID 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.
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) {
77 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
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
Service instance; DynamicEntity entity;
pMemberResult returnValue; nce.RemoveGroupMember(entity, asset);
DynamicAsset asset; GroureturnValue = insta
78 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
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
79 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
Sample Code – Java
try { // Set up the Eloqua API Service EloquaService.Eloqua eloquaService = new EloquaService.Eloqua(); EloquaService.EloquaService service = eloquaService.getEloquaService(); // Instantiate a new Eloqua Service object factory
ory = new EloquaService.ObjectFactory();
Entity Type object yType = new EloquaService.EntityType();
entityType.setName(serviceFactory.createEntityTypeName("Contact"));
antiate a new Dynamic Entity of type Contact and supply the EntityID 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.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.
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) {
}
80 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
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
81 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
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);
82 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
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}
83 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
Sample Code – Java
try { // Set up the Eloqua API Data Transfer Service EloquaDataService.EloquaDataTransfer eloquaService = new EloquaDataService.EloquaDataTransfer(); EloquaDataService.DataTransferService service = eloquaService.getEloquaDataTransferService(); // Instantiate a new Eloqua Data Transfer Service object factory
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",));
System.out.println(String.format("Fault Code: %s", ex.getFault().getFaultCode()));
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
84 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
DataExportStatus Usage
R
AAssetType
RD
FUV
S
etrieve the status of a Data Export execution.
rguments
esponse ataExportExecutionStatus
aults nexpectedErrorFault alidationFault
yntax
Service instance; AssetType assetType; taExportExecutionStatus returnValue; Da
returnValue = instance.DataExportStatus(assetType);
85 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
86 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
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
Eloqua® Web Services API v1.2 Developer Guide
Sample Code – Java
See Also
InitializeDataExport
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
tory = new EloquaDataService.ObjectFactory();
ort Asset Type object new EloquaDataService.AssetType();
assetType.setName(serviceFactory.createAssetTypeName("Sample Data Export")); eFactory.createAssetTypeType("DataExport"));
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");
ch (javax.xml.ws.soap.SOAPFaultException ex)
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
87 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
Response Byte[]
FUV
S
aults nexpectedErrorFault alidationFault
yntax
Service instance; AssetType assetType; Byte[] returnValue;
returnValue = instance.GetDataExportFile(assetType);
88 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
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";
89 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
Sample Code – Java
try { // Set up the Eloqua API Data Transfer Service EloquaDataService.EloquaDataTransfer eloquaService = new EloquaDataService.EloquaDataTransfer(); EloquaDataService.DataTransferService service = eloquaService.getEloquaDataTransferService(); // Instantiate a new Eloqua Data Transfer Service object factory
tory = new EloquaDataService.ObjectFactory();
ort Asset Type object new EloquaDataService.AssetType();
assetType.setName(serviceFactory.createAssetTypeName("Sample Data Export")); eFactory.createAssetTypeType("DataExport"));
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();
System.out.println(String.format("Fault Code: %s", ex.getFault().getFaultCode()));
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. }
90 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
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);
91 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
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}
92 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
Sample Code – Java
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 }
93 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
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
94 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
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) {
95 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
Sample Code – Java
try { // Set up the Eloqua API Data Transfer Service EloquaDataService.EloquaDataTransfer eloquaService = new EloquaDataService.EloquaDataTransfer(); EloquaDataService.DataTransferService service = eloquaService.getEloquaDataTransferService(); // Instantiate a new Eloqua Data Transfer Service object factory
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()));
// Customize your own Error handling code. System.out.println(ex.getMessage()); }
System.out.println } catch (Exception ex) {
96 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
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.
97 866 327 8764 · www.eloqua.com © 2008 Eloqua Corporation
Eloqua® Web Services API v1.2 Developer Guide
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.
Recommended