Integrating ColdFusion with Taleo TBE WebAPI

Integrating with a web service should be easy right? But what happens when the WSDL files generated by the web service are invalid? How do you integrate then? Well, this is the story of my integration attempts with Taleo TBE.

Firstly, Taleo have resource on their website that carries all the documentation and it even has a Java Toolkit containing some pre-prepared jar files that should make life easier if you are integrating using the Java platform. But hey, we wont need the Java Toolkit because we have ColdFusion and <cfinvoke> so we should be able to refer to the documentation and knock up an API wrapper in an hour or so. Or can we?

The first problem comes on pages 9 and 10 of the September 2009 release of the documentation. It states that we should use the following two URLs to integrate with TBE.

1. DispatcherAPI: http://tbe.taleo.net/wsdl/DispatcherAPI.wsdl
2. WebAPI: http://tbe.taleo.net/wsdl/WebAPI.wsdl

It then goes on to state that the initial call to the Dispatcher should always be made to the following address https://tbe.taleo.net/MANAGER/dispatcher/servlet/rpcrouter and the URL it returns should be used for all subsequent requests.

The URL returned by the Dispatcher looks like this:

https://tbe.taleo.net/NAxxx/ats/services/rpcrouter

Where xxx is a number e.g. 1, 2, 5 or 6 etc.

So there is the first problem. The web service URLs are defined at a different address to the web services themselves.

This is not a problem you may think but, in this case, it is. I attempted to create the web services by bypassing the first two addresses and using the latter two by appending ?wsdl to them and seeing what I got. It appeared that this would be successful as both URLs returned WSDL files in my browser so I built my <cfinvoke> calls using the following 2 URLs:

1. DispatcherAPI: https://tbe.taleo.net/MANAGER/dispatcher/servlet/rpcrouter?wsdl
2. WebAPI: https://tbe.taleo.net/NA6/ats/services/rpcrouter?wsdl

Here is where the fun begins...

Using the "new" DispatcherAPI URL here generates the following error:

WSDLException (at /html): faultCode=INVALID_WSDL: Expected element '{http://schemas.xmlsoap.org/wsdl/}definitions'

Ok, lets try the "new" WebAPI URL...

java.io.IOException: Type {http://www.w3.org/2001/XMLSchema}EmployeeBean is referenced but not defined.

So we have two WSDL files that are valid but of little to no use to us when using <cfinvoke> and two other WSDL URLs that generate invalid WSDL files.

So where do we go from here?

The official line from Taleo is that the only WSDL files that are supported are the two referenced at the beginning of this post:

1. DispatcherAPI: http://tbe.taleo.net/wsdl/DispatcherAPI.wsdl
2. WebAPI: http://tbe.taleo.net/wsdl/WebAPI.wsdl

But the second URL cannot be used directly to integrate with as we have to use the URL returned by the DispatcherAPI to integrate with the particular account on Taleo TBE which could be on a number of different URLs.

I figured that I may as well take a look at the Java Toolkit so I downloaded it and unzipped it, looking at the docs. I determined that I only needed the tbe.jar file that is supplied and placed it in my ColdFusion class path and restarted ColdFusion.

A little bit of code later and I had an idea that this could work. Then I hit another problem. The tbe.jar supplied with the JavaToolkit has an internal structure of com.rf.ats.services.integration.webserv.CLASS and attempting to interface with the web service using this tbe.jar results in an error stating that the classes are mismatched. The web service is expecting classes with the structure of TBEWebAPI.CLASS.

So after a little bit of thinking, I cleared out the stub files and deleted the webservices from the CF stubs folder and Admin area respectively and then I used <cfinvoke> on the two officially supported URLs (You could also use the WSDL2Java executable that ships with ColdFusion to do this.). I watched the stubs folder and saw two new directories appear. One of the folders contained a folder called TBEWebAPI and it was full of class files. Promising!

I zipped up the TBEWebAPI folder and renamed it as a jar file, stopped ColdFusion, dropped the jar file into the CF class path and restarted the server.

The new jar file worked. I had the correct class names and I was able to login by accessing the methods in the jar file directly and completely bypassing <cfinvoke>.

<!--- create the dispatcher --->
<cfset taleoDispatcher = createObject("component", 
			"cfc.com.taleo.dispatcher").init()>

<!--- get the endpoint URL --->
<cfset endpointURL = taleoDispatcher.getURL(organization)>

<cfset javaURL = createObject("java", "java.net.URL").init(endpointURL)>

<cfset WebAPISL = createObject("java",
			 "TBEWebAPI.IWebAPIServiceLocator")>
<cfset WebAPI = WebAPISL.getrpcrouter(javaURL)>


<cfset SessionID = WebAPI.login(organization, username, password)>

<cfdump var="#SessionID#">

<cfdump var="#WebAPI#">

So there you have it. A successful login to Taleo's TBE ATS platform without using <cfinvoke> to access the web service. But unless you run your own servers or have a very understanding CF host that will allow you to add .jar files to the ColdFusion class path, the integration of Taleo's TBE and ColdFusion is not going to happen any time soon.