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:
WSDL
A WSDL file is an XML file with the following elements:
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:
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:
<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: