To configure a pipeline, you use the Pipeline Editor. (Microsoft offers a Win32 and an HTML version of this tool. I'll use the Win32 application for this discussion, but the same features are available in both versions.) Using SSCE's Site Foundation Wizard and Store Builder Wizard, I constructed a simple mock site I called Eddins Product Catalog. Using the Pipeline Editor, I added a custom OPP Scriptor component to the purchase pipeline (purchase.pcf) the Store Builder Wizard created. I used the Scriptor component to make a final inventory adjustment at the beginning of the Accept stage that reduced the inventory count for specific items in an OrderForm. The simple database table that Screen 2, page 71, shows represents my inventory system, which the Scriptor component will update with the appropriate SKU counts.
To create the Scriptor component, I open purchase.pcf for Eddins Product Catalog in the Pipeline Editor. Next, I select and right-click the first OPP COM object in the Accept Stage. From the resulting context menu, I select Insert Component, Before. From the resulting Choose a component dialog box, I select the Scriptor entry from the Components list and click OK. The system then adds the Scriptor object to the pipeline above the SQLItemAdo horizontal section.
To set the new object's properties, right-click the new Scriptor object and select Properties. The system then displays the Component Properties dialog box, which Screen 3 shows. The Scriptor tab in this dialog box includes three fields: In the Scripting Engine drop-down list, you choose an available ActiveX scripting engine (JScript and VBScript are the default options). In the Source field, you specify where the system stores the script. Selecting Internal tells the system to store your script within the .pcf file, and this selection lets you edit the script by clicking Edit. If you select External, you can create a separate script file. In this case, you provide the system a full path to the file location in the Filename text box. If you select External, you can use the Config text box to pass runtime parameters, in the form of named value pairs, to the script for processing. For example, you can use the Config text box to pass an Open Database Connectivity (ODBC) string to the Scriptor component, which your script uses to dynamically choose the database to use at runtime. The script determines which named value pairs are appropriate or needed. In my example, I used Internal VBScript to program the Scriptor component that will update my inventory table, so the Config text box is not available.
Selecting Edit on the Scriptor tab takes you to a window with three predefined entry point functions that the Scriptor component will use to call your script. These functions are MSCSExecute, MSCSOpen, and MSCSClose. Screen 4 shows the initial Source Code Edit window with the skeletal entries for these three functions. MSCSExecute is the primary function that does the component's work; this function is where you put the bulk of your code. This function acts as the main module for the program, and it must be present in your script. MSCSOpen and MSCSClose are optional entry points for initialization or clean-up code for your object. The software runs the MSCSOpen subroutine immediately after you create the Scriptor component. The software carries out the MSCSClose subroutine when you destroy the Scriptor component. The Scriptor component strictly defines these three functions, so you shouldn't change their declarations. However, you can add functions to organize and develop your program. The script calls these additional helper functions from the MSCSExecute function.
Listing 1 shows the complete script for my inventory update. The MSCSExecute function directly hosts most of this code. I created a helper function that I called GetItemQuantity. It returns the item quantity for a particular SKU the shopper is ordering. The MSCSOpen and MSCSClose functions are not present in Listing 1 because I didn't include initialization or termination code.
At callout A in Listing 1, the script creates an ADO connection object and sets ConnectionString for the database hosting my inventory table (i.e., DSN=Commerce). At callout B, the script creates a Recordset object to hold the inventory records I need to update, and builds a SQL statement that retrieves all the inventory records for SKUs the shopper has ordered. The ASP store these inventory records in the OrderForm. Next, the code walks through the OrderForm items, picks the SKUs, and adds them to the list of criteria. This code leaves an extra comma at the end of the list, so I used the VB Left function to drop the last character. I appended the closing parenthesis, which resulted in a SQL statement similar to
"SELECT * FROM eddinswear_inventory where sku in ('001-001','001-002')"
At callout C, this SQL statement populates my Recordset object. The Recordset object will contain only those inventory records the shopper has actually purchased. Finally, at callout D, the script loops through the Recordset object and reduces inventory by the item quantity the shopper purchased.
At callout E, the job is finished, so the script closes the ADO connection and Recordset and destroys the objects by setting them to Nothing. At callout F, the script returns 1, which signifies that the table is updated.
The GetItemQuantity function, at the end of Listing 1, simply walks through the OrderForm items until it finds the SKU that matches the inventory record the script is in the process of updating. When GetItemQuantity finds a match, it returns the item quantity the shopper purchased, and that number is the amount by which the script reduces the inventory.
Reality Check
We've just used the Scriptor component to create a custom OPP COM object. You might have noticed that my code doesn't have any error handling. Definitely add good error checking to any code you develop, especially if you're accessing a database. SSCE provides a well-documented structure for managing errors, and the OrderForm includes list objects for recording any Basket_Errors and Purchase_Errors the software discovers during OPP processing. Microsoft also provides a special MessageManager object that stores error messages in multiple languages, which OPP components can use to describe error conditions the software generates during OrderForm processing in a location-specific manner.
The work performed in the example is, of course, an example. To simply update one table, you would just use the standard SQLItemAdo object and a SQL stored procedure. However, with the Scriptor component and a custom script, you can add logging, more complex calculations, and more sophisticated integration with other systems.
A Word of Caution
If your script becomes very involved (over a hundred lines of code), consider creating a compiled OPP COM object using VB, Visual C++, or a tool other than the Scriptor component. Because the system interprets script, your Scriptor component script will perform slower than a compiled object.