Whatever message this page gives is out now! Go check it out!

Consuming web services

Last update:
May 18, 2026
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:
Method
CFML operator
Description
CFScript
()
Consumes a web service from within a CFScript block.
CFML tag
Consumes a web service from within a block of CFML code.
CFML tag
Consumes a web service from within a block of CFML code.
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:
<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.

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:
<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.

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.
Note: You can pass parameters to a web service using the cfinvokeargument tag or by specifying parameter names in the cfinvoke tag itself. For more information, see Passing parameters to methods by using the cfinvoke tag in Passing parameters to methods.

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:
stArgs = structNew();

stArgs.zipcode = "55987";

</cfscript>

<cfinvoke

webservice="http://www.xmethods.net/sd/2001/TemperatureService.wsdl"

method="getTemp"

argumentcollection="#stArgs#"

returnvariable="aTemp">

<cfoutput>The temperature at ZIP code 55987 is #aTemp#</cfoutput>
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:
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, ...) );

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:
ws = CreateObject("webservice",

"http://www.xmethods.net/sd/2001/TemperatureService.wsdl");

xlatstring = ws.getTemp(zipcode = "55987");

writeoutput("The temperature at 55987 is " & xlatstring);

</cfscript>

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:
<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.

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:
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.

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:
<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.
Note: ColdFusion supports the use of inout and out parameters to consume web services. However, ColdFusion does not support inout and out parameters when creating web services for publication.

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.
Note: The first time you reference a web service, ColdFusion automatically registers it in the Administrator.
For example, the following code references the URL to the TemperatureService WSDL file:
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:
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.

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:
<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:
ColdFusion data type
WSDL data type
numeric
SOAP-ENC:double
Boolean
SOAP-ENC:boolean
string
SOAP-ENC:string
array
SOAP-ENC:Array
binary
xsd:base64Binary
numeric
xsd:float
string
xsd:enumeration
date
xsd:dateTime
void (operation returns nothing)
struct
complex type
query
tns1:QueryBean (Returned by CFCs)
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.
Note: For a list of how ColdFusion data types map to WSDL data types, see Data conversions between ColdFusion and WSDL data types in this page.
The following example shows a ColdFusion component that takes a query as input and echoes the query back to the caller:
<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: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:
<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>

Share this page

Was this page helpful?
We're glad. Tell us how this page helped.
We're sorry. Can you tell us what didn't work for you?
Thank you for your feedback. Your response will help improve this page.

On this page