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 email-Address 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>

Displaying the Results
The final step is processing the result set returned from the Web service that will be stored in the aGetXMLValidEmail ColdFusion variable created by the <CFINVOKE> tag. For this example <CFSWITCH> will be used to display, dynamically, a "user friendly" message based on the value of the result set.

<cfswitch expression="#aGetXMLValidEmail#">
<cfcase value="Valid">
E-Mail Provided Is Valid
</cfcase>
<cfcase value="InvalidUser">
E-Mail Server is Valid but the User does not exist.
</cfcase>
<cfcase value="InvalidServer">
E-Mail Server is not valid, cannot verify E-Mail address
provided. Please re-enter and try again.
</cfcase>
<cfcase value="InvalidAddress">
E-Mail provided is not properly formatted. Please re-enter and try again.
</cfcase>
<cfcase value="Error">
An error was encountered with the web service verification.
Please try again later.
</cfcase>
</cfswitch>

Using the returned result set, a custom message can be displayed to the user (see Image V).

Conclusion
Sometime near the start of the Internet the term "Information Highway" was coined. Except for a very few, most drivers on this "Information Highway" got lost or missed a lot of the wondrous sights. The biggest problem, in my opinion, was that there were not enough road signs to indicate what services were available at the millions of off-ramps.

My sixth grade teacher, my mentor even now that she has been gone for many years, once told me, "The smartest person in the world is not the one who knows the most, but the one who knows where to find the most." She told me this the day she took me to the school library, gave me my first library card, and showed me how to use the card catalog to locate a book.

With this article you now have a road sign that spells out some of the services that are available on the off-ramp called Web services. Take the exit, explore the countryside, and enjoy the wonders and advantages that this article barely touches on.

Acknowledgments
A special thanks to Josh Einstein of Einstein Technologies for allowing the use of their Web service for the examples in this article.

Listings and information on hundreds of Web services can be found at the following URLs:

• www.xmethods.com
• www.salcentral.com
• www-306.ibm.com/software/solutions/webservices/uddi/
• www.webservices.org/
• www.macromedia.com/devnet/mx/coldfusion/articles/creating_cfcs.html

• Image I
• Image II
• Image III
• Image IV
• Image V