Using Eloqua WS API with Java - Series Introduction 

 

 

 

This three part series we will walk through using the Eloqua WS API with Java and related technologies. The goal of the series is to show with the choice of a few simple examples the approach to working with the API to complete some simple tasks, along with making sure we avoid some problems that might occur. 

The series will be broken down as follows

1. Basic setup and getting started

2. Simple API usage scenarios.

3. Working with emails and deployments

Part 1 - Basic Setup and Usage:


In this tutorial of working with the Eloqua WS API in Java we will utilize the Axis2 library and related modules along with Eclipse as the IDE.

Developer Pre-Requisites

 

We will begin by first making getting all the tools and technologies that are being used in this tutorial. Please ensure that you have all the right pieces downloaded and in place before we begin to avoid issues later in the tutorial.

 

Tools and technologies

 

The Java Web Service Client will be built using Apache Axis2 and Apache Rampart. To facilitate the development of the client the Eclipse IDE will be used along with a Axis2 specific Eclipse plug-in.

The samples that will be built shall be setup as simple Console applications to make it very easy to test them; the code, however, can be used in any deployment topology including web application.

Installation and setup

 

Java SE 6 Update 24

Download and install the latest Java SE 6 JDK.

 

 

 

Eclipse IDE for Java Developers ( Helios SR2 )

image001.png

Download and install (extract) the Eclipse IDE on your computer. Please make note of the directory where you have installed it.

Note If you already have any other version of the Helios release that will work as well - we will install the required plug-in later.

 

 

Apache Axis2/Java

 

Download and install the latest version of the Axis2/Java release, the Binary Distribution will be all that is needed. Follow instructions provided.

 

Axis2/Java - Version 1.5.4

 

 

Apache Rampart Module

 

Download and extract the latest version of the Rampart module, the Binary Distribution will be all that is needed. Follow instructions provided.

 

Apache Rampart - Version 1.5.1

 

 

Code Generator Wizard - Eclipse Plug-in

 

Download and install the Code Generator Eclipse Plug-In for Axis2.

  1. Download the ZIP file for the plugin you want to install.
  2. Extract      the content of the plugins folder in      the ZIP archive into the dropins folder      (i.e. do not create a plugins folder      under dropins).

 

Note: Restart eclipse to ensure that the plug-in gets loaded successfully.

 

To ensure that the plug-in has successfully do the following:

 

1. Start Eclipse

 

2. Select File --> New --> Other

image002.png

 

If Axis2 Wizards shows up as shown above then the plug-in is ready to use. If it does not show up please ensure that the jar file is in the correct location and restart Eclipse if necessary.

 


 

Getting Started

In this section we shall start with generating the WS Clients and then configure Axis2 to ensure that we are able to connect to the Eloqua WS API.

Before starting please make sure that the you valid credentials ( username / password ) for an Eloqua User that has been granted the API access.

Generate WS Clients

 

To generate the WS Client the first step is to create a new project in Eclipse.

 

File --> New --> Project --> Java Project

 

image003.png

 

Name the project ( I chose EloquaWSClient )and click Finish

 

image004.png

Right click on the new project and then select New --> Other--> Axis2 Code Generator

 

 

 

 

image005.png

 

The client will be created from a WSDL so make the selection and click Next.

 

image006.png

 

Enter the Eloqua Service URL  https://secure.eloqua.com/API/1.2/Service.svc?wsdl and click Next

image007.png


 

Next select Custom as the Codegen option.

 

image008.png

Change the package name of the client to something that does not contain _1._2

 

 

Select Generate Sync Style only and then click Next

 

 

image009.png

 

First select to browse and select a project from the workspace and then click Browse and find the project you just created.

 

image010.png

Check the option to add the Axis2 codegen jars

 

image011.png

Check the option to add Axis2 libraries to the codegen result project. Once you click browse you will have to point to the location where the Axis2 libraries were installed. Click Check Libs to make sure the libraries are found.

 

image012.png

 

Finally click Finish and the client code should be generated.

 

image013.png

 

Configure Eclipse Project

 

Once the code has been generated the next step is to ensure that the Eclipse Project that was created will have the correct build path setup.  First ensure that the source files for the clients are in the project src directory.

 

image014.png

NOTE: Don't worry if it's all red - we will fix it next with the build path.

 

Next select the project and choose Build Path --> Configure Built Path

 

image015.png

 

Next select the Libraries tab and choose to Add Jars... then from the lib folder select all the jar files and click OK

 

image016.png

 

If project is already setup for Build Automatically just wait a few seconds and you will see all the compiler errors will be gone!

 

NOTE - If you have installed Apache Rampart correctly you will see at the very least the Rampart Jars.

 

image017.png

 

If these are not present the following steps will have to be done:

 

Step 1.  Open the folder in which Apache Rampart was installed and select all jar files in the lib directory.

image018.png

Step 2. Copy these jar files into the lib folder of your eclipse project and then go through the Build Path steps to include these in the project as well.

 

Connecting to Eloqua WS API

 

First we will start with a simple console application to make sure that we can connect to the Eloqua WS API. To do so first we create a simple Java Class, select the project and choose to create a new class:

 

image019.png

Next enter the name of the package and class and click Finish.

 

image020.png


 

The content of this file will be

 

package com.eloqua.sample;

import org.apache.axis2.client.Options;
import org.apache.axis2.client.ServiceClient;
import org.apache.axis2.context.ConfigurationContext;
import org.apache.axis2.context.ConfigurationContextFactory;
import org.apache.log4j.BasicConfigurator;
import com.eloqua.secure.api.EloquaStub;
import com.eloqua.secure.api._1_2.ListAssetTypes;

public class WSConsoleClient {

                public static void main(String[] args) throws Exception 
                {
                                // To debug the this line will set Log4J to use System.Out for a lot of messages.
                                //BasicConfigurator.configure();
                                // Configure your username and password here.
                                String company = "   ";
                                String username = "   ";
                                String password = "   ";
                                // Assuming that the conf directory has the Axis2 config file and Rampart is installed correctly.
                                ConfigurationContext ctx = ConfigurationContextFactory.createConfigurationContextFromFileSystem("D:\\Apache\\axis2-1.5.4\\conf", null);

                                EloquaStub stub = new EloquaStub(ctx,"https://secure.eloqua.com/API/1.2/Service.svc");
                                ServiceClient sc = stub._getServiceClient();
                                Options options = sc.getOptions();

                                sc.engageModule("rampart");

                                options.setUserName(company +"\\"+username);
                                options.setPassword(password);

                                String[] assetTypes = stub.listAssetTypes(new ListAssetTypes()).getListAssetTypesResult().getAssetTypes().getString();
                                System.out.println("Asset Types count : " + assetTypes.length);
                                for ( String s : assetTypes)
                                {
                                                System.out.println(" -> " + s);                                                    
                                }
                }
}

 

Make sure of the following:

1. The login credentials are added correctly.

2. The location of the Apache Axis2 Configuration file is set correctly.

 

image021.png

 

3. It is VERY important to ensure security works that Apache Rampart was correctly added; in particular the modules directory of your Apache Axis2 installation MUST have the rampart MAR file.

 

image022.png

 

If this file is NOT present please go back and install Apache Rampart with the installation instructions.

 

Running the code

 

To run the sample simply select the file you just created and then select Run As --> Java Application

image023.png

 

 

In the Console you should see the following output:

log4j:WARN No appenders could be found for logger (org.apache.axiom.om.util.StAXUtils).

log4j:WARN Please initialize the log4j system properly.

Asset Types count : 10

-> DataExport

-> DataImport

-> Email

-> EmailHeader

-> EmailFooter

-> ContactGroup

-> CompanyGroup

-> ProspectGroup

-> Form

-> None

 

Congrats - you are now using the Eloqua WS API!

Next Steps

 

Having completed the steps above you should be able to now run all the other WS API calls by using the documentation provided.