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.

[Anthony Holloway]

The first thing we do in a series of steps to get this class on the server is to package the class file in a .jar file. A .jar file is simply a .zip file with some additional information in it, but mainly your .class file.

http://www.avholloway.com/vtools/ipcc/custom-java/soap/packaging-SimpleSOAP.png - Command Prompt>jar SimpleSOAP.jar SimpleSOAP.class

Next, we need to upload this .jar file to the Document Management on the CRS server's admin page, and it will go under default\classpath.

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

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

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

Now let's do this next step which I still haven't quite figured out the purpose of. We will go to System > Custom File Configuration, and move our .jar file over from the left pane to the right pane.

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

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

Essentially what you are doing in these two steps, is adding your custom Java class to the search path for finding other classes when the CRS server tries to use your custom class. Because by default, it only knows about core Java classes that are built into the JRE.

Lastly, we have to restart the CRS Engine.

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

Now we can launch our CRS Editor, and it's important to note, the editor must be ran from the server. So, if you have it installed on your local dev box, skip the headache and launch it from within the server. RDP or VNC is fine.

I am going to create a very simple script just to show the bare minimum to access our custom Java class, and return a SOAP response.

Download link: http://www.avholloway.com/vtools/ipcc/custom-java/soap/you-need-some-soap.aef

Screen shot: http://www.avholloway.com/vtools/ipcc/custom-java/soap/you-need-some-soap.aef.png

There are three important things to note here:

1. I do not have to create a variable of type SimpleSOAP, even though I can

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

2. I do need a variable to hold the return value (The SOAP response)

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

3. I only need one set step to use my custom Java class, and have it return something useful

The set step is the most complex step, because it is written in Java. So what we have in this step is a block of Java being executed, and it must return a String value.

Source code: http://www.avholloway.com/vtools/ipcc/custom-java/soap/set-step-expression.txt

Screen shot: http://www.avholloway.com/vtools/ipcc/custom-java/soap/set-step-expression.png

Before we run it, set a break point on the End step, then click the play button in the tool bar. Because the End step has a break point set on it, you will be able to see the variable xml_soap_response populated with the XML response. Double click the xml_soap_response variable in the variable list to access the expression editor where you can see the full XML output.

http://www.avholloway.com/vtools/ipcc/custom-java/soap/script-execution-complete.png

This is where this how-to goes south, and hopefully that will change. You see, Cisco's CRS editor lacks the programming to handle XML documents that reference name spaces, but it can handle simple XML documents pretty well.

So, we can take the return XML SOAP response, and create an XML document with it, but I cannot extract any of the data out of it.

See this script for an example of my attempt at this:

Screen shot: http://www.avholloway.com/vtools/ipcc/custom-java/soap/attempt-xml-document.aef.png

Download link: http://www.avholloway.com/vtools/ipcc/custom-java/soap/attempt-xml-document.aef

Please comment/rate. =)

Anthony Holloway (avholloway@gmail.com)

[sferland]

Thanks Anthony, this is by far, the best post I've seen in this forum.

Good job !

[mvtonytjo]

Thanks Anthony!!

I have a related problem and very wish you could help.

I can follow your instructions and call a custom-defined class.

However, I wish to return something from the class. I think I should use the RMI logic provided by IPCCX.

But there is a "java.rmi.NotBoundException" when I create the RMI object.

I have uploaded the RMI server, client and the interface classes to the default classpath.

What settings else?

Thanks a lot in advance!!

Tony

[rsnook]

Where was this 3 months ago... AWSOME!!!!

[voiceops]

Thank you very much for sharing this info with us. Would you have any info using custom classes with CRS 3.5(2).

I've done all but copying the class to the location in the server where the editor can see it.

I think I know where I'm supposed to copy it but I'm not to clear about needing a jar file. My class uses a third party driver to connect to a SQL server table. I've run the class from the server's command line and it works. I've also modified the classpath so that it can find the 3rd party driver.

So, basically what I have is a class (dbinsert.class) and a jar file (jtds.jar). I can run/call dbinsert.class from a java application (rundbinsert.class) successfully.

thanks

[mmusitani]

Anthony:

I would appreciate if you could check this post to the forum:

I'm having problems to create Objects from a Jar file in CCX Editor... Maybe you could help!

http://developer.cisco.com/web/ccxs/forums/-/message_boards/view_message/5330902/maximized?p_p_auth=vRbm0EeH

Regards,

[Aaron Harrison]

Hi Mmusitani

Questions there are answered here (below).

Regards

Aaron

[Maic Naatz]

Hi Anthony,

can you please provide all the pics and documents from your post above? Every links resonses with the "Forbidden 403" Error.

Greetings Maic Naatz

[Gergely Szabo]

Hi, can you please start a new thread if you have a specific problem.

Thanks.

G.
 

[Maic Naatz]

Hi,

i do so: https://supportforums.cisco.com/discussion/12265461/run-java-code-jar-file-set-step

Greetings Maic

[Gergely Szabo]

Thanks :-) Excellent!

[Nicolas Mansour]

Hi Anthony,

First of all,I want to thank you for the this post. Very handy.

I wanted to ask you, have you ever used nested classes? My goal is to create a custom class that will use default classes. Should I just create a jar file containing all of the needed files?

Thank you in advance

[Anthony Holloway]

I have no idea. As I stated in my post, I am not a Java Programmer.

I don't fully understand how class are all mapped to, or pointing at each other.

If you find out, do post it here.

[mvtonytjo]

My colleague has tried to use package in the Java code, and it succeeds.

I don't know if using package can help you.

Tony