Consuming web services

The examples shown here reference the TemperatureService web service from XMethods. This web service returns the temperature for a given ZIP code. You can read the WSDL file for this web service in Reading a WSDL file.

The TemperatureService web service has one input parameter, a string that contains the requested ZIP code. It returns a float that contains the temperature for the specified ZIP code.

The message and operation elements in the WSDL file contains subelements that define the web service operations and the input and output parameters of each operation, including the data type of each parameter. The following example shows a portion of the WSDL file for the TemperatureService web service:

<message name="getTempRequest"> 
    <part name="zipcode" type="xsd:string"/> 
</message> 
<message name="getTempResponse"> 
    <part name="return" type="xsd:float"/> 
</message> 
<portType name="TemperaturePortType"> 
    <operation name="getTemp"> 
        <input message="tns:getTempRequest"/> 
        <output message="tns:getTempResponse"/> 
    </operation> 
</portType> 

The operation name used in the examples is getTemp. This operation takes a single input parameter defined as a message of type getTempRequest.

You can see that the message element named getTempRequest contains one string parameter: zipcode. When you call the getTemp operation, you pass the parameter as input.

Web service operations often return information back to your application. You can determine the name and data type of returned information by examining subelements of the message and operation elements in the WSDL file.

The following example shows a portion of the WSDL file for the TemperatureService web service:

<message name="getTempRequest"> 
    <part name="zipcode" type="xsd:string"/> 
</message> 
<message name="getTempResponse"> 
    <part name="return" type="xsd:float"/> 
</message> 
<portType name="TemperaturePortType"> 
    <operation name="getTemp"> 
        <input message="tns:getTempRequest"/> 
        <output message="tns:getTempResponse"/> 
    </operation> 
</portType> 

The operation getTemp returns a message of type getTempResponse. The message statement in the WSDL file defines the getTempResponse message as containing a single string parameter named return.

With the cfinvoke tag, you reference the WSDL file and invoke an operation on the web service with a single tag.

The cfinvoke tag includes attributes that specify the URL to the WSDL file, the method to invoke, the return variable, and input parameters. For complete syntax, see the CFML Reference.

The following example uses CFScript to consume a web service. In CFScript, you use the CreateObject function to connect to the web service. After connecting, you can make requests to the service. For CreateObject syntax, see the CFML Reference.

After creating the web service object, you can call operations of the web service using dot notation, in the following form:

webServiceName.operationName(inputVal1, inputVal2, ... );

You can handle return values from web services by writing them to a variable, as the following example shows:

resultVar = webServiceName.operationName(inputVal1, inputVal2, ... );

Or, you can pass the return values directly to a function, such as the WriteOutput function, as the following example shows:

writeoutput(webServiceName.operationName(inputVal1, inputVal2, ...) );

To consume a web service that is implemented in a technology other than ColdFusion, the web service must have one of the following sets of options:

• rpc as the SOAP binding style and encoding as the encodingStyle

• document as the SOAP binding style and literal as the encodingStyle

The following example shows a portion of the WSDL file for the TemperatureService web service:

<binding name="TemperatureBinding" type="tns:TemperaturePortType"> 
    <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/> 
    <operation name="getTemp"> 
        <soap:operation soapAction=""/> 
        <input> 
            <soap:body use="encoded" namespace="urn:xmethods-Temperature" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/> 
        </input> 
        <output> 
            <soap:body use="encoded" namespace="urn:xmethods-Temperature" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/> 
        </output> 
    </operation> 
</binding>

The WSDL file for the TemperatureService web service is compatible with ColdFusion because it uses rpc as the binding style, and encoding as the encodingStyle.

The Flash Remoting service lets you call ColdFusion pages from a Flash client, but it does not let you call web services directly. To call web services from a Flash client, you can use Flash Remoting to call a ColdFusion component that calls the web service. The Flash client can pass input parameters to the component, and the component can return to the Flash client any data returned by the web service.

For more information, see Using the Flash Remoting Service.

During processing, you can catch in your application errors, including SOAP faults, that otherwise propagate to the browser.

To catch errors, you specify an error type of application to the ColdFusion cfcatch tag, as the following example shows:

<cftry> 
    Place your application code here ... 
    <cfcatch type="application"> 
        <!--- Add exception processing code here ... ---> 
    </cfcatch> 
    ... 
    <cfcatch type="Any"> 
        <!--- Add exception processing code appropriate for all other  
    exceptions here ... ---> 
    </cfcatch> 
</cftry>

For more information on error handling, see Handling Errors.

Some web services define inout and out parameters. You use out parameters to pass a placeholder for a return value to a web service. The web service then returns its result by writing it to the out parameter. Inout parameters let you pass a value to a web service and lets the web service return its result by overwriting the parameter value.

The following example shows a web service that takes as input an inout parameter containing a string and writes its results back to the string:

<cfset S="foo"> 
<cfscript> 
    ws=createobject("webservice", "URLtoWSDL") 
    ws.modifyString("S"); 
</cfscript> 
<cfoutput>#S#</cfoutput>

Even though this web service takes as input the value of S, because you pass it as an inout parameter, you do not enclose it in number signs.

The ColdFusion Administrator lets you register web services so that you do not have to specify the entire WSDL URL when you reference the web service.

For example, the following code references the URL to the TemperatureService WSDL file:

<cfscript> 
ws = CreateObject("webservice",  
"http://www.xmethods.net/sd/2001/TemperatureService.wsdl"); 
xlatstring = ws.getTemp("55987"); 
writeoutput(xlatstring); 
</cfscript>

If you register the TemperatureService web service in the Administrator using (for example, the name wsTemp), you can then reference the web service as follows:

<cfscript> 
     ws = CreateObject("webservice", "wsTemp"); 
     xlatstring = ws.getTemp("55987"); 
     writeoutput("wsTemp: " & xlatstring); 
</cfscript>

Not only does registering the service in the Administrator enable you to shorten your code, it lets you change a web service URL without modifying your code. So, if the TemperatureService web service moves to a new location, you only update the administrator setting, not your application code.

For more information, see the ColdFusion Administrator online Help.

A WSDL file defines the input and return parameters of an operation, including data types. For example, the TemperatureService web service contains the following definition of input and return parameters:

<message name="getTempRequest"> 
    <part name="zipcode" type="xsd:string"/> 
</message> 
<message name="getTempResponse"> 
    <part name="return" type="xsd:float"/> 
</message>

As part of consuming web services, understand how ColdFusion converts WSDL defined data types to ColdFusion data types. The following table shows this conversion:

For many of the most common data types, such as string and numeric, a WSDL data type maps directly to a ColdFusion data type. For complex WSDL data types, the mapping is not as straight forward. In many cases, you map a complex WSDL data type to a ColdFusion structure. For more information on handling complex data types, see Handling complex data types.

Your application can consume web services created in ColdFusion. You do not have to perform any special processing on the input parameters or return values because ColdFusion handles data mappings automatically when consuming a ColdFusion web service.

For example, when ColdFusion publishes a web service that returns a query, or takes a query as an input, the WSDL file for that service lists its data type as QueryBean. However, a ColdFusion application consuming this web service can pass a ColdFusion query object to the function as an input, or write a returned QueryBean to a ColdFusion query object.

The following example shows a ColdFusion component that takes a query as input and echoes the query back to the caller:

<cfcomponent> 
    <cffunction name='echoQuery' returnType='query' access='remote'> 
        <cfargument name='input' type='query'> 
        <cfreturn #arguments.input#> 
    </cffunction> 
</cfcomponent>

In the WSDL file for the echotypes.cfc component, you see the following definitions that specify the type of the function input and output as QueryBean:

<wsdl:message name="echoQueryResponse"> 
     <wsdl:part name="echoQueryReturn" type="tns1:QueryBean"/> 
</wsdl:message> 
<wsdl:message name="echoQueryRequest"> 
     <wsdl:part name="input" type="tns1:QueryBean"/> 
</wsdl:message>

For information on displaying WSDL, see Producing WSDL files.

Since ColdFusion automatically handles mappings to ColdFusion data types, you can call this web service as the following example shows:

<head> 
<title>Passing queries to web services</title> 
</head> 
<body> 
<cfquery name="GetEmployees" datasource="cfdocexamples"> 
    SELECT FirstName, LastName, Salary 
    FROM Employee 
</cfquery> 
 
<cfinvoke  
    webservice = "http://localhost/echotypes.cfc?wsdl" 
    method = "echoQuery" 
    input="#GetEmployees#" 
    returnVariable = "returnedQuery"> 
 
<cfoutput> 
    Is returned result a query? #isQuery(returnedQuery)# <br><br> 
</cfoutput> 
 
<cfoutput query="returnedQuery"> 
    #FirstName#, #LastName#, #Salary#<br> 
</cfoutput> 
</body>