Consuming web services

ColdFusion provides a variety of methods for consuming web services. The method that you choose depends on your ColdFusion programming style and application. 
The following table describes these methods:

One important consideration is that all consumption methods use the same underlying technology and offer the same performance.

About the examples

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.

Passing parameters to a web service

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:

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.

Handling return values from a web service

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:

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.

Using cfinvoke to consume a web service

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.

Access a web service using cfinvoke

1. Create a ColdFusion page with the following content:

   webservice="http://www.xmethods.net/sd/2001/TemperatureService.wsdl" method="getTemp" returnvariable="aTemp"> <cfinvokeargument name="zipcode" value="55987"/> </cfinvoke> <cfoutput>The temperature at ZIP code 55987 is #aTemp#</cfoutput>

2. Save the page as wscfc.cfm in your web root directory.
3. View the page in your browser.
   You can omit a parameter by setting the omit attribute to "yes". If the WSDL specifies that the argument is nullable, ColdFusion sets the associated argument to null. If the WSDL specifies minoccurs=0, ColdFusion omits the argument from the WSDL. However, CFC web services must still specify required="true" for all arguments.
   You can also use an attribute collection to pass parameters. An attribute collections is a structure where each structure key corresponds to a parameter name and each structure value is the parameter value passed for the corresponding key. The following example shows an invocation of a web service using an attribute collection:

In this example, you create the structure in a CFScript block, but you can use any ColdFusion method to create the structure.

Using CFScript to consume a web service

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:

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

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

Access a web service from CFScript

1. Create a ColdFusion page with the following content:

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

2. Save the page as wscfscript.cfm in your web root directory.
3. View the page in your browser.
   You can also use named parameters to pass information to a web service. The following example performs the same operation as the preceding code, except that it uses named parameters to make the web service request:

Consuming web services that ColdFusion does not generate

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:

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.

Calling web services from a Flash client

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.

Catching errors when consuming web services

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:

For more information on error handling, see Handling Errors.

Handling inout and out parameters

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:

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.

Configuring web services in the ColdFusion Administrator

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:

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:

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.

Data conversions between ColdFusion and WSDL data types

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:

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.

Consuming ColdFusion web services

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:

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:

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: