During a customer’s visit to a commerce site, you will want to keep an orderform of who they are, what they have purchased, how they are going to pay for it, etc. This information is kept in a standard Dictionary object (introduced in IIS 4.0) referred to as the OrderForm (progid of "Commerce.OrderForm"). A dictionary object can be thought of as a two-dimensional array of name/value pairs. The Dictionary object can be treated as a collection so that the .item and .count properties are available. The value can be any object, including another Dictionary object. For more information on dictionary objects, please refer to WebBuilder’s article “Make Dictionaries Work For You”, October 1998.
The customer information and the product information are treated differently in the orderform. The customer information is a regular name/value pair such as “ship_to_name” with a value of “Dina Berry”. Since there can be many products, the object in the orderform for the “items” is a Simple List. A Simple List is a one-dimensional array of Dictionary objects. Each array item is a Dictionary object that contains all the information about the product. To validate a credit card, the code needs to create an orderform but does not need to create the Simple List or subsequent Dictionary objects for the products.
Most of the code to run a pipeline is available when you create a site using the Site Creation Wizard. To run a pipeline you need the global.asa and the i_util.asp files that are in the root of your commerce site. The global.asa creates most of the commerce objects you will need. The i_util.asp has all the functions you need in order to use a pipeline.
The validatecc_test.asp file is a short form to enter the credit card type, number, expiration month, and expiration year. Once your have filled out the information and submitted the HTTP form, the orderform object is created. The orderform object is then passed to the pipeline. The result of the pipeline is either an error that the card couldn’t be validated or no error at all. If there is an error, the text of the error is displayed at the top of the page.
Figure 1: The Web Form for Credit Cards
The code to produce this page is in Listing 1. The page contains a form and the call to the function “ValidateCreditCard” to validate the form information. This function creates an orderform and executes the pipeline. But first we need to create the pipeline file itself.
Listing 1 - Credit card validation form
<%@ Language=VBScript %>
<!-- #include file="i_util.asp" -->
<%
Dim sCardType
Dim sCardNumber
Dim sExpMonth
Dim sExpYear
sCardType = Request("cctype")
sCardNumber = Request("ccnumber")
sExpMonth = Request("ccexpmonth")
sExpYear = Request("ccexpyear")
if Request("submit") <> "" then
sMessage = ValidateCreditCard()
end if
%>
<HTML>
<HEAD>
<META NAME="GENERATOR" Content="Microsoft Visual Studio 6.0">
</HEAD>
<BODY>
Message = "<% = sMessage %>"
<p>
<form action="validatecc_test.asp" method="post">
<table>
<tr>
<td>
card number
</td>
<td>
<input name="ccnumber">
</td>
</tr>
<tr>
<td>
card type
</td>
<td>
<SELECT id=CardType_ID name="cctype">
<option value="American Express">American Express
<option value="Discover">Discover
<option value="Mastercard">Mastercard
<option value="Visa">Visa
</SELECT>
</td>
</tr>
<tr>
<td>
expiration month
</td>
<td>
<SELECT id=ExpMonth_ID name="ccexpmonth">
<!-- #include file="e_month.asp" -->
</SELECT>
</td>
</tr>
<tr>
<td>
expiration year
</td>
<td>
<SELECT id=ExpYear_ID name="ccexpyear">
<!-- #include file="e_year.asp" -->
</SELECT>
</td>
</tr>
</table>
<input type="submit" name="submit" value="submit">
</form>
</BODY>
</HTML>
To use the credit card validation component you need to create a pipeline file. When you open the pipeline editor and choose New, you will have several choices of pipeline templates. For this article, I chose the Blank pipeline. This pipeline opens up with nothing in it. I selected the pipe and inserted a “stage” (from the right-click options). You can think of a stage as a single transaction. The stage can have as many components as you want but it is best to have the stage represent some meaningful single action. Since I just want to validate a credit card, the stage will have a single component.
To insert the component, I chose “Insert Component” from the right-click choices on the stage. Figure 2 shows the list of component choices that are available to all stages. The “ValidateCCNumber” is the component I chose.
Figure 2: Components Available to All Stages
The Credit Card Validation component requires the following orderform fields to be filled in for the component to have enough information to validate the credit card: Order.cc_type, Order._cc_number, Order._cc_expmonth, Order._cc_expyear. The cc_type has to be the name of the credit card type such as “American Express”. The number should be a valid number for the specified credit card type. The month and year should also be numeric.
The component that you are planning on using will have a list of required and optional fields from the orderform. You use the pipeline editor in order to view the component’s field list. Figure 3 shows the pipeline open, with the Credit Card Validation component’s properties available. This figure shows three stages but for now, you only need to focus on the middle stage named ValidateCCNumber. The first and last stages are for debugging, which I’ll get to later.
Figure 3: The Order Form Fields
Now that the pipeline is created with a single stage, you need to save the file into the “/Config” subdirectory in your commerce web site. The file extension should be “*.pcf”. A copy of the pipeline used for this article is available.
The last piece is the code for the ValidateCreditCard function shown in Listing 2. The function returns the error from the execution of the pipeline or nothing at all (meaning the credit card information passed the validation). This code only inserts the required READ properties for the credit card validation component, but it could also have been an orderform with more information including the product list. The orderform variable is set to a commerce orderform. Then the four required properties are filled in. The brackets around the orderform names are required because of the leading underscore in the name. This is a VBScript issue and not a commerce server issue. The UtilGetPipeContext is a function available from i_util.asp. Don’t change the function, just call it. The next call is the UtilRunPipe which is another function from i_util.asp. The first parameter is the pipeline file “validatecc.pcf”. You don’t need to specify the “/Config” directory but the file does need to be in that directory. The second parameter is the orderform object that was just created and filled in. The last param is the pipeline context created from the previous call. The component will place any error messages in the “_Purchase_Errors” Dictionary object of the orderform. You can see that this is a written value from Figure 3. Since the “_Purchase_Errors is a Dictionary object, the code should check to a count of errors to determine if an error occurred. The code returns an empty string if there are no errors.
Listing 2 – ValidateCreditCard function
'------------------------------------------------------------------------------
Function ValidateCreditCard()
sReturn = ""
'create dictionary object orderform
'only add required fields
set orderForm = Server.CreateObject("Commerce.OrderForm")
orderForm.[cc_type] = sCardType
orderForm.[_cc_number] = sCardNumber
orderForm.[_cc_expmonth] = sExpMonth
orderForm.[_cc_expyear] = sExpYear
REM -- Create the pipe context
set mscsPipeContext = UtilGetPipeContext()
REM -- Run the plan
errorLevel = UtilRunPipe("validatecc.pcf", orderForm, mscsPipeContext)
if orderForm.[_Purchase_Errors].Count > 0 then
sReturn = orderForm.[_Purchase_Errors](0)
end if
ValidateCreditCard = sReturn
End Function
If errors are found, a string is placed in the first element of the “_Purchase_Errors” Dictionary object. You can determine the actual error string that has been returned. The InitMessageManager function in the global.asa fills in the message map with strings for various errors. This particular error is in the "pur_badcc" variable. The line in the global.asa would look like Listing 3. The message manager is meant to be a single location for your commerce application strings. If you want to translate you Web site into a different language, you only need to hand one file to the localization team.
Listing 3 – Error message for a bad credit card number
call MSCSMessageManager.AddMessage("pur_badcc", &_
"The credit-card number you provided is not valid. " &_
"Please verify your payment information or use a " &_
"different card.")
If the credit card number is not validated, the error message will show at the top of the ASP page (shown in Figure 4). Of course, once you have the error string, you can do anything that you want to with it. This is just an example.
Figure 4: Web Page Shows Error.
Since the pipeline works as a component that runs other components, we can not easily look at what is happening to the orderform as it is happening. But we can add a stage above and below the credit card validation stage that logs the orderform to a file on our system. These should be stages that hold a Scriptor component. The Scriptor component runs a VBS script. This makes it easy to add code to the pipeline stage without having to compile the code into a pipeline component. The scriptor will run an external file called “dumporder.vbs” which is available in the Site Server SDK under the samples directory.
To add this file to the scriptor, choose the properties of the Scriptor component. The language field needs to correctly identify what scripting language the file is written in. The location of the file also needs to be specified. I included the dumporder.vbs file as an external location from the SDK installation directory. The last parameter indicates where I want the orderform variables to be dumped. I choose the first stage to dump to “c:\validatecc_dumporder1.txt” and the last stage to dump to “c:\validatecc_dumporder2.txt”. Figure 5 shows this information for the Scriptor component.
Figure 5: Scriptor Component Properties
You should only add the dumporder.vbs to the pipeline for testing or debugging. When you want to take the site live, you should remove these stages from the pipeline.
If you run the page with these two dumporder stages, you will notice that two log files have appeared in the root of the c drive. Listings 3 and 4 show the orderform log file before and after the credit card validation stage. Listing 4 is based on a bad credit card number, so an error was returned. Notice that all of the fields are the same except for the “_Purchase_Errors”.
Listing 3 : The Orderform Before the Credit Card Validation Stage
** Orderform Contents **
Items List
End of Items List
Order Key is [_Basket_Errors] Start List
End of List
Order Key is [_Purchase_Errors] Start List
End of List
Order Key is [_Verify_With] Start Dictionary
End of Dictionary
Order Key [cc_type] {String} Value [American Express] {String}
Order Key [_cc_number] {String} Value [] {String}
Order Key [_cc_expmonth] {String} Value [1] {String}
Order Key [_cc_expyear] {String} Value [1998] {String}
** End of Orderform Contents **
Listing 4 : The Orderform after the credit card validation stage
** Orderform Contents **
Items List
End of Items List
Order Key is [_Basket_Errors] Start List
End of List
Order Key is [_Purchase_Errors] Start List
Value [The credit-card number you provided is not valid.
Please verify your payment information or use a different card.] {String}
End of List
Order Key is [_Verify_With] Start Dictionary
End of Dictionary
Order Key [cc_type] {String} Value [American Express] {String}
Order Key [_cc_number] {String} Value [] {String}
Order Key [_cc_expmonth] {String} Value [1] {String}
Order Key [_cc_expyear] {String} Value [1998] {String}
** End of Orderform Contents **
