ColdFusion

From the first day the Internet was conceived, its primary goal was to allow people to access information stored on remote computers. Over the last couple of years, the technology of Web services has evolved not only to enhance accessing this information, but to share it as well.

 Web services are in action everywhere. When you see 20-minute delayed stock quotes on a Web site, or you track eBay auctions on another, you are most likely seeing Web services in action. Look a little further and you'll find Web services that can provide these functions as well as spell checking, address verification, ZIP code to city search, and even validation of e-mail addresses. In this article, you'll see how to access one of these Web services and display the results on your own Web site.

Sending e-mail responses to users is one of the most important services you can provide to a customer visiting your site. E-mail is used for sending response messages, reports, and personal messages, and almost without exception, any site that has an online form has a field for entering an e-mail address. This information is, or at least was, one of the hardest pieces of information to verify. This article will outline a very simple application of Web services that will have you verifying e-mail addresses at time-of-entry in no time.

Web Services
Four main components make up a Web service:

• XML: eXtensible Markup Language provides a language-neutral format for exchanging information.
• WSDL: Web Service Definition Language file in XML format that describes the Web service.
• SOAP: XML-based messaging framework used for Web services.
• UDDI: standardized directory service for registering and querying Web service meta data.

For this article, I will be concerned only with the URL location of a single Web service WSDL file.

WSDL
A WSDL file is an XML file with the following elements:

• <definitions>: Root element specifying namespace definitions for the Web service.
• <types>: Specifies data type definitions for the messages being exchanged.
• <message>: Defines the data being exchanged (input/output).
• <part>: Describes the content of the message being exchanged, typically used to name parameters being passed to the WSDL file.
• <portType>: Defines the operations the Web service can be called to perform.
• <operation>: Function or operation that can be performed with the Web service.
• <input>: Input parameters for the parent <operation>.
• <output>: Output parameters for the parent <operation>.
• <fault>: Message returned to the parent <operation> in the event of an error.
• <binding>: Protocol for accessing the operation described in the <portType>.
• <service>: Related port definitions.
• <documentation>: Information about the Web service operations.
• <port>: Endpoint definition for a <binding> element.

ColdFusion MX has incorporated three ways to access these WSDL files (referred to as "consuming a Web service"): the <CFINVOKE> tag, the <CFOBJECT> tag, and the createObject() function. This article will focus on using the <CFINVOKE> tag. Dreamweaver MX also has a components panel (see Image I) where you can access various Web services, view tree diagrams of the WSDL files, and create code snippets by drag and drop.

Since there are numerous documents describing how to add a Web service to the component panel, this article will provide WSDL output file information directly from the Web service.

<CFINVOKE>
The <CFINVOKE> tag provides access to a registered WSDL component on a server. This WSDL component can be written as a ColdFusion Component (CFC), ASP.NET, SOAP, or in other languages that are capable of outputting a WSDL file.

The first attribute of the <CFINVOKE> tag to be populated is WEBSERVICE. The value of this attribute is the literal URL of the WSDL file for the Web service component being "consumed." For this example, the Web service is located at: http://soap.einsteinware.com/email/emailservices.asmx?WSDL.

The next <CFINVOKE> attribute that will be populated is METHOD. The value of METHOD will correspond to the <part> element used for processing the request in the WSDL file. Image II shows that the <part> element is located in the s:element element and has an attribute of "ValidateEmailAddress". The "ValidateEmailAddress" will be the value entered for METHOD.

The last attribute that will be populated for this example is the RETURNVARIABLE. This attribute specifies the name of the ColdFusion variable that will be populated with the result set returned from the Web service. Image III shows that the WSDL return values are located in the simpleType element named "CheckEmailResult". The sub-element s:restriction specifies that the result set will be a string and the s:enumeration sub-elements show five possible results.

The possible values that can be returned are:

• Valid
• InvalidUser
• InvalidAddress
• InvalidServer
• Error

<CFINVOKEARGUMENT>
In some cases, as with the example shown, the Web service may require parameters to be supplied. Viewing the http://soap.einsteinware.com/email/emailservices.asmx?WSDL file shows that the <part> element named "ValidateEmailAddress" has a sub-element complexType.sequence.element with a name attribute of "emailAddress" with a type of string. This is the parameter for the e-mail address that's to be verified.

When parameters are required to be passed to the Web service you can use the <CFINVOKEARGUMENT> tag. This tag has two attributes: "NAME" and "VALUE".

The "NAME" attribute, for this example, is populated with the name attribute value from the complexType.sequence.element element - "emailAddress".

The "VALUE" attribute is populated with the e-mail address to be verified.

You now have code that will "consume" a Web service located on the Einstein Technologies server that you can pass an e-mail address, and verify if the e-mail address:

• Is properly formatted
• Has a valid server
• Has a matching valid user on that server

<cfinvoke
webservice="http://soap.einsteinware.com/email/emailservice.asmx?WSDL"
method="ValidateEmailAddress"
returnvariable="aGetXMLValidEmail">

<cfinvokeargument name="emailAddress" value="#Trim(form.formEmailAddress)#"/>
</cfinvoke>

Now that you have the code for the <CFINVOKE> tag completed, the next step is adding code for getting the e-mail address (see Image IV for screen print) that will be sent as the emailAddress parameter. The code used in this example is shown below:

<hr />
<h1>E-Mail Verification Form<h1>
<hr />
<form name="formEmailSubmit" action="#CGI.SCRIPT_NAME#" method="post">
Enter E-Mail Address:
<input type="text" value="" name="formEmailAddress" maxlength="254" width="50">
<input type="submit" name="formSubmit" value="Verify">
</form>