Skip navigation
fsakr

Bulk API - .NET SDK

Posted by fsakr Aug 23, 2013

The results of our poll (Let's write some code together) are in and .NET came in second place! We're excited to announce that we've started a .NET SDK Project to help developers building on the Bulk API.

 

The project is open source and currently supports the following operations :

  • Contact Exports
  • Contact Imports
  • Custom Object Exports
  • Custom Object Imports
  • Account Exports
  • Account Imports

 

This is an open source project and we encourage contributions from the community. The project is available on Github or you can clone it from : fredsakr/eloqua-csharp-sdk · GitHub

 

The Winter release is scheduled to include support for Exporting Activity Data and we'll aim to have it supported by this client on Day 1.

 

Usage

 

Create Client

var info = BulkClient.GetAccountInfo(site, user, password);
var client = new BulkClient(site, user, password, info.Urls.Apis.Rest.Bulk);


 

Search Assets

List<ContactFilter> filters = _client.ContactFilters.Search(searchTerm, page, count);


 

Create Export

Export export = new Export
{
    name = "sample export",
    fields = fields,
    filter = filter,
    secondsToAutoDelete = 3600,
    secondsToRetainData = 3600,
};

var exportResult = client.ContactExport.CreateExport(export);

Sync sync = new Sync
            {
                status = SyncStatusType.pending,
                syncedInstanceUri = exportResult.uri
            };
var syncResult = _client.ContactExport.CreateSync(sync);

var data = _client.ContactExport.GetExportData(exportResult.uri);


 

Please note that these libraries are not written or supported by Eloqua. Questions about these libraries can be directed to the author on Github or here on Topliners.

 

We hope that you find this helpful and please let us know if you have any questions.

 

Thanks,

Fred

fsakr

Bulk API - Java SDK

Posted by fsakr Aug 15, 2013

Attention developers - the results of our poll (Let's write some code together) are in and a majority of people are looking for Java! We're excited to announce that we've started a Java SDK project to help developers building on the Bulk API. The project is open source and currently supports the following operations :

  • Contact Exports
  • Contact Imports
  • Custom Object Exports
  • Custom Object Imports
  • Account Exports
  • Account Imports

 

Grab a copy from Github and check for updates.

 

Create Client

AccountInfo info = BulkClient.GetAccountInfo("site", "user", "password");
BulkClient client = new BulkClient("site", "user", "password", info.urls.apis.rest.bulk);




 

Search

SearchResponse<Field> fields = client.ContactFieldClient().Search(searchTerm, page, count);

 

 

Contact Export

// instantiate a new instance of the client
// String baseUrl = BulkClient.GetAccountInfo(site, user, password);
BulkClient client = new BulkClient("site", "user", "password", "https://secure.eloqua.com/API/Bulk/1.0");

// define the list of fields to be included in the Export
// use : client.ContactFieldClient().Search(searchTerm, page, pageSize)
HashMap<String, String> fields = new HashMap<String, String>();
fields.put("C_EmailAddress", "{{Contact.Field(C_EmailAddress)}}");
fields.put("C_FirstName", "{{Contact.Field(C_FirstName)}}");

// define the filter criteria for the export
// use : client.ContactFilterClient().Search(searchTerm, page, pageSize)
ExportFilter filter = new ExportFilter();
filter.filterRule = FilterRuleType.member;
filter.membershipUri = "/contact/segment/4268";

// create the definition for the Export
Export export = new Export();
export.name = "sample export";
export.fields = fields;
export.filter = filter;
export.secondsToAutoDelete = 3600;
export.secondsToRetainData = 3600;

Export exportResult = client.ContactExportClient().CreateExport(export);

// create the sync for the Export
Sync sync = new Sync();
sync.status = SyncStatusType.pending;
sync.syncedInstanceUri = exportResult.uri;

// check Sync results (use polling)
Sync syncResult = client.ContactExportClient().CreateSync(sync);

// retrieve the data
Data data = client.ContactExportClient().GetExportData(exportResult.uri);



 

Response

A sample response for this call :

{
  "values": [
    {
      "C_FirstName": "Fred",
      "C_EmailAddress": "fred.sakr@oracle.com"
    },
    {
      "C_FirstName": "T.J.",
      "C_EmailAddress": "tj.fields@oracle.com"
    },
    {
      "C_FirstName": "Modern",
      "C_EmailAddress": "modern.mark@e..."
    ..}
  ]
}

 

 

The Winter release is scheduled to include support for Exporting Activity Data and we'll aim to have it supported by this client on Day 1.

 

Please note that these libraries are not written or supported by Eloqua. Questions about these libraries can be directed to the author on Github or here on Topliners.

We hope that you find this helpful and please let us know if you have any questions.

 

Thanks,

Fred

To ensure a faster resolution time on API related cases that get submitted to Eloqua support, it would be helpful if you can provide the following information when you first submit the case:

1) An explanation of the use-case or business objective and end goals that you're hoping to achieve using API.

Eg: You might want to import data from an external system to Eloqua. It would be helpful to touch on why you want to bring the data to Eloqua and what you want to do with it. Again, this is all on a high-level to help us understand your use-case and keep it in mind as we're devising technical solutions.

 

2) Whenever possible, try to determine if the issue is an API issue or whether the API is just bringing the issue to the surface.

Eg: You're importing data cards to Eloqua through API but the datacards services are not running. It would be helpful to see if you can create a data card manually directly through the App and see if the datacard services run. If they don't, then this would confirm that the issue is not API related.

 

3) Once you think that the issue is API related, the two most important pieces of information are the REQUEST AND RESPONSE header and bodies. What we're interested in here is not so much your Java or C# code that's executing the API calls but rather the API request that gets sent to Eloqua as a result of the code execution - or whatever method you're using to execute these API calls. One good way to get that request header and body is to run a web tool called Fiddler that would allow you to monitor the traffic on your computer -- including the API calls. You can drag and drop a call from the left side of the window to the composer tab and see the Request header and body. You can also monitor the response header and body that way too. Another tool that can be helpful too is Firebug which is an add-on on firefox. The response code result -- 200, 400, 403, along with the exact message are very important as well.

8-14-2013 2-03-12 PM.png

 

4) It's also important for support to have an understanding of: How long has the issue been occurring for? When did it start? Is it intermittent or does it occur all the time? When was the last time that the client you were able -- if ever, to run a similar request successfully?

 

5) Please provide us with a sense of the business impact that this issue is having on your operations

 

6) For authentication/privileges issues, ensure that the user has the API security Group and that the credentials are valid. You can verify whether the credentials are valid by attempting to login to the application -- using the API user credentials, the same way any Eloqua user would.

 

With all this information provided in the case, you will ensure that your case gets routed quickly to the appropriate resources at the support team and get the attention and action needed in a timely manner.

Thanks,

Tarek

The Rest API provides access to create and retrieve External Activities for known contacts. For more information on External Activities, see the following Summer Release Notes.

 

Accessing External Activities

  • GET :  /data/activity/{id}

 

Response

The response for this call looks as follows :

 

{
  "type": "ExternalActivities",
  "id": "35",
  "depth": "complete",
  "name": "Eventbrite",
  "activityDate": "1362543780",
  "activityType": "Registration",
  "assetName": "Eventbrite",
  "assetType": "Event",
  "contactId": 44891
}

 

Properties

 

Name

Type

Description

Notes

Validations

type

"ExternalActivities"

activityDate

integer

The date of the activity

DateRequirement

activityType

string

The type of activity

EnumRequirement

assetName

string

assetType

string

contactId

integer

The id of the contact who performed the activity

IdRequirement

campaignId

integer

The id of the contact associated with this activity

id

string

The unique identifier of the activity

 

Related Operations

  • POST :  /data/activity

 

We hope that you find this helpful and please let us know if you have any questions.

 

Thanks,

Fred

The table below shows the limits for different methods of importing/uploading data to Eloqua

Upload/Import TypeSize allowed
REST API 1.0500MB
BULK API32MB -- pages, or 50k records
SOAP API64MB -- RAW envelope size limit, no file size limit
Data Cards Upload Wizard500MB
Contact file Upload Wizard500MB
SFTP/FTP based AutosynchsNo Limit
Autosynchs - Get Contacts, etc..No Limit
Content upload - PDF Document, files10MB
Images50MB
Call Script, Fax Document, Call Center Batch -- Only applicable to E910MB
HTML Content for Landing Pages10MB

Notice from the table above that all wizard-based uploads have a limit of 500MB

We are pleased to announce that a new version of our Rest Client is now available via NuGet. And sources, documentation as well as a community site are now hosted on Codeplex.


Documentation | Community

 

 

For anyone currently using the sources on Github, note that we’ll continue to maintain both sites, but NuGet will be the recommended source for using the client in your own projects.


Getting the C# Rest Client Library using NuGet

  1. Using the NuGet Package Manager Console :
    • Install-Package Eloqua.Api.Rest.ClientLibrary
  2. Using Visual Studio 2012
    • Right-click on the project's references
    • Select "Manage NuGet Package..."
    • Search for "Eloqua Client Library"

 

There are two versions of the Rest API Client – note that the Eloqua.Api.Rest.ClientLibrary is the current version and EloquaClient is the original work. Please use Eloqua.Api.Rest.ClientLibrary going forward.

 

 

We hope that you find this helpful and please let me know if you have any questions.


Thanks,

Fred

 

Disclaimer

Please note that these are my own tools and are meant to help developers build on the Eloqua platform and while I am happy to answer questions and provide support, note that Eloqua is not responsible for and cannot support this product.