UCCX 8.x - a Really Simple SOAP Client (no custom JAR) - Page 3

Gergely Szabo · ‎04-17-2012

Problem: it's a common task for a call center routing script to communicate with a remote procedure using the SOAP protocol, over HTTP. Usually, the script sends a piece of information to the SOAP server, parses the response, reads some useful data and then continues.

Analysis: Unfortunately, there is no built in step or method to create a simple SOAP client within a CRS script (and I don't blame the UCCX programmers for that). Some people use various frameworks (JAX-WS, Axis) to make SOAP calls easier, this usually requires an IDE like NetBeans or Eclipse, building a Java package, and uploading it - along with the framework itself - as custom JARs to the UCCX server. Personally, I don't really like that idea:

it makes debugging complicated;
if any change is needed, one must rebuild the whole solution, upload it to the UCCX server, restart the CCX engine - who likes this hassle;
I don't see the reason why we can't keep things simple and stupid - meaning, CRS scripts can do Java, and Java (at least Java 6 which comes with UCCX 8.x) can do everything you need to build a Really Simple SOAP Client.

UPDATE 1: if you are interested in a more OOP-style WS client (created with JAX-WS) read the following post:

https://supportforums.cisco.com/docs/DOC-26957.

UPDATE 2: I got a couple of comments and private messages about the CCX editor not accepting the second Set step due to one line:

return new String(baos.toByteArray());

This is a bug in some versions of UCCX. Unfortunately, for some reason it will sort of "hide" the Set step if it contains the above line. I don't know why it won't allow calling the toByteArray() method on a ByteArrayOutputStream object, this method is legal. Some versions of UCCX may accept it, some just won't. For instance, UCCX 8.0.2 happily accepts that method, UCCX 7.0SR5 does not.

If your UCCX is affected by the bug, then try replacing the above line with the following:

return baos.toString();

This has been tested and found working with UCCX Premium 7.0SR5 which does contain the bug, so the Set step disapperared with the original line but it did not with the replacement.

Solution: so, what is SOAP anyway?

In Plain English, it consists of:

creating an XML document;
SOAP Request: sending this XML document to the SOAP server. This is usually HTTP POSTing it to the web server;
read the SOAP response (this is an XML document, too);
parse the SOAP response and filter out the information we are looking for.

Looking at the tools the CCX editor offers for the above four tasks:

1. creating an XML document - easy. Two alternatives:

XML Template: you can upload an XML document on to the UCCX server, with some tokens; then, using the Keyword Transform Document step (where the already existing XML document will be the template), just replace the tokens with the desired values. That works just great if you don't want anything complicated and you are absolutely sure the result will also be a valid XML document (so there is no chance the Keyword Transform Document messes it up with some unexpected characters etc).
You can, of course, use Java to build the XML from scratch if you want to have more control. Personally, I like this option.

2. sending this XML document - now, one may say, there's the Create URL Document step, and it can do HTTP Post. Well, that's right, the step exists, it can sort of POST, but it's not the POST we are looking for. This step actually formats the value to be sent differently (application/x-www-form-urlencoded) which may or may not be accepted by the SOAP server. Java gives you more precise tools for that.

3. reading the SOAP response - this actually goes along with the previous step. But if we send something unacceptable to the SOAP server, we cannot expect a valid response either. Using Java gives you more granulated control.

4. parse the SOAP response and "fish out" the desired piece of information - easy. The Get XML Document Data step can operate with XPath expressions perfectly. So no Java code is needed.

**** DISCLAIMER: This is a proof of concept. I am not responsible for any damage, including the death of your favorite pet/rockstar. I cannot guarrantee this solution is the best, I cannot even guarrantee it would work in your system. Tested with IP IVR version 8.0(2) ****

I am going to explain the whole process using an example. Again, y u no build any packages, custom JARs. I don't even expect you to be fluent in Java.

In our not at all imaginary call center, there's a UCCX script that is supposed to do some routing decision based on a number which is calculated by some legacy systems, which speak SOAP only.

The expected SOAP request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">

<soapenv:Header/>

<soapenv:Body>

<mis:GetCallAggregates xmlns:mis="http://mis.report.pointers.cz/">

</mis:GetCallAggregates>

</soapenv:Body>

</soapenv:Envelope>

If everything goes fine, then the SOAP response is:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

<soap:Body>

<ns2:GetCallAggregatesResponse xmlns:ns2="http://mis.report.pointers.cz/">

<parameterName>AbandonIn30</parameterName>

</CallAggregate>

<parameterName>AbandonIn30</parameterName>

</CallAggregate>

<parameterName>BehindIVR</parameterName>

</CallAggregate>

<parameterName>BehindIVR</parameterName>

</CallAggregate>

</GetCallAggregatesResult>

</ns2:GetCallAggregatesResponse>

</soap:Body>

</soap:Envelope>

If we send something to the SOAP server and an error occurs, the SOAP response looks like this (I just inserted a bogus <boo> tag into the XML):

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

<soap:Body>

<soap:Fault>

<faultcode>soap:Client</faultcode>

<faultstring>Unmarshalling Error: unexpected element (uri:"", local:"boo"). Expected elements are (none)</faultstring>

</soap:Fault>

</soap:Body>

</soap:Envelope>

Now, take a look at the request again:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">

<soapenv:Header/>

<soapenv:Body>

<mis:GetCallAggregates xmlns:mis="http://mis.report.pointers.cz/">

</mis:GetCallAggregates>

</soapenv:Body>

</soapenv:Envelope>

As we can see, it's just a plain ordinary XML document (sans the XML declaration, for the sake of brevity). The so-called root element is soapenv:Envelope (its namespace in red, first row - expected by the SOAP server). The first child node is soapenv:Header; notice, it is empty - my SOAP server does not expect any headers. Then the soapenv:Body - this contains the next element, mis:GetCallAggregates (with the namespace URI in red, again), and this contains two elements, startDate and endDate (each containing a date and time string).

In other words, I am asking the SOAP server to run the GetCallAggregates method, with two parameters, startDate (its value is 2012-04-01T00:00:00) and endDate (its value is 2012-04-02T23:59:59). Actually, I am asking for some statistical information (CallAggregates) within the specified dates (1st April 2012 00:00:00, and 2nd April 2012 23:59:59).

This can be very easily constructed in Java, using only the tools Java 6 offers. And, as we know, Java 6 - more precisely, JDK 1.6 - is included in UCCX and if you have IP IVR or UCCX Enhanced or Premium, you can use it, most likely with Set steps.

Constructing XML in Java

First, I am going to create a new variable, type String, and name it soapRequest (initial value: null).

Then I am going to insert a Set step into my script, that would yield the value of the above soapRequest variable. The value field would be a closure (a block of Java code. Don't panic, I'll explain that, too!)

The source code I am using at this step (please note: // starts a line of comment):

{

// first, create a new buffer:

java.io.StringWriter buffer = new java.io.StringWriter();

// define namespace URI's and prefixes

// (take a look at the SOAP request XML above, you'll see there are two namespace prefix - URI pairs

final String SOAPENV_NAMESPACE_URI = "http://schemas.xmlsoap.org/soap/envelope/";

final String SOAPENV_NAMESPACE_PREFIX = "soapenv";

final String MIS_NAMESPACE_URI = "http://mis.report.pointers.cz/";

final String MIS_NAMESPACE_PREFIX = "mis";

// some of the following methods may throw an exception (~ error), so we want to wrap them

// into a try..catch block. Remember, if an exception occurs, the resulting value,

// thus the soapRequest variable will be null

try {

// create a document builder "factory" (that builds the document)

// make it namespace aware

// then crate a new document

javax.xml.parsers.DocumentBuilderFactory factory = javax.xml.parsers.DocumentBuilderFactory.newInstance();

factory.setNamespaceAware(true);

javax.xml.parsers.DocumentBuilder documentBuilder = factory.newDocumentBuilder();

org.w3c.dom.Document document = documentBuilder.newDocument();

// insert the "root" element (soapenv:Envelope), and introduce the required namespace:

org.w3c.dom.Element root = document.createElementNS(SOAPENV_NAMESPACE_URI, SOAPENV_NAMESPACE_PREFIX + ":Envelope");

root.setAttributeNS("http://www.w3.org/2000/xmlns/", "xmlns:" + SOAPENV_NAMESPACE_PREFIX, SOAPENV_NAMESPACE_URI);

// create the header element (precisely: soapenv:Header)

// we are going to append it to the root element right away (since it should not contain anything)

org.w3c.dom.Element header = document.createElement("soapenv:Header");

root.appendChild(header);

// create the body (precisely: soapenv:Body) element:

org.w3c.dom.Element body = document.createElement("soapenv:Body");

// create another element, mis:GetCallAggregates, now with a different namespace, too:

org.w3c.dom.Element gca = document.createElementNS(MIS_NAMESPACE_URI, MIS_NAMESPACE_PREFIX + ":GetCallAggregates");

gca.setAttributeNS("http://www.w3.org/2000/xmlns/", "xmlns:" + MIS_NAMESPACE_PREFIX, MIS_NAMESPACE_URI);

// and, create two other elements, startDate and endDate

// each contains a date-time string:

org.w3c.dom.Element startDate = document.createElement("startDate");

startDate.setTextContent("2012-04-01T00:00:00");

org.w3c.dom.Element endDate = document.createElement("endDate");

endDate.setTextContent("2012-04-02T23:59:59");

// adding startDate and endDate to mis:GetCallAggregates

gca.appendChild(startDate);

gca.appendChild(endDate);

// adding mis:GetCallAggregates to the soapenv:Body element

body.appendChild(gca);

// adding the soapenv:Body element to the root element (soapenv:Envelope)

root.appendChild(body);

// and then adding the root element to the document

document.appendChild(root);

// at this point, we've got the programmatic representation of XML

// but we need to transform it into a String so we can send it to the SOAP server

// this can be achieved, too: the source being the programmatic representation

// and the result is the buffer we specified on the first line

javax.xml.transform.TransformerFactory transFactory = javax.xml.transform.TransformerFactory.newInstance();

javax.xml.transform.Transformer transformer = transFactory.newTransformer();

javax.xml.transform.Source source = new javax.xml.transform.dom.DOMSource(document);

javax.xml.transform.stream.StreamResult result = new javax.xml.transform.stream.StreamResult(buffer);

transformer.transform(source, result);

} catch (Exception e) {

// again, if anything happens,the strack trace is sent to the standard output (stdout.log, most likely)

e.printStackTrace();

// and then null is returned

return null;

} // try..catch block ends here

// but if there are no problems, the buffer is cast into a String:

return buffer.toString();

} //closure ends here

I know, it might be overwhelming, but once you understand the basic concepts of XML, this code will also be easier to read.

So at this point, we've got the SOAP request XML document - held by the soapRequest variable.

Issuing the SOAP request, using Java

Again, we need to connect to the web server, in other words, to the endpoint, and using HTTP POST, send the XML document created above.

First, I am going to introduce three new variables:

soapResponseString, type String, initial value: null

soapResponseDoc, type Document, initial value: DOC[]

soapServiceEndpoint, type String, initial value is "http://10.232.108.15:8080/MIS/services/MISReport"

Just some more details on them: soapResponseString is the raw "string", sent by the SOAP server as response. Since the Get XML Document Data step can only operate on documents of which type is Document, we'll have to use a different variable, with the expected type, soapResponseDoc. And, as you might have guessed, the soapServiceEndpoint contains the URL of the SOAP Server endpoint.

Then, the Set step. The variable is the soapResponseString, and the value field contains another nice block of code again:

Source code (again, don't panic!):

{

// create a ByteArrayOutputStream - this is actually a buffer

// we are going to use to store the response coming from the SOAP server

java.io.ByteArrayOutputStream baos = new java.io.ByteArrayOutputStream();

// this is quite unnecessary: assigning the value of the soapRequest (still holding our XML document)

// to another variable, named content, type String; but anyway, it's just cleaner

String content = soapRequest;

// specify a timeout - 5000 milliseconds - if the web server does not start sending back

// anything within this timeframe, an exception will be raised

int readTimeout = 5000;

// now, the following methods are enclosed by a try..catch block

// to catch any exceptions - we just want to have control over them

// remember, an uncaught exception might stop your CRS script execution

// and you might not want that

try {

// a new URL, which is the soapServiceEndpoint variable value (http://ip:port/ etc):

java.net.URL url = new java.net.URL(soapServiceEndpoint);

// creating a HTTP connection to the above URL:

java.net.HttpURLConnection urlCon = (java.net.HttpURLConnection) url.openConnection();

// setting some important header parameters, first of all, content length, this is most likely expected

// by the SOAP server

urlCon.setFixedLengthStreamingMode(content.length());

// setting the timeout:

urlCon.setReadTimeout(readTimeout);

// we tell Java we will do input (in other words, we will read):

urlCon.setDoInput (true);

// we tell Java we will do output (in other words, we will send):

urlCon.setDoOutput (true);

// we tell Java not to cache:

urlCon.setUseCaches (false);

// we are using HTTP POST

urlCon.setRequestMethod("POST");

// finally, we set the Content-Type header,

// this way we are telling the SOAP server we are sending an XML, using the UTF-8 charset

urlCon.setRequestProperty("Content-Type","text/xml;charset=UTF-8");

// opening an OutputStream (this is a one-way channel towards the SOAP server:

java.io.DataOutputStream output = new java.io.DataOutputStream(urlCon.getOutputStream());

// we write the contents of the content variable (= soapRequest = XML document):

output.writeBytes(content);

// telling Java to flush "speed up!" and then close the stream:

output.flush();

output.close();

// now getting the InputStream (getting a one way channel coming from the SOAP server):

java.io.DataInputStream input = new java.io.DataInputStream(urlCon.getInputStream());

// buffered read from the InputStream, buffer size 4Kilobytes (= 4096 bytes):

// and the buffer is always written to the other buffer, named baos, that we specified

// on the first line of this block of code

int bufSize = 4096; // buffer size, bytes

byte[] bytesRead = new byte[bufSize];

int bytesReadLength = 0;

while(( bytesReadLength = input.read( bytesRead )) > 0 ) {

baos.write(bytesRead,0,bytesReadLength);

} //while block ends here

// closing the InputStream:

input.close();

// closing the baos buffer

baos.close();

} catch (Exception e) {

// again, if an error occurs, let's just send the stack trace to stdout (stdout.log)

// and then return null

e.printStackTrace();

return null;

} // try..catch block ends here

// construct a new String, and return that to the CRS script:

return new String(baos.toByteArray());

} // closure ends here

(N.B.: If your UCCX is affected by a strange bug - see UPDATE 2 - try replacing

return new String(baos.toByteArray());

with

return baos.toString();

)

There's still one more step, cast this soapResponseString to a Document. Notice the next step, the Get XML Document Data step expects the document be created by the Create XML Document step. But that's not a problem:

Voilá, we've got our SOAP response document. Again, it's something like this if everything goes perfectly:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

<soap:Body>

<ns2:GetCallAggregatesResponse xmlns:ns2="http://mis.report.pointers.cz/">

<parameterName>AbandonIn30</parameterName>

</CallAggregate>

<parameterName>AbandonIn30</parameterName>

</CallAggregate>

<parameterName>BehindIVR</parameterName>

</CallAggregate>

<parameterName>BehindIVR</parameterName>

</CallAggregate>

</GetCallAggregatesResult>

</ns2:GetCallAggregatesResponse>

</soap:Body>

</soap:Envelope>

And like this if something goes bad:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

<soap:Body>

<soap:Fault>

<faultcode>soap:Client</faultcode>

<faultstring>Unmarshalling Error: unexpected element (uri:"", local:"boo"). Expected elements are (none)</faultstring>

</soap:Fault>

</soap:Body>

</soap:Envelope>

Getting the desired value from the SOAP response XML document

For now, let's pretend everything went fine, there were no errors. I am interested in the value of the "value" element of the first CallAggregate element (where the date is 2012-04-01 and the "parameterName" is AbandonIn30):

We use the Get XML Document Data step for it (the result variable is named inString, type String, inital value: null):

The actual XPath expression:

"//CallAggregate[1]/value"

Of course, you might check whether there are any soap:Fault nodes, you can do that using the XPath expression //faultcode (for instance).

Check Wikipedia or w3schools for more XPath examples.

Conclusion: this is a simplistic approach, yet it works very well in a real environment.

Happy coding!

sreeraman · ‎03-28-2016

Thanks to everyone for this great post. Thanks to Gergely the original creator of this post as well.

Just want to know if anyone got this working with https and CUCM AXL API

I could not and any help would be greatly appreciated

Firstly I think , I need to use javax.net.ssl.HttpsURLConnection instead of java.net.HttpURLConnection

But I am not sure how to send the username and password

I was able to form the soapRequest string successfully but the soapResponseString is always null

I cannot even see the request hitting the CUCM from AXL logs in CUCM

U"<?xml version=\"1.0\" encoding=\"UTF-8\"?><soapenv:Envelope xmlns:soapenv=\"http://schemas.xmlsoap.org/soap/envelope/\"><soapenv:Header/><soapenv:Body><ns:getLine xmlns:ns=\"http://www.cisco.com/AXL/API/10.5\"><pattern>123456</pattern><routePartitionName>IP-Phones</routePartitionName></ns:getLine></soapenv:Body></soapenv:Envelope>"

{
java.io.ByteArrayOutputStream baos = new java.io.ByteArrayOutputStream();
String content = soapRequest;
int readTimeout = 5000;
try {
java.net.URL url = new java.net.URL(soapServiceEndpoint);
java.net.HttpURLConnection urlCon = (java.net.HttpURLConnection) url.openConnection();
urlCon.setFixedLengthStreamingMode(content.length());
urlCon.setReadTimeout(readTimeout);
urlCon.setDoInput (true);
urlCon.setDoOutput (true);
urlCon.setUseCaches (false);
urlCon.setRequestMethod("POST");
urlCon.setRequestProperty("Content-Type","text/xml;charset=UTF-8");
java.io.DataOutputStream output = new java.io.DataOutputStream(urlCon.getOutputStream());
output.writeBytes(content);
output.flush();
output.close();
java.io.DataInputStream input = new java.io.DataInputStream(urlCon.getInputStream());
int bufSize = 4096;
byte[] bytesRead = new byte[bufSize];
int bytesReadLength = 0;
while(( bytesReadLength = input.read( bytesRead )) > 0 ) {
baos.write(bytesRead,0,bytesReadLength);
}
input.close();
baos.close();
} catch (Exception e) {
e.printStackTrace();
return null;
}
return new String(baos.toByteArray());
}

Valber Carvalho · ‎03-28-2016

Hi sreeraman,

Please, access Cisco DevNet for more information. Login is required.

http://developer.cisco.com/site/axl/learn/how-to/axl-java-sample-application.gsp

Good lucky,

Valber Carvalho

mariusstan · ‎04-08-2017

Hello Gergely,

I founded the post very useful for my activity. Many thanks for it. I would require some advice some, guidance when the SOAP is used with https. In that case there are 2 steps:

- first: upload soap webservice certificate in the UCCX tomcat-trust

- second: is it enough to simply change the url from http to https - I guess I saw your answer in this direction somewhere but I cant find that post right now - or it is necessary to use Https.ssl.URLConnection method?

I was not able to reach second step because I am still working on the certificate side. The UCCX even if it is on 10.5 version does not seem to recognize the uploaded certificate and so the TLS fails with Fatal Alert message - Internal Error - code 80 from IVR side.

I am stuck on this also and any ideea would be very much appreciated.

Kind regards,

Marius

Valber Carvalho · ‎04-10-2017

Hi Marius,

Some years ago I had the same problem than you.
I needed to import some digital certificates to the UCCX v8.5.
To solve it I had to open a TAC and the support engineer imported all certificates using a tool called: CetTool.exe.
It is only possible because TAC has the root user from your Linux/UCCX and they are able to import any files to there.

I am not sure if it is other way to do it.

Best Regards,

Valber Carvalho.

mariusstan · ‎04-10-2017

Hello Valber,

Thank you very much for your advice. I saw that you experienced same issue - on your posts - but I thought that Cisco solved that bug. You hit that problem in 8.X version and now I am on 10.5.

I use this occasion to ask an advice from your side:

- in order to launch https actions is enough to change the URL from the soap endpoint from http in https or I need to Https.ssl.URLConnection method ?

Kind regards,

Marius

Valber Carvalho · ‎04-10-2017

Hi Marius.

Normally if you change the URL is enough.
Some cases you need to set some properties to the URLConnection object (see setRequestProperty() method below). I think that you can check with Web Services owner what is really necessary to establish your connection.
Doing it you are maniputing the SOAP header, see the sample of code:

{
String soapResponse= "";
String soapRequestURL= URLWebServer;
String soapRequestTXT = docRequestSoap;
int readTimeout = TimeoutWebServer ;
try {
java.net.URL url = new java.net.URL(soapRequestURL);
java.net.URLConnection conn = url.openConnection();
conn.setRequestProperty("Content-Type", "txt/xml; charset=utf-8");
// Set Key and Value to HTTP header authentication
conn.setRequestProperty("Authorization","Basic dXJhd3M6a2g1a3ptZXkzcXk2ZXg1czB0MjM=");
conn.setRequestProperty("SOAPAction", strMetodoSoapAction );
conn.setRequestProperty("Content-Length", "" + soapRequestTXT.length());
conn.setDoOutput(true);
conn.setReadTimeout(readTimeout);
java.io.OutputStreamWriter wr = new java.io.OutputStreamWriter(conn.getOutputStream());
wr.write(soapRequestTXT);
wr.flush();
java.io.BufferedReader rd = new java.io.BufferedReader(new java.io.InputStreamReader(conn.getInputStream()));
String line = "";
while ((line = rd.readLine()) != null) {
soapResponse += line;
}
wr.close();
rd.close();
return soapResponse;
} catch (Exception exception) {
return "Erro: " + exception;
//return "ErroWebService";
}
}

Use the Soap UI software (it's free) you can test the connection and see the Soap Requests and Responses are working properly.

mariusstan · ‎04-10-2017

Hello Valber,

I tried in my lab to access cucm axl web service and seems that for uccx 11.x version the https connection worked. The SOAP action did not worked - but I am not sure that I formed the SOAP ok. But I have a point to start. I will dig tomorrow again.

Kind regards for your advice.

Marius

NinjaPirate · ‎12-06-2017

Hi guys,

Newbie SOAP and java coder here.

Here is what I get when doing reactive debugging at the Create XML Document step.

"Source document variable "(Document) soapResponseString" has null value."

Looks like my java insert is throwing exception and I get null returned. Wondering where do i get the stdout.log log with the exception from?

Which logs should I pull to dig deeper? MIVR?

thx

ln33147 · ‎02-01-2018

Thank you so much Gergely for the helpful post. Highly appreciated.

I just have one question regarding the authentication. Can you please advise what SOAP authentication method can be used.

Thank you in advance.