I. Introduction
This document summarizes the data objects and data flow that occurs in the "shopping experience" and related events in the (new) Danly web site.  It assumes basic knowledge of the database tables established by Websphere, and some understanding of net.data macro files.  You should also see the customfields.xls spreadsheet, which details 'custom' use of certain websphere database table fields.

This document is proprietary information, and should only be distributed by IBS or Danly personnel.  It is subject to frequent revision(!).

II. Users
Before shopping at the site, individuals must register at the site, via the "new user" link on the home page.  Note some definitions:

• A "new user" is a person that is just registering with the site. 
• An "existing customer" is a company that already does business with Danly, and has the ability to use purchase orders (which assumes a line of credit?) to order Danly products.
• A "new customer" is a person who is registering as a new user, and also buying products from Danly from the first time, presumably thru the web site.

Thus, an existing customer may still be a new user.

New users register by entering their e-mail address as their "login" id (hence called "login"), choosing a password, and specifying various contact information (name, phone, company).  The login is used both to authenticate them at the site, and as an e-mail address to contact the user.  Each new user gets a row in the SHOPPER table. 

New users specify whether they are an existing Danly customer.  They may choose to:

• Shop only via purchase order, in which case they can shop but not checkout until Danly enters customer/pricing data for them.  Only existing customers get this choice.
• Shop via credit card, in which case they must enter a ship-to address and a bill-to address.  All customers have this choice.

Each new user gets a row in SHADDR with their contact information; this is called a "contact" row and is marked with a "C" in field SAFIELD2.  Existing customers get another row in SHADDR for their ship-to information, initially mostly empty, marked with a "T".  This information gets updated by Danly.

Credit-card customers (remember, they can be new customers or existing customers) get a SHADDR ship-to address row (marked with an "S"), and a SHADDR bill-to address row (marked with a "B").  The new user-registration process requires them to enter data for one of each (ship-to, bill-to).

All new users get a row in DANLY_SHCM that determines their CMSTKY ("ship-to key").  Initially their CMSTKY is tied to their (one) ship-to address, and is set to "999998", which essentially means "list prices". 

Once a user has registered, they can change or add to their information from the "My Account" link.  A user only has one "C" row, and may change any of their contact information except the login.  They may have multiple "S" or "T" rows, each of which has/gets a corresponding DANLY_SHCM row.  They may have multiple "B" rows.  Users can change/add their "S" or "B" rows at will; only Danly can add or change "T" rows, which are the rows that get used for purchase-order shopping.

New-user registration is implemented by

• home.d2w  Home page; determines if user is logged-in, or offers link to new user registration
• newuser.d2w  First new-user registration form; collects login, password, contact info, and existing-customer status.
• new1.d2w  Handles error output (from RegisterNew command) in a separate window, and/or redirects main window to next page.
• newuser2.d2w  Gets first ship-to and bill-to address for credit card shoppers.  Runs AddressAdd command(s).
• makecart.d2w  Creates a shopping cart for the user, with a dummy product.
• makecart2.d2w  Deletes the dummy product.
• homenew.d2w  Looks like home.d2w (to the user), but finishes registration process by adding row to DANLY_SHCM and e-mailing Danly about new registrant.

III. Shopping Carts
Once a user is logged in, most of the site pages automatically display a header that looks like:

Welcome, Mr. Phelps.  You are shopping for Mission Impossible.

Any mouse-over on the link displays a DHTML menu of all the different sites ("S" or "T" SHADDR rows) for that user.  (If there is only one site for the user, the text does not appear as a link). Clicking on a site in the menu redisplays the page with the new site name in the header.  The idea here is that a given user may shop for multiple sites, but is always shopping for one particular site at a time.  The most recently chosen site for a user is recorded by the timestamp row SHCMDATE in DANLY_SHCM.

This also means that each user has exactly one shopping cart per site.  Shopping carts "persist", meaning that their contents are kept across login sessions.

The implementation of shopping carts was, ah, interesting.  The default Websphere implementation of shopping carts (using the SHOPPINGS and related tables) proved insufficient to our needs; in particular, the default shopping carts do not remember quantities of items.

Our current implementation of shopping carts uses the ORDERS table instead.  Each shopping cart is really an order, with field ORSTAT set to "P" (pending), and (otherwise unused) field ORDESCR set to the SHADDR row number of the "site" the user is shopping for.  This actually proved quite elegant, since the translation from shopping cart to order becomes trivial during check-out.

Shopping carts are implemented by:

• proddisp.d2w  Adds a product to the cart.
• itemdisp.d2w  (ditto)
• ocart.d2w  Does all the work of displaying and updating a shopping cart.

IV. Checking out
When a user is satisfied with their shopping cart, they click on "proceed to checkout".  This takes them through 8 steps (net.data macro files, which produce HTML pages), which verify and set additional information, before the order is fully placed.

1. acctship.d2w  Finalize bill-to address, ship-to address, order confirmation e-mails, shipping method, and shipping preference (ship everything together, or in pieces as they are avilable).

   Because for non-purchase order shopping, customers are allowed to change (over-ride/over-write) at least the ship-to (and maybe the bill-to) information at this step, we need yet another place to store this info.  Therefore we've added yet another type of SHADDR row, the "Z" row.  Once this page is completed, the ship-to information is stored in a "Z" row.  If a user aborts checking out a cart after this page (but before the final order page), this changed information is kept in the "Z" row, and is used (loaded) the next time the user returns to this page.  (Once the order is completed/fulfilled, we'll need a way to delete the "Z" rows.)

   To summarize:

   • Updated ship-to is kept in a "Z" row, and field STSANBR in each ordered item row in SHIPTO is updated to point to this row.
   • Selected bill-to address (from menu) row is stored in ORDERS, field ORBLLTO
   • Updated confirmation e-mails are also kept in the "Z" row.
   • Shipping method and shipping preference are stored together, encoded, in ORDERS, field ORFIELD1.
   • Total cost of order is stored in ORFIELD2 (since ORPRTOTAL is automatically generated).

   Acctship.d2w calls the AddressAdd command to write the "Z" row, chaining to acctship2.d2w, which is evaluated in a pop-up window.

2. acctship2.d2w  Updates the ORDER row to contain the encoded shipping method and preferences (in orfield1) and the proper bill-to address (orbllto).  Updates all of the line-item SHIPTO rows to point to the new "Z" SHADDR row. 

   Redirects the main window to payment.d2w, and closes the pop-up.

3. payment.d2w  Display one-line summary of each line-item in the order.  Write the unit price into each line-item in the order (each SHIPTO row).  Get payment information, one of:
   • Purchase order number (if existing customer who doesn't use credit card)
   • Credit card info (if new customer)
   • Either one (if existing customer who also can use credit card)

   Calls order1.d2w in a pop-up window.

4. order1.d2w  Assembles the payment data (from the form in payment.d2w).  In the ORDERS row, writes the encoded payment info in orfield3, writes the total price (orprtot), and "locks" the row (orlock).

   Calls the OrderProcess command for further processing: (a) to invoke MQSeries, and (b) to do credit card verification (if needed), and (eventually) (c) to do CyberCash payment processing.  If OrderProcess succeeds, it writes a 'C' into orders.orstat.

5. orderaccept.d2w is automatically called (still in the pop-up window) when OrderProcess finishes (which we defined by setting the appropriate entry for OrderProcess in the MACROS and TASKS tables). 

   Orderaccept converts the order from a shopping cart to a real order (clears ordescr); unlocks the ORDERS row, sends the e-mail confirmation(s) to the shopper, and redirects to makecart.d2w

6. makecart.d2w is used to create a new, "empty" shopping cart.  It prepares some information (a dummy product), and calls the OrderItemUpdate command to create the new cart with the dummy product.  When OrderItemUpdate is complete, it continues with makecart2.d2w.

7. makecart2.d2w fixes up the merchant number in the newly created shopping cart, deletes the dummy product, redirects the main window to confirm.d2w, and (finally!) closes the pop-up window.

8. confirm.d2w  Display order confirmation and order number. 

Note:  The "generic dealer portal" version of the checkout process operates somewhat differently.  It writes a complete order in the normal way, but the order is not passed to MQ series.  Instead, the order is sent as a text e-mail to the dealer.  The numbered sections below note the changes to the proceeding process for the dealer portal.

3. payment.d2w  Only purchase orders may be used; there is no credit card entry or processing.

4. order1.d2w  No locking is done.  OrderProcess is not called.  Goes directly to orderaccept.

5. orderaccept.d2w (still in the pop-up window) actually marks the 'C' in orstat, but does not (need to) do any unlocking.  It sends the user's e-mail confirmation as before, except that code has been moved into an include file, mailconfirm.i.  It then transfers to a new file, orderplace.d2w.

   5a.  orderplace.d2w sends the e-mail order to the dealer.  That code is implemented in the include file mailorder.i.  It then continues on with makecart.d2w in the normal way.

V. Cleaning up
The Danly site will, over time, generate many rows in the database that can (and should) be "cleaned up".  In particular:

1. SHOPPER gets a new row (session_id) for each non-logged-in shopper that is browsing.  (Can check for SHSHTYP='G' and SHRSTMP over a day old to find rows that can be gotten rid of.)

2. SHADDR gets SAFIELD2='Z' rows added for each order actually processed.  Can probably ditch anything with SASTMP more than a few days old (??).  Also, SHADDR rows with SAADRFLG='T' can be removed at any time.

3. Completed ORDERS rows (ORSTAT='C') should also be removed (eventually) after the order is processed (delivered??).  These orders also "own" SHIPTO rows that probably have to be deleted first.

---