Documentation for Yams 0.6.2

About Yams

Features include:

Obtaining Yams

Yams Requirements

Installing Yams

Preparing the database

Two accounts need to be created, one for the http_auth database and one for the commerce database.

The tables can be created via the command line: mysql < tables.sql with all the necessary flags and arguments to mysql for logging in as the correct user.

Installing the code

The "commerce" directory inside of scripts should go inside of your cgi-bin directory or directory containing scripts to be run as Apache::Registry scripts. The "commerce" directory inside of the html directory should go into your htdocs directory structure.

Preparing the Web Server

If running under Apache::Registry, all the modules should be preloaded and initial database connections should be opened in the perl-startup.pl file. The additional code is provided in the perl-startup-add.pl file included with the distribution.

More Information

Upgrading

From 0.6.1 to 0.6.2

No database changes are needed.

Running create_pds_table.pl in the script/utilities directory will populate the
tables used for the product description search.

Yams/Cart.pm, shop/toplevel.pl, and shop/cart.pl were updated.

From 0.6.0 to 0.6.1

The following tables need to be added to the database

CREATE TABLE product_description_search (
        sku varchar(15) NOT NULL,
        descriptions BLOB,
        PRIMARY KEY(sku));

CREATE TABLE related_product_data (
        id integer NOT NULL DEFAULT 0 AUTO_INCREMENT,
        sku varchar(15) NOT NULL,
        related_sku varchar(15) NOT NULL,
        PRIMARY KEY(id));

From 0.5.7 to 0.6.0

CREATE TABLE session_ids (
	session_id VARCHAR(24) NOT NULL,
	shopping_cart_number INTEGER,
        host_reference VARCHAR(50),
        string_reference VARCHAR(30),
	url_reference VARCHAR(100),
        date DATETIME,
        PRIMARY KEY(session_id));

ALTER TABLE orders ADD host_reference VARCHAR(50) NOT NULL DEFAULT '/', 
	ADD string_reference VARCHAR(30);

From 0.5.6 to 0.5.7

From 0.5.5 to 0.5.6

ALTER TABLE download_product_data ADD COLUMN duration INTEGER NOT NULL;

From v0.5.1/0.5.2 to 0.5.5

ALTER TABLE orders MODIFY order_status 
	ENUM ('NEW', 'ASSEMBLING', 'PENDING CHARGE', 
                           'FULL SHIPMENT', 'PARTIAL SHIPMENT', 
                           'NO SHIPMENT', 'CANCELED') NOT NULL;
ALTER TABLE order_status_history
	MODIFY order_status ENUM ('NEW', 'ASSEMBLING', 'PENDING CHARGE', 
                           'FULL SHIPMENT', 'PARTIAL SHIPMENT', 
                           'NO SHIPMENT', 'CANCELED') NOT NULL;
ALTER TABLE order_status_history DROP PRIMARY KEY;
ALTER TABLE order_status_history ADD id integer NOT NULL DEFAULT 0 
	AUTO_INCREMENT, ADD PRIMARY KEY(id);
ALTER TABLE order_status_history DROP comments;
ALTER TABLE orders ADD comments BLOB NOT NULL;
ALTER TABLE products ADD COLUMN inventory_comments BLOB;
ALTER TABLE subscriptions ADD expired CHAR(1) NOT NULL DEFAULT 'N';
CREATE TABLE bundle_product_data (
	id integer NOT NULL DEFAULT 0 AUTO_INCREMENT,
	bundle_sku varchar(15) NOT NULL,
	item_sku varchar(15) NOT NULL,
	PRIMARY KEY(id));

From v0.5.0 to v0.5.1/0.5.2

ALTER TABLE orders ADD shipping_vendor VARCHAR(12) NOT NULL;
ALTER TABLE orders ADD tracking_number VARCHAR(34) NOT NULL;
ALTER TABLE products ADD intl_shipping_cost DECIMAL(8,2) NOT NULL;

Mailing Lists

Configuring Yams

YamsGlobals.pm

CreditCard.pm

Template.pm

Future plans are to improve this templating mechanism. Below are descriptions of what the functions and variables in Template.pm are used for.

%departmentImages is a hash associating each department with a graphic to display to indicate which department the product list is for. This is only used internally in the module.

$top_navigation is internal and only used in the module. It defines the code to be used for the top navigation bar portion of the template.

&printBranding in internal and only used in the module. It prints a standard header/"branding bar" on each page that is dynamically generated.

&printTemplateHead is used to print out the generic header we use for a lot of the pages. The argument determine which header graphic should be displated above the dynamic content and below the navigation bar. This is called from other modules to display the template header.

$template_foot contains the code needed to close all the tables that are defined in the generic header. This variable is exported and should probably be wrapped in a function.

&printProductListHead is a slightly different version of the generic header. It adds in a graphic depicting which department the following product list is for. It is used when displaying a list of sub departments for a given department or for the list of products for each department. It is called from within the printProductList subroutine in Cart.pm

$product_list_foot closed what printProductListHead started.

&printProductForTemplateList prints out the product description to be part of the product list for a department. It is called from within printProductList in Cart.pm also.

&printTemplateProductDetail displays the long product description for a product in templated form.

&getAd is internal to the module and probably not useful to anyone else. It generated a random ad from a list to place into the branding bar. This is a quick fix until I figure out how to include a SSI in dynamic output.

&printSubProductListHead prints out yet another version of the header if we are trying to display a product list by subdepartments.

&printSubProductListHead prints out yet another version of the header if we are trying to display a product list by subdepartments.

&printAffiliateProductForTemplateList display an affilaite product within the product list framework. It allows you to place a link to the affiliate's site to purchase the item rather than sell it through your own channels. We are planning on using this feature to list books from Amazon; incorporating it into Yams allows us to dynamically generate those pages and hopefully make adding and subtracting books easier.

Shipping.pm

Future plans are to increase the number of possible calculations.

Shopping with Yams

1. Customer visits front page of store.
2. Customer chooses department.
3. Customer is presented with a product list or a list of subdepartments to choose to from.
4. Customer has three options for each item
   1. More info - this brings up a detailed product information page
   2. Add to Cart - this puts the item into the users cart
   3. Add to Cart and Login - this puts the item into the user's cart and prompts them to login or to create an account.
5. If customer select "More Info" he then has the option to "Add to Cart" or "Add to Cart and Login."
6. Once item is added to cart user can
   1. Adjust item quantities, 0 to remove. Electronic goods are limited to a quantity of 1.
   2. Place an order.
7. Customer places order.
8. If the customer has not yet logged in, he is prompted to login or create a new account.
9. If the customer creates a new account and the option is one, the username and password will be mailed to the customer.
10. Customer is then prompted for billing information. Customer also chooses where to ship the product: billing address, other address, multiples addresses.
11. Customer is prompted to add/edit addresses and then choose where to send the order, or even the items on an item by item basis.
12. Customer can also change the item quantities, or choose to save some of the items for later orders.
13. Customer is presented with a preview of the order, with links to go back and change the billing information, shipping address, or quantities.
14. Customer places order, is presented with a confirmation screen and receives a confirmation email.

About Search

If you have an existing installation of yams, you can run scripts/utilities/create_pds_table.pl to populate the searching of descriptions.

Adminstering Yams

Orders

• View new orders
  This option allows the administrator to view all orders with a status of NEW.
• View all orders
  Displays all orders in the system.
• Select Orders to View
  Displays a form allowing the administrator to view a specifc order number or choose the set of order stati to view.
• View Payment Data
  This options displays the list of orders and associated payment info and if the credit card has been charged or not.
• Print Labels
  Prints out the shipping addresses for all orders that have a status of NEW and a product that is of the SHIPPED type in a table.

Updating Orders

At the top of the page is a list of the ordered items, the merchandise total, the sales tax, and the final total. For each item there is a popup menu for the item status and another for the order status. Then the customer's shipping and billing information as well as the results of the credit card verification are shown. The customer's username is printed if an e-good is part of the purchase. Next are the three values returned by the credit card processor. The first is the vendor's authorization number, and next are two advisory values about whether or not the zip code and address match the card. The last item on the order page is the status of the charge on the credit card.

Item Status Values

• IN_STOCK
  The item is in stock
• ON_ORDER
  The item is on order.
• BACK_ORDER
  The item is back ordered.
• RETIRED
  The item is no longer available.
• SHIPPED
  The item was sent to the customer.
• CANCELED
  This item in the order was canceled.

• NEW
  No action has been taken on the order.
• ASSEMBLING
  The order is in the process of being put together.
• PENDING CHARGE
  The order has been filled and sent ot the customer but the credit card has not been debited.
• FULL SHIPMENT
  The whole order was filled and sent to the customer. The credit card was charged.
• PARTIAL SHIPMENT
  Some items were sent to the customer.
• NO SHIPMENT
  No items were sent to the customer.
• CANCELED
  The entire order was canceled.

• UNCHARGED
  The credit card has not been charged.
• CHARGED
  The credit card has been charged.
• PAID
  The credit card charge has been paid into your merchant accoutn.

Changes are made by using the "Update Order" button after the various stati have been adjusted appropriately.

Notes

Departments

• Show Departments
  Displays a list of all the departments.
• Add a Department
  Provides a form for adding a department to the list.
• Show SubDepartments
  Displays a list of subdepartments.
• Add a subdepartment
  Provides a form for adding a subdepartment to the list.

Adding/Editing a Department

Adding/Editing a Department

Categories

• Show Categories
  Displays a list of categories.
• Add a Cateogry
  Provides a form to add a category.

Adding/Editing a Category

Affiliates

• Show Affiliates
  Displays the list of affiliates.
• Add Affiliate
  Provides a form for adding an affiliate.

Adding/Editing an Affiliate

• Affiliate Name - name of the affiliate, will show up in any product listing with a type of AFFILIATE with the text "Buy this item from affiliate name."
• Buy URL Start - beginning of the URL to direct the user to the affiliate's page. This can be a URL directly to the page or the path a redirect script on your own site. The product id, specified in the product creation, is appended to this URL.
• Image URL Start - this is the beginning of the image URL to display a small image of the item. This value is override if the "Small Image Path" is set in the product information. The product id, specified in the product creation, is appended to this URL.
• Buy URL End - this piece of the URL is appended after the product id.
• Affiliate description - description of the affiliate, only seen in the administrative side currently.
• Status - specifies whether the affiliate is active or retired.

Products

• Show products by category
  Display the products seperated into the various categories.
• Show products by department
  Display the products seperated into departments.
• Show products by subdepartment
  Display the products seperated into subdepartments
• Add a product
  Provides a form for adding a product.

Adding/Editing a Product

• SKU - Stock keeping unit number. Simply a number used to track the product internally.
• Name - Name of the product as it will appear to the customer.
• Category - Category that the product is in.
• Department - Department that the product is in. If subdepartments are turned on, then it will be the department-subdepartment pair that the product is in.
• Platform - Which platform the products is inteded for. Possible values are:
  • ANY - product works with any platform
  • LINUX - products work with linux (*nix) systems
  • MAC - product works with Macintoshes.
  • NA - not applicable
  • WIN - products works with computers runnign Windows.
  • WIN/MAC - products works with both Macintosh and Windows machines.
• Type - What type of product this is. Possible values are
  • SHIPPED - indicates a product you have in stock and are responsible for shipping.
  • DROP SHIPPED - indicates a product you sell in conjunction with a third party who is responsible for shipping the item.
  • SUBSCRIPTION - indicates a subscription area of the website.
  • DOWNLOAD - indicates a subscription area of the website with a specific item to download
  • RENEWAL - specific form of the subscription used to allow users to renew subscriptions.
  • AFFILIATE - indicates a product displayed on your pages but actual ordering is done through the affiliate's pages.
  • BUNDLE - indicates a product that is composed of other already existing products. A bundle cannot contain another product of the BUNDLE type.
• Group Name - Used for subscriptions, downloads, and renewals only. Specifies the name of the subscription that should be used for controlling access to this product. To show up in the list, a subscription must be defined by using the "Add Subscription" option.
• Duration - Used for subscriptions and renewals only. Specifies the length (in month) of the supscription product.
• URL to download - Used for downloads only. The URL of the product that the customer bought. Displayed if auto insertion for the downloads products is turned on.
• Product ID - Used for affiliate products only. Identifies the product as the middle section of the buy url.
• Affiliate Name - Used for affiliate products only. Identifies which affiliate this product is being sold through.
• Products in Bundle - This is a list of available products that can be put into a bundle.
• Short Description - A short description of the product that appears on the product listing page.
• Long Description - A longer description of the product that appears on the right side of the display detail page.
• Other Text - As much additional text as you need to describe the product, appears below the large image and long description on the display detail page.
• Small Image Path - path to the image to use in the product listing.
• Large Image Path - path to the image to use in the product detail page.
• Price - price of the product.
• Taxable - whether or not the product is taxable.
• Weight - needs to be specified if using the UPS or other dynamic shipping calculation. Weights of zero are ignored when calculating shipping.
• Domestic Shipping Cost - needs to be specified for calculating shipping using the static method.
• Internation Shipping Cost - needs to be specified for calculating shipping using the static method.
• Initial Stock - for products that you keep in stock, how many are you starting with.
• Threshold Quantity - Eventually there will be a utility that will detect when an item's stock falls below this value and notifies the administrator.
• Related Products - Choose the products that should be soft sold when this product is placed into the cart. This option can be toggled by chagning the value of $display_related in YamsGlobals.pm
• Status - identifies the status of the item. See "Item Status" in the orders section for more details.

Inventory

Subscriptions

Show Subscription Areas

Add Subscriptions

• Name - name of the subscription. This will show up in the popup menu on the add products page.
• Group Name - this is the name of the group that the user has to be a member of in order gain access to the subscription materials. This also requires web server configuration.
• Description - descibes the subscription.
• Status - indicates whether this is an active subscription or not.

Add User to Subscription Group

• Order Number - Enter the order number in which the user purchased access to the subscription area otherwise enter zero.
• User name - case sensitive user name that is to be added to the subscription area
• Subscription - Subscription to add the user to.
• Duration(in month) - How many months to give the user access for.

User Management

Sites Using Yams

Bugs, Patches, Comments

Future Plans for Yams

• Tool to let user check on status of order.
• Handle gift subscriptions
• Create new products by copying from old
• Enhance titles of shopping pages.
• Clean up form processing code.
• Finalize mechanism and information needed for download product type.
• Tools to sync product/category/department tables between databases
• Include user registration forms/tools for use outside of the commerce system
• Additional reports on the administration side.
• Add other methods of calculating shipping costs.
• Localization
• Install script
• Improve inventory capabilities
• Preview capabilities for product listings

Version History

0.6.2

• fixed problems with the proper headers not being sent when the server side includes were used under mod_cgi (toplevel.pl, cart.pl)
• fixed problem where displaying empty departments did not work properly (Cart.pm)
• fixed problem where creating session id was causing a warning message (Cart.pm)
• added utility to initialize the search function with the existing product descriptions (create_pds_table.pl)

0.6.1

• introduced simple product search mechanism -user can search for keywords in name of product or in the product description.
• introducted related products - at product creation time, related products can be chosen for the new product and these products will be soft sold to the user after the product is placed in the cart
• fixed problem with printLabels in Reports.pm where bundle products with shippable products would not show up in the label list.

0.6.0

• added concept of session ids
  • allows for store server and secure server to have differnt urls
  • allows for tracking of where customer came from
  • allows for placement of "Return from whence you came" link at the end of the ordering process
• changed behaviour of state field - popup for USA, textfield for other countries
• more quoting cleanup
• updated revenue report to display report for each referrer to store
• strip spurious characters from address before passing to Signio tool
• carts now combine correctly when user logins after starting with "anonymous" cart
• renewals now properly update order number in subscriptions table
• Fixed problem where program would die without leaving an error message if an address was not chosen from the list for non-billing address shipping

0.5.7

• Fixed security hole where customer id was being stored as a hidden field in some order pages - it not longer does so.
• Removed spurious database connect in Cart.pm
• Fixed problem with wrong warning message being shown in Order.pm
• Fixed problem with renewal of expired user who is still within grace period.
• Fixed some problems with improper quoting of department names.

0.5.6

• Changed download product to have a granularity of days in the length of a user is authorized to download the product; also moved that duration into the product definition and out of YamsGlobals.
• Fixed typo in the SQL used to convert a product to the DOWNLOAD type from a previous type
• Fixed problem with auto-increment column not being specified as a key in the definition of order_status_history in table.sql
• Fixed problem in totalling sales_tax in revenue report.

0.5.5

• Updated problem with order_status_history table - history is now recorded.
• Comments can be stored with each order
• Fixed SQL in AdminUser.pm
• Added ability to add custom text to email sent to new user
• Broke up "All Orders" listing by day
• Added need order_status "PENDING CHARGE"
• Fixed problem with two word country names in YamsGlobals.pm
• Egood orders that are automatically filled now go to "PENDING CHARGE" rather than "FULL SHIPMENT"
• Fixed problem with product status of "RETIRED" not working
• Fixed problem with inventory being decremented twice in some cases
• Added comments field to each product in the inventory section
• Added support for bundling products together
• Changed form field for group_name for electronic products from textfield to popup menu
• Updated "Revenue Report" to pull in all types of revenue instead of just products sold
• Changed display of "All Users" from one big table to a series of smaller ones
• Fixed problem with foreign postal codes being truncated
• Fixed problem with incorrect shipping calculation for customers with a billing address in the US and a shipping address outside the country.
• Order cannot be placed if egood purchase is not appropriate.
• Added cron jobs to automatically notify and expire subscribers
• Reset notification fields on renewal
• Fixed problem with non-USA addresses requiring a state

0.5.2

• Fixed problem with SQL for the inserting of products

0.5.1

• fixed typo in SQL queries in Subscription.pm ("subscription_type" to "group_name")
• fixed typo in Order.pm ("Sales" to "Sales Tax")
• Added support for associating a shipping vendor and tracking number with each order.
• Added support for specifying a static international shipping charge
• Expanded list of countries from OTHER to one containg those countries we've taken orders from.
• Static internation shipping cost now part of item description.
• Fixed typo in many form elements - changed "maxleth" to "maxlength"
• Fixed problems with zip+4 returning an error if dynamic shipping is selected.
• Added missing quotes to SQL statement in AdminUser.pm
• Added "print labels" functionality
• Added more documentation about Template.pm
• Added line to tables.sql to allow it be read as input directly into mysql.
• Other typo corrections

0.5.0

• Initial public release.

Credits

Drew Taylor
TrouBle
Michael Nash
"nytshade"
Otis Gospodnetic
Patrick Boutilier
Philip Wall
Donald L. Greer, Jr
Roscinante
Tommy Gunn
Gaelyne Gasson
as well as anyone I may have mistakenly left off this list.