Eloqua Bulk API and Postman

The Eloqua Bulk API is very complex and – well to be honest – its documentation isn’t the best. But its also a very powerful API which allows you to import/export or filter bulks of data.

In this blogpost I will demonstrate a simple usecase for the Bulk API, how to test it and give some examples how to handle troubleshooting.

Every import / export with the Bulk API follows this pattern:

  1. Create an import / export defintion
  2. Moving the data to the staging area
  3. Moving the data to the final destination (synchronize the database )

When using this pattern you have the advantage of fast requests while other longer actions are performed asynchronously.

 

Testing the Bulk API with the „Postman“

The Postman is a very useful tool when it comes to creating and sending HTTP Requests for testing. It allows you to simply test requests without coding a single line, which makes API’s easier to understand for developers and non-developers.

Postman small

To work with the Bulk API we need to know which Base-URL our Eloqua Instance is referenced to. Getting this URL is pretty simple: We use a ‚GET‚ on the following URL „https://login.eloqua.com/id„. For the sake of simplicity I choose HTTP Basic Authorization to authenticate with Eloqua.

For HTTP basic authentication, each request must include an Authentication header with a Base64 encoded value. After clicking the second tab ‘Headers’ two inputfields appear, in the first we choose the kind of Header which is ‘Authorization’. In the second inputfield we have to enter “Basic” and a Base64 encoded String which has the following format:

siteName + \ + username + : + password
for example: Company\user.name:password

 

To easily Base64 encode this string search for „Base64 encoder„, our example looks like this: “Q29tcGFueVx1c2VyLm5hbWU6cGFzc3dvcmQ=”. Now copy the encoded String and paste it into the value-inputfield but write “Basic” in front of it.

Header: Authorization
Value: “Basic Q29tcGFueVx1c2VyLm5hbWU6cGFzc3dvcmQ=”

Finally hit the ‘Send’ button to send the request. The response should look like this:

So our BaseURL is “https://secure.p01.eloqua.com”. If you already know which API you want to use you can just select it from the response. In our case we want to use the Bulk API Version 2.0 therefor our URL is “https://secure.p01.eloqua.com/BULK/2.0/

After all this preparation, we are now ready to dive into our usecase: Importing new Contacts

 

1. Create an import / export defintion

 

The Import Definition is basically the mapping used by the Bulk API to match (y)our import with the existing fields in Eloqua.

First of all we need to set up the required Http method. In this case it’s a Http POST.
Just use the dropdownmenu and select “POST”.

Step two is to enter the Request URL which is a combination of the BaseURL “https://secure.p01.eloqua.com/BULK/2.0/”  and the endpoint “contacts/imports/”.

Postman Dropdown

The third step is to add a second header: Content-Type with the value: “application/json”.

Now we have two headers: the Authorization-Header and the Content-Type Header.

Header

In the last step we have to send our Import Definition within the body. Just click on the Body-tab, check the ‚raw‘-checkbox and paste it into the textfield.

 

Although a ’name‘ is required for every import it’s not needed or used again, so you shouldn’t worry about the name giving.

fields“ is the most important parameter of the Import Definition because it defines which fields in Eloqua will be mapped to the data we want to import. The „identifierFieldName“ should be a field in Eloqua which is unique to ensure that no wrong records get updated.

The option „isSyncTriggeredOnImport“ ensures that the import we POST into the staging area gets automatically synced into the Eloqua Database when the POST to the staging area is completed. So every one of our contacts will have a salutation, a firstname, a lastname and an emailaddress.

Now we hit the ’send‘-button and this is how it should look like:

Postman body & Response

 

2. Moving the data to the staging area

Now after successfully POSTing the Import Definition to Eloqua we need to POST the data we want to import. We need the „uri“ from our response of the Import Definition which is „/contacts/imports/144„. Just append the “/144” to our RequestURL.

Headers: Authorization  Value: “Basic Q29tcGFueVx1c2VyLm5hbWU6cGFzc3dvcmQ=”
  Content-Type Value: “application/json”

Finally paste our data json into the „Body„.

This time the response should be a „Http 204 No Content“ status message. If we get this response, the data is in the staging area and ready to be sychronized into the Eloqua Database.

 

3. Moving the data to the final destination

Now we are able to synchronize the data (If we would have set the option „isSyncTriggeredOnImport„:“true“ instead of „false“ the synchronization would be done automatically).

To sync the data we a POST on the following RequestURL: “https://secure.p01.eloqua.com/BULK/2.0/syncs

The Headers are still the same only the body changes to :

We should get a „201 Created“ Http status code and the response-body looks like this:

To ensure that everything worked out perfectly, we need to do one last request, a ‘GET’ request to check the „status„.

HttpMethod: GET
RequestURL: https://secure.eloqua.com/api/bulk/2.0/syncs/37
Headers: Authorization & Content-type

If everything worked right you get a response like this:

 

Troubleshooting

If the status is “warning” the reason could be a typo in your data json, for example when you send more data than you originally declared in the Import Definition. The most common errors are typos.

The correct data will be successfully imported while the not declared data will be ignored. Best practise should be to get an “success”-status instead of ignoring “warnings”.

You can check out the logs of the sync with another ‘GET’ request just append “/logs/” to the RequestURL.

logs

The response is a json which shows how the data went through every step.

In case of a “warning” or an “error” just copy the “statusCode” beyond it and check it against Eloquas Bulk Documentation, where all “Bulk Status Codes” are listed. (http://docs.oracle.com/cloud/latest/marketingcs_gs/OMCAC/APIRequests_EloquaStatusCodes.html)

Or maybe there was already an error with the request. For example instead of a “200 OK” status code we get a “404 Endpoint no found”. If the API fails to validate a request, it will respond with a validation error message describing the issue.

Postman Typo

It’s basically just another typo, so always make sure that you enter everything correct.

For all HTTP status codes you may encounter have a look at :
http://docs.oracle.com/cloud/latest/marketingcs_gs/OMCAC/APIRequests_HTTPStatusCodes.html

There are also explanations for “Validation Errors

Another very useful advantage of the Postman is its history where you can search for older requests. I often use an older request from my history and just edit and adapt it. That way I dont have to re-enter everything and Base64-encode my complete login-credentials again.

Postman History

 

The Eloqua Bulk API is very awesome. With a bit patience and by testing your usecases with the Postman, you can save a lot of time searching for errors in your own code. The Postman has a free basic version – in my opinion it’s perfectly adequate for testing API’s. There is also a “Cloud”-Version with some more features which costs monthly. There even will soon be a “Enterprise”-Version which includes some more feautures than the “Cloud”-Version.

 

Sources:
https://www.getpostman.com/
http://docs.oracle.com/cloud/latest/marketingcs_gs/OMCAB/index.html#Developers/Welcome.htm%3FTocPath%3D_____1

The following two tabs change content below.

Patrick Gastmann

Patrick beschäftigt sich als angehender Fachinformatiker im Fachbereich Anwendungsentwicklung vor allem mit den Herausforderungen und Möglichkeiten der Programmiersprache Java.

Neueste Artikel von Patrick Gastmann (alle ansehen)

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert.