The agency I work for is implementing the Avatar clinical software system from Netsmart Technologies.  Netsmart has recently released a collection of Web Services for the Avatar system to extend it’s functionality.   It became my duty to fully leverage these Web Services using my favorite language, ColdFusion.  Up until this point I have never worked with a Web Service or even fully understood what one is.  So, I put on my learnin’ hat and started searching around the web for some information.  I soon learned that a web service, loosely and briefly designed can be summized as a way for two software systems, written in different languages and running on different platforms, to talk to each other using a standardized language they can both understand over a protocol they can both understand.  The language in this case is XML (extensible markup language) and the protocol is HTTP (hypertext transfer protocol).  Okay, so now that I know what it is, how can I use it?  A little bit more research and I found out that ColdFusion makes using a Web Service, which is formally referred to as "Consuming" the service, extremely simple.  In fact, ColdFusion has two equally simple ways to consume: using the <cfinvoke> tag or the createObject() function with the "webservice" argument. 

 

The tag based solution works like the following:

 

   <cfinovke webservice="urlToTheWSDL" method="nameOfMethod>

        <cfinvokeargument name="argumentName" type="argumentType">

                                                .

                                                .

                                                .

    </cfinvoke>

 

For the webservice attribute, all you need to do is specify the URL to the WSDL file of the web service.  Every web service you will consume has an accompanying WSDL (Web Service Defintion Language) file that describes what the web service does, what its methods / functions are , and what data types it takes in and returns.  To call a specfic function of the web service, just supply its name in the method attribute.  If the method takes in arguments, you can specify those using <cfinvokeargument> tags, supplying the name of the argument as well as the type.  The type can be simple (string, numeric, boolean,…) or complex (struct, array, user defined object, array of object, …).  If the web service returns a value, you can use the returnvariable attribute of the <cfinvoke> tag to capture it for further processing. 

 

The function based solution looks like this:

 

     <cfset ws = createObject("webservice", "urlToTheWSDL")>

     <cfset returnValue =  ws.nameOfMethod(arg1Name = arg1Value, arg2Name = arg2Value, …)>

 

  or using scripting…

 

     <cfscript>

          ws = createObject("webservice", "urlToTheWSDL");

          returnValue = ws.nameOfMethod(arg1Name = arg1Value, arg2Name = arg2Value, …);

     </cfscript>

         

All you do here is create a web service object, then call methods of the object passing name / value pairs to it.  While this second method requires two seprate steps to consume the service, I prefer it as I believe it has a cleaner appearance when there are multiple arguments to send to the method. 

 

As I hope you can see, ColdFusion makes working with the basic functionality of Web Services quite painless.  In later posts, I will examine how to create, or publish, a Web Service using ColdFusion, as well as dealing with complex data types that are often used in Web Services.

 

Hope this information is useful.  Happy Coding!