How-To: Using a custom Java class in UCCX 5.x (SOAP Example)

[Anthony Holloway]

Update: Due to the loss of dropbox, the links to dropbox offline project are no longer active.  Please use this awesome document as your new reference:

https://supportforums.cisco.com/document/97736/uccx-8x-really-simple-soap-client-no-custom-jar

Update:  Due to a server failure, the links to http://www.avholloway.com/ are no longer active.  Please download the offline project.

This tutorial can be viewed in its entirety on my web site:

http://www.avholloway.com/vtools/ipcc/custom-java/soap/

The first thing we need to do is find out what version of Java is our server running, this way we know which version of Java to compile in.

This document outlines the JRE (Java Runtime Environment) version compatibility with all versions of CRS:

"Cisco Customer Response Solutions (CRS) Software and Hardware Compatibility Guide" - June 16, 2008

http://www.cisco.com/en/US/docs/voice_ip_comm/cust_contact/contact_center/crs/express_compatibility/matrix/crscomtx.pdf

According to that document, my version of CRS, v5.0(1) SR2, uses JRE 1.5.0.  So I will go to Sun's site and download the JDK (Java Development Kit) for that version.

Alternatively, you could determine the Java version right on the CRS server itself.  Though, there could be multiple JRE's installed, and the CRS Engine uses only the one listed in the above document.

Sun's page for previous JDK versions:

http://java.sun.com/javase/downloads/previous.jsp

I would typically install the JDK and JRE for 1.5.0 on my personal computer and not on the server.  This way I can do all of my Java testing offline, making sure it all works, before even uploading it to the server.  I did one additional, and optional, thing to make developing easier.  I added the bin directory to my path variable so I can execute the necessary Java commands from any directory.  This is outlined in the installation instructions, which can be found on the JDK download page.

So now we have our development environment setup.  Yep, all we needed was the JDK, and the JRE, the only other tool we'll use it already on every system; a text editor.  I will use TextEdit on my Mac for this example, but you could easily use Notepad on Windows, or nano on Linux.

I will not get into the details of writing Java apps/classes, so for the purpose of this tutorial I will offer my simple SOAP class to you.

Disclaimer: I am not a Java programmer.  In fact, this is my very first program in Java, and I learned just enough for this task.

Browseable link: http://www.avholloway.com/vtools/ipcc/custom-java/soap/SimpleSOAP.java.txt

Download link: http://www.avholloway.com/vtools/ipcc/custom-java/soap/SimpleSOAP.java

Now, we need to compile our source code into byte code so the JRE can execute it.  Compiling the .java file will result in a new file of the same name, but with the .class extension on it.

http://www.avholloway.com/vtools/ipcc/custom-java/soap/compiling-SimpleSOAP.png - Command Prompt>javac SimpleSOAP.java

Now we need to test this new class to see if it works before we add the complexity of the CRS environment.

Let's create another Java file, and this one will utilize our newly created class.

Browseable link: http://www.avholloway.com/vtools/ipcc/custom-java/soap/RunMyCode.java.txt

Download link: http://www.avholloway.com/vtools/ipcc/custom-java/soap/RunMyCode.java

Now we compile that source code so it can also be ran.

http://www.avholloway.com/vtools/ipcc/custom-java/soap/compiling-RunMyCode.png - Command Prompt>javac RunMyCode.java

Next we pass the RunMyCode class to the JRE like so (Note the absence of the .class or .java file extension):

http://www.avholloway.com/vtools/ipcc/custom-java/soap/running-RunMyCode.png - Command Prompt>java RunMyCode

Your output should look something similar to this:

Screen shot: http://www.avholloway.com/vtools/ipcc/custom-java/soap/running-RunMycode.png

Browseable link: http://www.avholloway.com/vtools/ipcc/custom-java/soap/soap-response.xml

OK, so if everything is working up to this point, it's safe to assume that our CRS server will be able to utilize our class as well.

[Nicolas Mansour]

Hi there,

I am trying to integrate these java classes with a custom built .NET web service. I haven't been able to get it to work with my web service but if i try the one on the net it works fine. Anyone has tried it and has any insight on the requirements of the web service?

The error i'm getting is:

java.io.IOException: Server returned HTTP response code: 500 for URL: http:///WebService/

Thanks in advance.

Nick

[Anthony Holloway]

Are you testing on your PC or in an script?

I would recommend testing on your PC before trying it in a script.

[Nicolas Mansour]

Hi,

I'm using just my pc.

i'm just compiling and trying to use it directly from command prompt.

I was able to find the specific error by sniffing my packets.

Here is the error:

"System.Web.Services.Protocols.SoapException: Unable to handle request without a valid action parameter. Please supply a valid soap action"

Any help will be appreciated.

Thanks in advance,

Nick

[Anthony Holloway]

I wont be able to help you because it sounds like it's a problem with your SOAP request, and the format of that XML document.

Not every SOAP request is built the same or has all of the same elements.

Double check your Web Service that you built and modify the SOAP request accordingly.

Best of luck.

[Stephen Earl]

Does anyone have any of the content mentioned in this post? The website, www.avholloway.com, appears to be down at this point in time.

If not, if anyone can point me in the direction of a developers guide for some of the java / UCCX stuff I certainly would appreciate it.

I'm a very experienced java engineer, I just have no experience integrating with UCCX.

Thanks,

Steve E.

[Anthony Holloway]

Sorry, my power supply died on my server. Actually, it's not even a real server, it's an HP Pavilion from like 1999 with 190MB of RAM and a 650MHz Celeron CPU.

http://dl.getdropbox.com/u/15705/Pictures/www.avholloway.com-server.jpg

Temporarily, you can download the .zip file for this tutorial here:

http://dl.getdropbox.com/u/15705/www.avholloway.com-soap-project.zip

[Anthony Holloway]

I have made some additional changes to the above ZIP file. Now it includes the screen shots, and can be viewed in a web page offline.

http://dl.getdropbox.com/u/15705/www.avholloway.com-soap-project-offline.zip

[raziel78kain]

Dear Anthony,

have you made a similar guide for UCCX 8.X, too?

Thanks and regards.

[Hythim Ali El Hadad]

Hi,

I need to check for these 3-point:

1. Why I upload the JAR file into the CRS as a document ?
you said to make use of its classes and methods ,, what is this mean and why I need this upload process and how I'll use the benifit of this step then ?

2. In my case I'll play IVR to the client,then get his ID and his choice, based on this, I'll contact a URL [web service] to get the required data and play them back to the customer
So I'll give the webservice a value to get some values based on it
So is what i need is called [calling a web service] ?
Also I found that I need
create URL document & create XML document then Get XML Document Data

the first one will take the URL,the second will query the webservice and the 3rd will get the needed variables
So why I would need the SET step that you have showed in your tutorial ? that I found the above 3-steps may be sufficient.

3. What is the supported webservice security in the IPCC ?

PLease correct me if I'm wrong

Thanks a lot for your time

[Clifford McGlamry]

Awesome post.

I have some stuff to add.  I've been working on this, and I've found some interesting things.  First of all, having an XPath visualizer that will allow you to see what is going to happen becomes critical.  It also lets you see when the namespace (xmlns) tags create a problem.  There is a free one out there that is awesome.  I downloaded it from here:

http://xpathvisualizer.codeplex.com/

Once I had this, I found that the problem that was breaking the query appears to be the XMLNS tag on the

GetCityWeatherByZIPResponse key.  Having the namespace on the initial tag doesn't appear to be a problem (it might be...still working through all this).

The question became how to get rid of the namespace tag in the response so it wouldn't mess things up.  We're not using it, and we're not passing it on, so it is safe to strip it out in this case.

I stripped out the offending tag by adding the following code to the bottom of the java class before it was compiled:

//original code in next two lines provided to show positioning

   wr.close();
   rd.close();

//   Following section is added to identify the string we want to strip.  I have to escape my " characters with a \ so that

//   they will be interpreted as part of the string

   String r = "xmlns=\"http://ws.cdyne.com/WeatherWS/\"";
     
   String rip = "";

   // we use the replace function to find the contents of string "r" and replace them with an empty string - ""

   //  The results go into another string variable "rip"
   rip=soapResponse.replace(r,"");

   //now we take our modified results, and push them back into our response variable

   soapResponse=rip;

//  Here we return you to the existing code - with one minor exception tagged below...

   return soapResponse;
  } catch (Exception exception) {
   return "OUCH";        //<<====   I added "OUCH" so I could tell if it was going to error handling (silly, but with no debugger, it works)
  }

This runs cleanly, and returns an XML document that can be successfully parsed...at least by the XPath Visualizer.  I'm going to work with it more in UCCX to check it's behavior there.  More once I work through it farther.

I've attached the modified SimpleSOAP.java class code.

Cliff

[Anthony Holloway]

Thanks for the enthusiasm here, it's nice to see another user actively making improvements.

Doing a simple string replace is fine, when there's a single piece to remove, but it's just duct tape.

Imagine if you had a much more complex SOAP response: e.g.,

http://schemas.xmlsoap.org/soap/envelope/" S

OAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">

            SOAP-ENV:Client

            Device not found with name SEP003094C39708.

            http://www.cisco.com/AXL/1.0"

                     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

                     xsi:schemaLocation="http://www.cisco.com/AXL/1.0

                                         http://myhost/CMApi/AXL/V1/axlsoap.xsd">

                    0

</p><p>Device not found with name SEP003094C39708.</p><p>

                   doDeviceLogin

The real solution is to get it working with the XML parser, with a second option of taping into some more custom Java.  Ultimately, I would like to see Cisco incorporate some new steps to work directly with Web Services (SOAP and REST), without the need for complex Java.

EDIT: Formatting of XML

[Clifford McGlamry]

Agreed.  I think there are two approaches that have to be addressed:

1.  How to work with what we have now and

2.  How would we like this to be improved so it works better.

Ideally, you could solve the problem completely if the XPath spec were implemented more than just at the /descendant and /child levels.  For example, you should be able to enter //  and jump directly to the tag you want.

Getting Cisco to make a change like that will take some pushing.  In the meantime, I'm going to look at being able to figure how how to get a subroutine that can look at any appearance of xmlns and strip that all the way to the next > in the string.

Admittedly it is a work around, but a lot of these solutions are completely custom anyway.  But I do like the challenge. 

Cliff    

[Anthony Holloway]

You will be pleasantly surprised that you can type //node. Granted it will not return an array or even empty nodes, but you can do complex xpath expressions.

Search on the forums for posts by me and xpath or XML. One or two examples should pop up.

Sent from Cisco Technical Support iPhone App

[Clifford McGlamry]

Hmmm.....I tried that and couldn't get it to work.  I'll have to go back and look at it some more.      

[Clifford McGlamry]

Interesting.  I went back and tried this again.  Here's what I found out.

Even though I could select //State using the XPath visualizer and land on the correct node, UCCX doesn't seem to be able to handle that as long as the xmlns is present on one of the child nodes.

But if I strip off the xmlns, then it does in fact work.

I'm not sure if that's a bug or not.  You'd think that xpath = xpath, but maybe there are different versions/implementations.

Cliff