Q-Shop Storefront System - Garrett's Muscle Car Museum Manual.pdf · Q-Shop Storefront System...

Copyright © QuadComm, Inc. 1999-2002

Q-Shop Storefront System

Version 2.5

14 April 2002


All rights reserved

http://quadcomm.com


Index

1 INSTALLATION REQUIREMENTS.................................................................. 5

2 SOFTWARE INSTALLATION........................................................................ 6

2.1 Copy of the files ...................................................................................6

2.2 Database Set-up...................................................................................7 2.2.1 Database System ............................................................................9 2.2.2 Troubleshooting.............................................................................10

2.3 Application Setup. ...............................................................................11

2.4 System Permissions .............................................................................11

2.5 Password-protect folders. .....................................................................12

2.6 Mail system. .......................................................................................12

2.7 Security ............................................................................................13

2.8 SSL Configuration................................................................................14

2.9 Debugging the application.....................................................................15

2.10 Test credit card number ....................................................................15

2.11 Browse layout ..................................................................................16

3 SITE PERSONALISATION ..........................................................................17

3.1 Shop Settings.....................................................................................20

3.2 Stock control features .........................................................................22

3.3 Shipping Cost Calculation......................................................................22

3.4 Tax Calculation...................................................................................29

3.5 Order States ......................................................................................31

3.6 Billing States ......................................................................................34

3.7 Product Availability ..............................................................................34

3.8 Others ..............................................................................................35

4 SHOP MAINTENANCE...............................................................................37

4.1 Administration web site ........................................................................37

4.2 Managing sections...............................................................................42

4.3 Managing products.............................................................................44 4.3.1 Price Options ................................................................................46 4.3.2 Related Products (Cross-selling) .......................................................47 4.3.3 Product Pictures............................................................................47 4.3.4 Modifying the way products are listed ...............................................49

ANNEX A. UPGRADE SCRIPTS.....................................................................52


ANNEX B. UPS MODULE.............................................................................53

ANNEX C. AUTHORIZE NET 3.0 MODULE ......................................................55

ANNEX D. DATACASH MODULE (BETA VERSION) ..........................................58

ANNEX E. Q-SHOP EXTERNAL PAYMENT GATEWAY FRAMEWORK....................60

ANNEX F. WORLDPAY PAYMENT MODULE (BETA VERSION) ...........................62

ANNEX G. PAYPAL PAYMENT MODULE (BETA VERSION) ................................66

ANNEX H. PAYBOX PAYMENT MODULE........................................................67

QUADCOMM Q-SHOP LICENSE AGREEMENT .....................................................74


QuadComm Q-Shop License Terms.

Please, read license agreement at the end of this document.

The text is a copy of the agreement accepted when placing an order online.


QuadComm Q-Shop Storefront System Manual v2.5

The QuadComm storefront system is completely based on ASP pages and does not need the assistance of components for maximum compatibility and to allow fast and easy personalisation. Only some special options may require a component (for example UPS integration).

The scripting language used is VBScript and it is recommendable to have some knowledge of VBScript together with HTML to personalise the storefront. QuadComm recommends VBScript 5.5 or newer and IIS 5 (Windows 2000) although is currently fully compatible with earlier versions. Future versions may require VBScript 5.5 or later.

This manual will explain the set -up, personalisation, maintenance and the technical architecture of the system.

When it is required to edit any information, always use a pure HTML or text editor instead of a visual HTML editor. We recommend Visual Interdev or Macromedia Homesite to edit Q-Shop.

1 Installation Requirements

To install Q-Shop it is required the use of an ASP compatible web hosting service. QuadComm has only tested this software under Windows NT and Windows 2000 on IIS 4.0 and 5.0 and these are the only platforms officially supported. However the system should also work without problems on other non Microsoft servers like O’Reilly’s Website Pro, InstantASP or Chilli!ASP. QuadComm is not responsible to make the system work on any non Microsoft Windows platforms

For the administration web utility it is strongly recommended the use SSL as for the checkout. Please, check the security recommendations provided in this document.

For the mailing subsystem it is needed the presence of IIS SMTP server and CDONTS server object installed. Alternatively you can use JMail (http://www.dimac.net/) or AspMail (http://www.serverobjects.com/ ). Additionally, Q-Shop can be modified very easily to use other mail components, which could provide additional functionality like encryption. For a list of components you can visit the QuadComm site at http://quadcomm.com/aspin. See section 2.6 for more details on the mail system.


2 Software installation

The installation of the software it is divided in the following steps:

- Copy of the files to the web server

- Database set-up

- Application set-up

- Password protection of admin web site

- Mail system configuration

- Personalisation (covered in the next chapter)

2.1 Copy of the files

The software it contains the following directories structure. Notice that all file references will be relative to the root folder referred to as “/”:

/ (root directory)

Main files of the storefront.

/images

Images used in the storefront (logos, buttons, graphics...).

/inc

Include files and code libraries for the storefront.

/cats

Pictures used for each section and/or subsection.

/prodspics

Pictures of products and their thumbnails. You must place here all the products images to be accessed from the store. All the product pictures are referenced from the storefront to this folder.

/admin

Files for the administration web site. This folder should be password-protected to be accessed only by the administrator. It is recommended to use SSL to access this utility as sensitive data like credit card information is accessed here.

/admin/inc


Include files and code libraries used in the administration web site.

/db

This is the folder containing the database. In an ideal situation this folder wouldn’t be under the web root to ensure maximum security. When this cannot be done then this folder should be password protected to avoid users accessing the database directly. If the folder cannot be protected we recommend changing the name of the folder and the database file.

Special permissions for /db:

- The user IUSR_machinename should have read/write permissions over this folder to be able to modify and update the database. Check this with your server administrator. (Required)

- This folder should be password-protected to avoid external users to access the database file. Check this with your server administrator. (Optional)

Remember that the personal information from users is stored here and you are responsible of its protection.

2.2 Database Set-up

The system comes with a database populated with sample information. First, it is needed to configure the system to access the database.

There are several options to configure the way the database connection is done: OLEDB, System DSN and DSN-Less.

a) OLEDB

The fastest way to access the database is trough the Microsoft OLEDB drivers. However it may be possible that they are not installed in your hosting service, contact your provider to know whether you can use them.

To use the Access database you will need the exact physical path of the MS Access database file. You may need to contact your ISP to know this or you could write an ASP page printing the result of Server.Mappath(“/db/store.mdb”). It will give the physical path that you need to use in the conx.asp file. In the example the path used is “C:\inetpub\q-shop2\db\store.mdb”.

We recommend using this method for best performance. To learn more about OLEDB visit http://www.microsoft.com/data/oledb/prodinfo.htm.

b) System DSN

First, it is needed to create a system DSN pointing at the .mdb file. This will often have to be done by your hosting service provider.

In the default code you will have to change “DSN_Name” with the name of your System DSN.


c) DSN-Less

If you want to use a connection directly to the database file you will need to know the physical path of the file, ask your provider for it or apply the same method explained in the OLEDB connection. This option is only available when using the Access database file and should only be used if an OLEDB connection is not possible.

In some cases hosting providers make you pay extra for defining DSN, if you want to avoid it is also possible to use a file DSN, you can see how to do it below.

Configuring the database access method

The files that you need to configure are \inc\conx.asp and \global.asa. They include examples of the three different connection methods.

First you will have to enter the information in the file \inc\conx.asp. The default file contains code similar to this:

<%

'==============================================================

' This file contains the database configuration. It also opens

' a connection object (Conn).

' The file also contains some constants definitions, SSL config.

' and colour settings.

'==============================================================

'Opens connection conn if it is not already open.

'Please, modify configuration with correct values

If NOT IsObject(conn) Then

Dim conn

Set conn = Server.CreateObject("ADODB.Connection")

On Error Resume Next

Password = "QS2002p"

'-------------------------------------------------------

'Pick ONE of the following configurations:

'(comment the others)

'For additional tech. info see

' - http://www.able-consulting.com/ADO_Conn.htm

'-------------------------------------------------------

'1. Configuration for System DSN

ConnStr = "DSN=DSN_Name;uid=;pwd=" & Password


'2. Configuration for file DSN (DSN-Less)

'ConnStr = "DBQ=c:\inetpub\site\db\store.mdb;Driver={Microsoft Access Driver

(*.mdb)};uid=;pwd=" & Password

'3. Configuration for OLEDB drivers (more efficient)

'ConnStr = "Provider=Microsoft.Jet.OLEDB.3.51; Data Source=

c:\inetpub\site\db\store.mdb; Jet OLEDB:Database Password=" & Password

'Example of OLEDB connection on Windows 2000 server (version 4.0)

ConnStr = "Provider=Microsoft.Jet.OLEDB.4.0; Data Source=

c:\inetpub\site\db\store.mdb; Jet OLEDB:Database Password=" & Password

'c)Example of OLEDB connection on Windows 2000 server (version 4.0) and MS SQL

Server 7.0

‘ConnStr = "Provider=SQLOLEDB; Data Source=OLYMP; Initial Catalog=Q-Shop; User

ID=sa; Password="

'-------------------------------------------------------

conn.open ConnStr

Notice that the code contains a line Password = “QS2002p”. In the code supplied this will be the default database password. Open the MS Access database and enter this password when requested. Then in Tools->Security select “Unset Database Password”, provide the password and press “OK”. Then in Tools->Security select “Set Database Password” and enter a new password, then press OK and close the database.

The new password should contain letters and numbers and it shouldn’t be obvious.

Edit conx.asp and set the line Password = “QS2002p” with the new password, example:

Password = “ADG154S”

Remember to comment out all ConnStr definitions other than the chosen one. You can do this by adding a single quote at the beginning of the line.

Now you will have to repeat the same configuration of the connection string in the file /global.asa, in function GetConnString. Remember to change the definition of the variable Password with the new password as well.

2.2.1 Database System


Q-Shop comes with an Access database and configured to use Access. However it can be easily migrated to SQL Server using the Import utility that comes with SQL Server 7.0 or the Upsizing Wizard Add-in available from Microsoft.

SQL Server is the recommended option as it is far more powerful and it offers very good performance under heavy use. Access is more limited and is ideal for low cost and low or medium load.

To use SQL Server you need to change the Database System setting in the administration site (Shop Settings). See section 3.1 Installation Requirements for more details. The options available are:

ACC: MS Access Database

SQL: MS SQL Server

If left empty the value “ACC” will be stored as default.

For a step-by-step tutorial on how to migrate the Access database to SQL Server 7.0 go to http://quadcomm.com/qshop/importsql/migration.htm.

To update the database system settings in a SQL Server environment you can run the following query in the Q-Shop database:

UPDATE Config_Table SET Content = “SQL” WHERE FieldName = “DBSystem”

2.2.2 Troubleshooting

These are some common errors that you may find:

- Provider not found Error

If you have correctly declared the database access methods and you get an error like:

ADODB.Connection error '800a0e7a'

Provider not found.

//global.asa, line 62

Check that your database connection settings are correct specially the file paths. If this doesn’t correct the problem then you may read these articles to look for a solution:

- http://support.microsoft.com/support/kb/articles/Q191/2/71.ASP

- http://support.microsoft.com/support/kb/articles/Q197/9/02.ASP

- Read only file Error

If you get a “Read only” error when accessing the shop this is a problem that can be addressed changing the file and folder permissions. Make sure that the database folder/file have write/change permissions for the user IUSR_machinename from the Internet Services Manager (MMC) console.


2.3 Application Setup.

In order to run the shop correctly it is needed that the folder containing the files of Q-Shop is defined as a web application. This will enable the execution of the file global.asa that executes very important code to initialise and close the application and user sessions.

One of the ways of checking this is correctly set up is entering the shop, if it doesn’t display the number of users on the left bottom of the page, or the prices are not shown but there is no error message then the application is probably not properly running. It may also be the case that after adding an item to the cart you can’t see it when you go back to the cart page.

If you have placed the files in a folder other than the root of your web server then you can do two things. First you can define the folder as a web application (recommended), or second, you can move global.asa to the root - if you are not already using one. The second method will add some extra processing, as the events will be executed even when a user doesn’t access the shop. Contact your server administrator for details.

Sometimes some errors in global.asa may not be obvious, as they are not shown on screen. To make sure that there is no error executing any of the functions we recommend you doing the following test in case you are experiencing some difficulties:

- Copy global.asa and call the new file global.asp

- Add the following code at the end of the file:

<% Response.Write("Running Application_OnStart<BR>") Call Application_OnStart Response.Write("Running Session_OnStart<BR>") Call Session_OnStart Response.Write("Running Session_OnEnd<BR>") Call Session_OnEnd %>

- Remove any “On Error Resume Next” line.

- Rename or move somewhere else the existing global.asa to avoid any interference.

Now run the new file global.asp. You should get only lines of the type “Running …”. If there is no error message then global.asa is most probably configured correctly (if placed in the root of the application).

2.4 System Permissions

You need to set write permissions for the account used by the web server IIS (IUSR_machinename) in two folders:

- /temp:

Q-Shop will try to write here temporary files to create the mail attachment sent with the order confirmation emails. If “write” permissions are not enabled emails won’t include the order details attachment.


- /db:

The database file is stored in this folder. You need to set write permissions on this folder so that the web server can update the database. If the permissions are not correctly set you will notice, for example, that you cannot add items to the cart, update shop settings or update the catalogue in the admin site.

Tip: If you change the name of these folders remember to check their permissions.

2.5 Password-protect folders.

It is strongly recommended to password protect the folder where the database is. This will allow access to it only by you and will protect your site and the information contained. Remember that the credit card information is stored in the database and is your responsibility to keep it secure.

When you do this make sure that the user IUSR_machinename keeps read/write access to the folder and database file.

To change the username and password of the administration website edit the file /admin/security.asp and edit the following code:

'----------------------------------------------------------------------- 'This function implements the security control over the administration web. '----------------------------------------------------------------------- 'Define login name and password: 'Login Name admin = "demo" 'Password pwd = "demo" '-----------------------------------------------------------------------

Change the definition of user name (admin) and the password (pwd) with new values.

2.6 Mail system.

You need to edit the file /inc/mailorder.asp to update the absolute path to the temporary folder to write files to:

TempPath = "e:\temp\"

This folder needs to have “change” permissions set for the user IUSR_machinename. It is used to temporarily write the order attachments sent in the e-mail notifications.

To change the text displayed in the order confirmation emails just edit the file mailbody.txt. You can find the file in the root of the shop.


The emails will include the user password as default. However, you can disable this by editing /inc/mailorder.asp and change the value of the parameter to False:

CONST MAIL_SENDCONF_PWD = True ' True|False

The shop comes configured to use CDONTS as default. CDONTS is part of IIS and is free; most of the ISP will at least support this option.

You can change the mail system back to CDONTS from another option in the General section of Shop Settings in the administration site set the Mail Component value to “CDONTS”.

JMail

It is also possible to use JMail instead of CDONTS. This offers some additional possibilities although the scripts provided offer the same functionality. With some modification you could, for example, receive all payment details in the order confirmation encrypted with PGP.

In order to use JMail instead of CDONTS you have to do the following changes:

1) In the Mail System section of Shop Settings in the administration site set the Mail Component value to “JMAIL”:

2) In the same settings page set the “SMTP Mail Server” with the address of your SMTP server.

You can download and purchase JMail at the following address: http://www.dimac.net. For developer information you can access http://tech.dimac.net.

AspMail

It is possible to use AspMail instead of CDONTS. This offers some additional possibilities although the scripts provided use the same as CDONTS. With some modification you could, for example, receive all payment details in the order confirmation encrypted with PGP.

In order to use AspMail instead of CDONTS you have to do the following changes:

1) In the Mail System section of Shop Settings in the administration site set the Mail Component value to “ASPMAIL”:

2) In the same settings page set the “SMTP Mail Server” with the address of your SMTP server.

You can download and purchase AspMail at the following address: http://www.serverobjects.com. The scripts have been tested with version 4.0 but should be backwards compatible.

2.7 Security

Remember to password protect the database folder; this is possible in any NT or Windows 2000 server using NTFS file system.


It is highly recommended the use of SSL in the checkout process. The checkout process takes three steps and uses the files checkout.asp, prockcheckout.asp and prockcheckoutend.asp. It is also highly recommended to use SSL in the administration site if you are going to store credit card information (default option). See the next section for further details.

These files should be in a SSL enabled folder to avoid third parties to read payment information from your users. Remember that changing the location of the files will also require you to modify the links to them together with the links contained on those files as stated in “SSL Configuration”.

The easies option is enable SSL access on the shop folder including the admin. Set it as “not required” to allow dual access and simplify the configuration.

Always remember calling these pages starting with “https://”.

2.8 SSL Configuration

The easiest way of using SSL is mapping the SSL certificate to the folder than contains Q-Shop (including subfolders) and /admin in particular. When doing this it shouldn’t be set as “Required” so that the same folder can be accessed with or without SSL.

In this case you will only need to modify conx.asp editing the following lines:

Dim strNonSecPath Dim strSecPath strSecPath = "https://www.domain.net/qshop/" strNonSecPath = "http://www.domain.net/qshop/"

Define the URL of the site in strNonSecPath and the URL of the secure site in strNonSecPath. Remember to point at the folder not any file and end the URL with “/”.

The site will not work if you try to have your secure pages in a different server, as it wouldn’t find the database and the session and application settings wouldn’t be kept.

However it is possible to use a shared certificate from another domain that is in the same server and pointing at the same shop files.

For instance, the files would be in c:\inetpub\qshop, the URL for the site would be http://domain.com/qshop and the secure site would be accessed trough https://secure.com/qshop. Remember that both URL’s must point to the same files.

To do this the server administrator has to set a virtual folder in the secure domain pointing to the same physical path as the non-secure domain.

Follow the following steps to configure this system:

1. Add in checkout.asp this line on top of the page after:

<% @Language=VBScript %>

the line:



This will initialise some session and application variables needed in the checkout and make up for the fact that they are not part of the same web application/session.

2. Edit conx.asp and edit strNonSecPath and strNonSecPath as described above.

2.9 Debugging the application

ASP applications are not easy to debug compared with desktop applications done with Visual Basic for instance. However, to simplify the process Q-Shop includes a file that can be of great help: debug.asp. This file is located in the root directory and in \admin. You can also call the file inc/debugger_object_asp.asp or use the class included in pages that you want to debug or simply to check server settings.

This file will show all the Session and Application variables, the version of the VBScript engine of the web server and when used as an “include” file the Query String and Form variables.

To call it, just type in you browser, for instance: http://www.domain.com/debug.asp according to your web site configuration. It will show you all the information including session and application variables, query string and form fields and VBScript version.

If you want to debug certain page/pages then just include somewhere in the page/s a line:



This will also add all the Query String and Form variables used in the page.

Additionally you can use http://www.domain.com/admin/execsql.asp to execute SQL queries. Please, notice that you should never use this function if you are not completely confident with what you are doing, especially when updating and deleting lines. We recommend doing a backup before executing any of these queries. Notice that you must be logged in the administration interface before calling this page.

Tip: It is recommended to rename, if not remove, these files from the server as they could help hackers to obtain information. Copy them only when needed.

2.10 Test credit card number

The system performs several checks, including mod10, on the credit card information. To be able to complete an order without entering valid data you can use the credit card number “4111111111111111”. When the site has been tested we recommend you to modify the file procchkoutend.asp to remove the line:

'----------------------------------------------------


'Allow test credit card (4111 1111 1111 1111) '====> Disallow next line in production environment!! <==== If CCNumber = "4111111111111111" Then CCCheck = 0 '----------------------------------------------------

2.11 Browse layout

When listing products it is possible to select between two different methods to add products to the cart:

- Single addition

Each product has its own “Add to cart” button. Only one product can be added to the cart in one click.

- Multiple addition

All products in one page share the same “Add to cart” button. Many products can be added to the cart in one single click.

The system used when displaying a section can be set using the section administration web interface. However, for special offers, common list, searches and manufacturer listings this has to be set directly in the ASP script files.

- Browse.asp

Edit the following lines:

'========================================== 'Set Browse types: S (single), M (multiple) '========================================== sBrowseOffer = "M" 'Offers sBrowseManu = "M" 'Manufacturer sBrowseFeat = "M" 'Featured Products '==========================================

- Search.asp

Edit the following lines:

'========================================== 'Set Browse types: S (single), M (multiple) '========================================== sBrowseSearch = "S" 'Search results '==========================================


3 Site Personalisation

Once the sample site is working you can start modifying it to adapt it to your needs. The first step will be changing logos and HTML templates.

All the pages have two include files that define the layout of the page:

- head.inc

This page contains the header of all the pages. It also calls leftinc.asp that generates the left-hand side bar. You might also need to modify this file to change the appearance of the site.

- foot.inc

This pages closes the layout started with head.inc.

- inc/conx.asp

There are two variables set in this file that define the image tag for the logos used:

- LogoURL: Main logo shown in all the pages.

- SmLogoURL: Small logo shown on the left-hand side navigation bar.

You can also set the default image displayed when a product does not have an image associated to it:

- LineLogoURL : URL of the small logo displayed when a product has no picture (called from inc/line.asp). Double quote all quote characters.

If you want to use quotes remember that you will need to double them.

Example for:

<IMG SRC=”/images/logo.gif”>

You will need to write:

LogoURL = “<IMG SRC=””/images/logo.gif””>”

You can also define the variable to contain any HTML code, just remember to double quote any quote character of the HTML code.

The second step could be change the information contained in the information pages:

- shop.asp


This file is the fist page opened when entering the shop. It contains the welcome message. Notice that it is personalised so that it recognises users that have previously visited the shop and obtains their name if the purchased something.

- help.asp

This file contains some help about the functions of the shop. Add any additional help you may required.

- shipping.asp

This file contains shipping cost information. Notice that this is static information and you will need to edit manually.

- terms.asp

This is the terms and conditions page. Make sure you add your own terms.

Additionally a privacy policy could be added in the same way as the term and conditions.

- contact.asp

Add your own contact details here. By default only the email address will be picked up automatically.

Remember that many users won’t feel safe if the full contact details are not available.

- mailbody.txt

This file contains the body of the message that is sent to a user containing the order information when they purchase any product as an attachment.

- welcomemailbody.txt

This file contains the template for the body of the message that is sent to a new user that register using the “create account” page. The following fields are available for the body of the message:

E-mail body template fields

#UserID# Customer's User ID.

#Name# Customer’s name.

#SurName# Customer's surname.

#Pwd# Customer’s password.

#Mail# Customer's e-mail address.

#shop_CompanyName# Shop company name.

#shop_Mail# Shop e-mail address.

#shop_Title# Shop title.

To change the subject of the message edit the file newuser.asp and in Sub SendWelcomeMail change the line:

sMailSubject = "Thank you for registering for #shop_Title#"

The template fields available are:

E-mail subject template fields



If you want to create new pages you can use a copy of the file template.asp as a template. This file is also very useful to figure out how the layout is built in Q-Shop:

<% @Language=VBScript %>  <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> <HTML> <HEAD> <link rel="stylesheet" type="text/css" href="style.css"> <Title><%= shop_Title %></title> </HEAD> <BODY link="#0000FF" vlink="#0000FF"> <br> <div align="center"><%= LogoURL %></div> Place your code/text here  </BODY> </HTML> 

Any page that accesses the database should have the include file conx.asp and call the include file closeconx.asp at the end of the page. It is very important not to forget closing database connections as this may affect performance and limit the number of simultaneous users.


A number of colours can be changed directly using the Colour Settings section in the administration site. This will take effect immediately.

3.1 Shop Settings

To change the site configuration access the admin folder with a browser (e.g. http://www.yourdomain.com/admin). This folder should be password protected. Access the “Shop Settings” section.

The settings are grouped in several categories:

- General

- Mail System

- Colour Settings

- Order States

- Billing States

- Product Availability

The following tables summarise the two main settings available. The rest of the settings are explain in their respective sections of this manual. The name of the field stored in the database is into brackets.

Shop Settings – General

Company Name

(CompanyName)

Name of the company.

URL

(URL)

URL for the root of the shop.

For example: http://shop.biz/shop/

User Session Time Out

(TimeOut)

Inactivity time in minutes after which a user session expires and the shopping cart is deleted.

Contact e -mail

(Mail)

Mail address of the shop.

Shop Title

(Title)

Title to be used on all the pages.

Default Currency Default currency expression. This expression generates all the prices in the main currency and in which all the prices are defined


(DefCurName) prices in the main currency and in which all the prices are defined in the database. It MUST always contain the symbol “#” that will be substituted by the price. Examples:

“$# USD” would generate: “$123.40 USD”

“# €” would generate: “123.40 €”

Secondary Currency

(SecCurName)

Secondary currency name. You can indicate an HTML tag to use an image instead of text but do not use quote (“) sign.

For example:

<IMG SRC=euro.gif WITH=10 HEIGTH=10 ALT=Euro>

Currency Conversion factor

(SecCurConv)

Conversion factor to the secondary currency name in the format:

Price in secondary curr. = Price in default curr. / Conversion factor

Featured Product Ids

(Featured)

Comma separated list of featured products. A product from the list will be chosen randomly and shown in the home page (shop.asp). Do not use spaces.

For example:

PROD001,PROD003,1234

Control of stock

(StockControl)

Defines whether stock control should be applied or not:

1: Yes

0: No

Database System

(DBSystem)

This sets the database system to be used. Options available are:

ACC: MS Access Database (default)

SQL: MS SQL Server

Minimum Order

(Order_Min)

Minimum order value to process order.

Shop Settings – Mail System

Mail component (MailSystem)

This specifies the mail component to use. Options supported are:

CDONTS: Default option

JMAIL: Dimac’s JMail component


ASPMAIL: ServerObject’s AspMail component

SMTP Mail Server SMTP Mail server address. Not needed when using CDONTS.

You can also modify the values directly into the database using the table Config_Table and the names of the parameters shown into brackets. Notice that if you do this you must make sure that the web application is restarted so that the values are reloaded in memory.

3.2 Stock control features

Stock control is optional. It can be activated or de-activated at any time from the Shop Settings | General section.

When stock control is on:

- Stock is reduced accordingly every time an order is placed.

- Stock level is displayed together will the product.

- When a product is out of stock it will be displayed but it won’t be possible to add it to the cart.

- If while the user was browsing the shop, a product has gone out of stock, he/she will be advised about it. If the stock has gone under the quantity in the cart he/she will be advised of the remaining quantity.

E.g.

- Vivaldi CD: Not in stock

- White Chocolates 200g: We only have 2 of the 3 requested.

If you still wish to order the products you can decrease the quantity in your cart before proceeding to checkout.

Stock levels can be modified at any time editing the product details in the administration site from the products section.

You can also obtain a list of products with stock level equal or lower than a specific quantity. Simply access the Stock Control section in the administration site and specify a quantity.

3.3 Shipping Cost Calculation

You must modify the shipping cost calculation settings in the file inc/shipping.asp. There are several methods provided to calculate costs.

• Based on total cost:


This method calculates the cost based on the total cost before taxes using a table of cost ranges. The cost applied is different for national shipping and international. Variables involved: SystemMode, level1min, level1cost, level2min,..., intllevel1min, intllevel1cost, intllevel2min,...

• Based on total weight:

In an equivalent form to the total cost this method uses the total order weight to calculate the shipping cost.

Variables involved: SystemMode, level1min, level1cost, level2min,..., intllevel1min, intllevel1cost, intllevel2min,...

• Based on percent of order cost:

This method will add as shipping cost a percentage of the order cost. For example, for a 10% charge of an order of $100 the shipping cost would be $10.

Variables involved: SystemMode and PercentRate.

• Proportional to weight:

Using this method it is possible to calculate the total cost proportionally to the weight.

Example: 1$ per pound or 1.5 Euro per Kg.

Variables involved: SystemMode and PerWeight.

• Proportional to number of products:

Using this method it is possible to calculate the total cost proportionally to the total number of products.

Example: 1$ per product.

Variables involved: SystemMode and PerUnit.

• Flat Rate Shipping Charge:

Adds a fixed cost per order. This system can be used together with any of the other systems.

Variables involved: SystemMode and BaseCost

• Free Shipping for orders above a limit:

You can make free shipping for all the order above a limit. This system can be used together with any of the other systems. Example: Free shipping for orders above $50

Variables involved: SystemMode and FreeShipping


• List of options

You can also provide a drop down menu with a list of available options to be choosen by the customer.

• Real-time UPS cost calculation

You can provide UPS cost calculation in real time obtaining costs directly from UPS. You must obtain a license from UPS to use this feature from their web site.

Note:

For free shipping you can either set the FreeShipping value to 0 or set SystemMode to “NONE”.

a) Based on total cost or weight:

The cost calculation algorithm provided uses country information and a scale of values before taxes.

The system can calculate the cost based on the total weight of the products in the shopping cart or the total cost of the order before taxes. To change this you will need to edit the file /inc/shipping.asp and give to the variable SystemMode the correct value:

To calculate the cost based on the total cost before taxes (default) the variable has to be defined:

SystemMode = "TOTAL"

To calculate the cost based on the total cost weight the variable has to be defined:

SystemMode = "WEIGHT"

The default value is “TOTAL” and you won’t need to change SystemMode if you want to use this option.

To define the scale you will have to change several variable values.

For nation shipping the default variables are:

level1min = 0 level1cost = 10 level2min = 10 level2cost = 12 level3min = 20 level3cost = 13 level4min = 30 level4cost = 14 level5min = 40 level5cost = 15


This will produce the following scale of weight/cost:

From (including) To (not including) Cost

level1min level2min Level1cost

Level2min Level3min Level2cost



Level5min - Level5cost

For international shipment the variables are: intllevel1min, intllevel1cost, intllevel2min, intllevel2cost, intllevel3min, intllevel3cost, intllevel4min, intllevel4cost, intllevel5min and intllevel5cost.

You will also have to change the line:

If ShipCountry = "CA" Then 'Local

Substituting “CA” (Canada) with the origin country code as it is listed in the file inc/country.inc

Next you will have to set the values of the international shipping in the same was as domestic modifying the following values:

'Table for international shipping

intllevel1min = 0 intllevel1cost = 10 intllevel2min = 10 intllevel2cost = 12 intllevel3min = 20 intllevel3cost = 15 intllevel4min = 30 intllevel4cost = 17 intllevel5min = 40 intllevel5cost = 20

b) Based on percent of order cost:

To set up this system you will need to define the variables SystemMode and PercentRate.


Modify:

'SystemMode = "PERCENT"

PercentRate = 0.00

To:

SystemMode = "PERCENT"

PercentRate = 0.10 ‘Example for 10%

Be sure of disabling any other declaration of SystemMode. To do it just add “’” (single quote) at the beginning of the line.

c) Proportional to weight:

To set up this system you will need to define the variables SystemMode and PerWeight.

Change:

'SystemMode = "PERWEIGHT"

PerWeight = 0.00

With:

SystemMode = "PERWEIGHT"

PerWeight = 1.00 ‘ Example for one unit of primary currency ‘ per unit of weight as declared in the weight of ‘ each product.


d) Proportional to number of products:

To set up this system you will need to define the variables SystemMode and PerUnit.

Change:

'SystemMode = "PERUNIT" PerWeight = 0.00

With:

SystemMode = "PERUNIT" PerUnit = 1.00 'Cost per unit. 'Example: 5 items in cart 'Cost = 5 * PerUnit


e) Flat Rate Shipping Charge:


This system can be used in conjunction with any of the listed above (except UPS). To activate it and add flat rates per shipping just declare the value of BaseCost with the cost.

Change:

BaseCost = 0

With:

BaseCost = 13 ‘Example for 13 units of primary currency


If you want to use this system only without combining it with another declare add a line like:

SystemMode = “NONE”

And then be sure of disabling any other declaration of SystemMode. To do it just add “’” (single quote) at the beginning of the line.

f) Free Shipping for orders above a limit:

This system can be used in conjunction with any of the listed above (except UPS). To activate it and add a flat rate per shipping just declares the value of BaseCost with the cost.

Change:

FreeShipping= -1

With:

FreeShipping= 50 ‘Example for orders above units ‘of primary currency (Dollars, Euros,..)


If you want to use this system only without combining it with another declare add a line like:

SystemMode = “NONE”

And then be sure of disabling any other declaration of SystemMode. To do it just add “’” (single quote) at the beginning of the line.

g) List of options

Alternatively, if you want to add a fixed list of options then add the following code in the file checkout.asp where you want the list of options to appear:

<tr> <td></td> <td><b>Shipping Method :</b></td> <td> <select name="ShipCost"> <option value="200">US Ground</option> <option value="250">US Air</option> <option value="150">Canada Ground</option> <option value="200">Canada Air</option> <option value="300">Other</option> </select> </td> </tr>

Simply change the name of the options (like ”US Ground”) and its associated cost (like 200 for US Ground in the example).

Then in the file procchkout.asp where it says:

' ------------------------------------------------------------------------- ' Here calculate the shipping costs and assign the total to the ' variable ShipCost ' -------------------------------------------------------------------------





Change the last line with this one if you don’t want to use any other shipping function:

ShipCost = Cdbl(request.Form("ShipCost"))

Or add the line before the shipping.asp include file:

ShipCost = Cdbl(request.Form("ShipCost"))



In this case you will have to modify in shipping.asp the variable SystemMode to “NONE” so that it doesn’t re-calculate the cost using another system like per weight. If the option will be the final price simply remove the line “”.

h) Real-time UPS cost calculation

Please, refer to Annex “UPS Module” for information about this system.


3.4 Tax Calculation

Finally, modify the tax settings. Q-Shop supports tax calculation for US, Canada and the European Union. You can change the configuration using the Tax Wizard in the administration site under Shop Settings | Tax.

The current details will be displayed. You can change the settings ticking the correct radio button (US/Canada/European Union) and click on Next. Then provide the tax details requested depending on the tax model.

Important: Taxes are only applied to products and not to shipping costs. If you need to apply taxes to shipping cost as well then you will need to edit the inc/carts.asp file and follow the instructions in the following code:

'----------------------------------------------------------------------- ' TAXES ' If there are taxes to apply, calculate taxes and display them. ' IMPORTANT!: It applies taxes to the products cost, not to the ' shipping cost. ' To also apply tax to shipping cost then uncomment lines as ' explained below. '----------------------------------------------------------------------- 'For taxes outside EU: USA and Canada If TotalTax > 0 AND Tax_Model <> "EU" Then Taxes = AppliedTax 'Use the following calculation instead if you want to apply taxes to shipping cost 'Taxes = AppliedTax + ShipCost * TotalTax 'Apply tax to shipping cost as well HTMLCart = HTMLCart & "Taxes (" & TotalTax*100 & "%): " & _ FormatDefCurr (Taxes) & "<br>" 'For European Union taxes: Elseif Tax_Model = "EU" Then Taxes = VATTax 'Note: To add VAT to shipping cost follow this instructions: 'Use the following calculation instead if you want to apply taxes to the shipping cost. 'Replace 0.16 with the tax rate needed 16% = 16/100 = 0.16 'VAT will only be applied if not VAT number has been specified. 'Uncomment the following 3 lines to apply VAT to shipping cost. 'If Trim(Request.Form("VATNumber")) <> "" Then ' Taxes = VATTax + ShipCost * 0.16 'End If


HTMLCart = HTMLCart & "VAT: " & _ FormatDefCurr (Taxes) & "<br>" End If

a) European Union Taxes

All customers from a country in the European Union will be charged VAT. The VAT applied to each product can be defined in the product details (see section later).

In the tax details screen provide a list of available tax rates in comma-separated format without spaces (e.g. 17.5,5,0), then click “Next Step” to save details.

To enable tax exemption for companies with a VAT number an additional field in the checkout will be displayed asking for a VAT number. Please, notice that Q-Shop does not validate VAT numbers. If you do not want to allow this remove the VATNumber field from the form (only displayed when EU mode set). When the EU tax model is set a help button will appear. When a user clicks on it a pop-up window will be opened displaying some help and the explanation of VAT in several European languages. To change the text edit the file VAThelp.htm You can also display all prices with VAT included. To enable this simply go to the Tax section under Shop Settings in the admin website. In the second step of the tax wizard there is an option called “Show prices with VAT incl.”; set it to Yes. All prices will be shown with VAT other than in the checkout and in all order summaries where tax will be shown separately. If you set the system to display prices with VAT included the Minimum Order setting will be compared against the total cost order including VAT as this is the cost displayed to the user regardless of whether the customer is exempt of paying VAT.

b) Canadian Taxes

The taxes that will applied are:

- Zero Tax: to customers outside Canada

- Local Tax: to customers in the same province as the company

- National Tax: to all customers in Canada

In the “Tax Wizard” select the Canada model and click on “Next Step”. Provide the different tax rates and enter the state code where the c ompany is based and where to apply local tax - you can obtain a list of codes clicking on the help icon beside the state code.

You can set products to be tax exempt by editing the product details and checking the “Tax Exempt” option.

c) U.S.A. Taxes


In the “Tax Wizard” select the U.S.A. model and click on “Next Step”. Provide the different tax rates and enter the state code where the company is based and where to apply local tax - you can obtain a list of codes clicking on the help icon beside the state code.

Substituting “CA” with the right US State code where the company is based. In the example the state is California. To obtain a list of state codes click on the help icon shown beside the state field.

Then define taxes for customers in that state writing the right value in the variable LocalTax.

The taxes that will applied are:

- Zero Tax: to customers outside the company state

- State Tax: to customers in the same state as the company

You can set products to be tax exempt by editing the product details and checking the “Tax Exempt” option.

Note about taxes: QuadComm Inc. will not be liable in any way for the taxes applied in an online shop using Q-Shop. Make sure that the taxes are correctly applied and consult a tax expert.

3.5 Order States

You can modify the list of order states from the admin web site using the function “Order States”. When selecting this section you will get a list of order states with the following fields:

Order States

State State Id.

Description Name of the state displayed.

Delete Tick this box to delete the state.

Message A link Add or Edit will be shown depending on whether the state has an e-mail message associated.

To modify existing states just change its details. You can also add as many states as you want (maximum of 5 new states each time).


Q-Shop can automatically send e-mails to customers every time an order changes to a particular state. To do this you can assign an e-mail message to individual states. The message will then be merged with the customer and order details before being sent.

To do this you just need to use expressions like #field_name# that will be replaced prior to sending the message. The available list of fields for the message body is:


#UserID# Customer's User ID.

#Name# Customer’s name.

#SurName# Customer's surname.

#Id# Order Id.

#Date# Order’s date.

#Mail# Customer's e-mail address.


#shop_Mail# Shop e-mail address.


#Tracking# Shipment tracking reference (optional field).

#tim_date# Current date.

#tim_time# Current time.

#Status# Description of the status (Shipped, etc).

Example of template:

Dear #Name# #SurName#, We would like to inform you that your order has been shipped. Your order details: Order#: #Id# (please quote this in any mails regarding this order) Date: #Date# You can review your order and details at any moment in "My Account" section at our web site. You can use your user ID #UserID# or your email address #Mail# to log in. Thank you for shopping with us.


#shop_Title# #shop_CompanyName# #shop_Mail# -------------------------------- E-mail sent with Q-Shop on the #tim_date# #tim_time#

You can modify the code in changestatus.asp to add new fields like this. The recordset Rs will contain the details in the Orders table for the current order. Just add code similar to this:

strMailBody = Replace(strMailBody,"#Mail#",rs("Mail"))

In the same way as with the body of the message a default subject template can be set. This is not done through the admin interface and has to be changed directly in the code. To change it simply edit the file /admin/changestatus.asp. In the function SendEmailNotification you will find the following:

If Request.Form("msgbody") = "" Then 'IMPORTANT: Manually edit this field to set the subject template text strMailSubject = "Order #Id# Update: #Status#" 'Default Subject Else strMailSubject = Request.Form("msgsubject") End If

Change "Order #Id# Update: #Status#" with the subject desired.

The available list of fields for the message subject is:

E-mail subject template fields

#Id# Order ID.

#Status# Description of the status (Shipped, etc).

Please, notice that if after some time you change the name of some states it will also change the states of all the orders that were previously in that state. A work around


would be adding a new state and stopping using the old one. This method will allow you to display old orders with the old order state name.

3.6 Billing States

You can modify the list of order billing states from the admin web site using the function “Billing States” under Shop Settings. When selecting this section you will get a list of order states with the following fields:

Order States

ID State Id.

Description Name of the state displayed.


To modify existing states just change its details. You can also add as many states as you want (maximum of 5 new states each time).

All orders will be created with state id 0. Because of this you should ALWAYS have a state with id 0. To change the default state simply edit the MoveCart function in inc/catfunc.asp.

3.7 Product Availability

You can modify the list of available product availability options from the admin web site using the function “Product Availability” under Shop Settings. When selecting this section you will get a list of options with the following fields:

Order States

ID Availability Id (numeric).

Description Name of the availability displayed.


To modify existing options just change their details. You can also add as many options as you want (maximum of 5 new options each time).

By default products will have availability id set to 0. This option comes with an empty description by default and it is advisable to leave it as such. When an option has an empty description no availability information will be displayed with the product details.


3.8 Others

Products lists

If you want to change the way the products are listed you will have to change the file inc/line.asp.

Line.asp is an include file that shows a product line when browsing the catalogue. It is called from browse.asp, habit.asp and search.asp.

To change the number of products displayed per row when listing products refer to section “Modifying the way products are listed”.

Credit Cards (Issue Number and CVV number)

If you want to accept cards that use an Issue Number like Switch you can enable this option. Edit /procchkout.asp where it says:

'========================================= 'CC extra fields configuaration '========================================= Dim bShow_CCIssueNumber 'Display issue number field? (True|False) bShow_CCIssueNumber = False Dim bShow_CVV 'Display CVV number field? (True|False) bShow_CVV = False '=========================================

Simply set CCIssueNumber to True; this will display the field in the credit card details form and will automatically save it in the database.

If you need to use the CVV number (in the back of some cards) edit /procchkout.asp and where it says:

'========================================= 'CC extra fields configuration '========================================= Dim bShow_CCIssueNumber 'Display issue number field? (True|False) bShow_CCIssueNumber = False Dim bShow_CVV 'Display CVV number field? (True|False) bShow_CVV = False '=========================================


Set bShow_CVV to True.

Recommend to a friend

In order to personalise the default message when a customer recommends a product you need to edit the file /recommend.asp. You can change the message text but it is very important to change the URL contained. Do not modify the part after “?” as this is necessary to point the user to the right page. For example if you shop is at http://www.domain.com then you need:

Hello!

I have seen the product "<%= Request("ProdName") %>" in <%= shop_Title %> and thought of you.

You can get more details visiting the following link:

http://www.domain.com/details.asp?ProdId=<%= Request("ProdId") %>&cat=<%= Request.QueryString("cat") %>&path=<%= Request.QueryString("path") %>

Database schema

You can programmatically obtain detailed information of the database tables and fields calling two ASP pages located in the admin folder. You will need to log in before you can call them (for security reasons):

- admin/db_schema.asp (MS Access)

- admin/db_schema_sql.asp (MS Access and MS SQL Server)

Direct SQL queries

You can perform SQL queries over the database (SELECT, UPDATE, DELETE, etc...). To do so you must log in the administrator interface first and then call the asp page: admin/execsql.asp.

WARNING: Be especially careful when executing queries that could change the data in the database; these operations cannot be undone. You could permanently lose data if your delete or update queries are incorrect. It is recommended to perform only SELECT statements.


4 Shop Maintenance

4.1 Administration web site

The administration web site contains several options divided in:

- Orders

- Reports

- Users

- Products

- Stock Control

- Sections

- Manufacturers

- Upload Images

- Shop Settings

- Open/Close Shop

- Send Mailing

- DB Tools

- Logout

a) Orders

There are three different options in this section:

- Full List

Selecting this option you will have a list of all the orders in the system ordered from newest to oldest.

If you click on one order it will appear the details of the order and the option of deleting it.

Clicking on a column header will sort the list on that field.

- By Order Status

Selecting this option you can filter orders by their order or billing status.

Clicking on a column header will sort the list on that field.


- Extract Orders

Select this option to extract a list of orders. You can specify a time period and the format for the extracted data: text (comma separated) or MS Excel.

If you choose MS Excel you need to have the software installed to be able to view the orders.

Clicking on an order id will take you to the order details.

In the order details you can click on the user ID that will lead you to a list of all the orders of certain user, this option will also allow you to access al the features available in the Users section.

If the order was paid using credit card, the number will be displayed. You can delete the number from the database clicking on the link “Click here to delete CC number for this order”. This has been added to provide an extra level of security.

You will also receive an e-mail with the order details every time a user places an order although this will not include all details for security reasons.

b) Reports

This section will allow you to extract brief reports of order activity for a specified period of time:

1. Total Orders

2. Total before shipping and taxes

3. Total Taxes

4. Total Shipping Cost

5. Total Charged

6. Average Total per order

c) Users

Clicking this option you will be able to:

Display/Edit/Delete User Data

This option allows you to see and edit the personal details of users.

Display orders from a user

This option will show a list of orders from certain user.

Display product shopping history briefing of user

This option will show a summary of all the products purchased by certain user.


List all users

Select this option to obtain a list of all the users in the system.

d) Products

In this section you will be able to manage the products database. The options available are:

Show/Edit product information

Write a product ID and select this option to view the information stored, change it or delete it.

Add products

Select this option to add a new product to the catalogue database.

This is explained in more detail later.

e) Stock Control

This section allows you to list products with a stock level lower than a specified quantity.

f) Sections

In this section you will be able to manage the sections database. The options available are:

Show/Edit/Delete section data

Write a section ID and select this option to view the information stored, c hange it or delete it.

Add sections

Select this option to add a new section to the catalogue database.

This is explained in more detail later.

g) Manufacturers

In addition to organising products by sections you can also allow browsing by manufacturer/brand. For example, you could divide your products based on style and add the possibility of browsing by brand as well.

You can list, add and edit manufacturers in this section.

h) Upload Images

Here you can upload files directly from your web browser. Simply select the file that you wish to upload and the folder where you want to save it (product, section or general pictures).


This function may not work in some servers and browsers.

i) Shop Settings

All shop settings are organised in the following sections. This section is explained in more detail in the Site Personalisation section above:

- General

General shop settings are configured here.

- Mail System

You can change the tax settings here.

- Tax

You can change the tax settings here.

- Colour settings

You can change colours used in the shop easily using this interface. You can select the colour code or use the Colour Picker tool by clicking on the icon beside the colour fields.

- Order States

This section allows you to define order states and messages to be sent to customers when one of their orders changes to a particular state.

- Billing States

This section allows you to define billing states.

- Product Availability

This section allows you to define product availability options that can be associated to products.

j) Open/Close shop

If you need to do some site maintenance or want to temporarily close the shop you can do it in this section. This will redirect all new users to a web page explaining that the site is temporarily closed (shopclosed.asp). Existing users will be able to continue shopping unless they access the home page (shop.asp).

k) Send Mailing

This section allows you to send mailings to your existing users that have agreed to receive mailing from you.

You can define your message using some codes that will be replaced with the user details when sending the mails. The options available are:


E-mail template fields

#name# Customer name

#surname# Customer surname

#mail# Customer email address

The URL in the message that will allow users to unsubscribe from your list used the URL value set in the shop general settings. You can edit this in the template if necessary.

This system is limited in functionality and capabilities. For large user databases you may need to use a professional software package or create your own mailing lists with a provider.

If your mailings start timing out you can edit the file mailingsend.asp and change the values of the timeout parameter to a higher number in seconds:

'Apply a new script time out value

Server.ScriptTimeout = 300 'Seconds

l) DB Tools

There are some database tools available:

- Compact Database

This option is only necessary and available with Access databases. Access is not very good keeping itself; when you delete records they remain in the database although they’re not accessible. With time your database will grow and performance will decrease.

To avoid this Access provides a tool to compact database files. This is accessible from Access in the Tools -> Database utilities -> Compact and repair database. Additionally if you have a DSN pointing at your database this option will also be available from the DSN settings.

Q-Shop allows you do this from the admin interface. It is advisable that you close the shop before running this tool. It is also highly advisable to make a backup of the file in case something goes wrong. Q-Shop will also create a file backup with name in the form backup_DDMMYY.mdb but we recommend you to create your own backup even if you don’t run this tool. If you run it twice in the same day the previous backup will be overwritten.

Run this utility using this or another interface periodically. You will get the size before and after compacting the database, check these values to establish how often you need to run it.

Delete old backups from your server periodically.


- Delete old carts

This option will delete all old carts in the database. In normal circumstances there shouldn't be any left.

- Delete old user’s lists items

This option will delete old entries in user's lists for users that don't exist in the database anymore. Default is 12 weeks. It is good practice to run this periodically specially when using an access database as it will reduce the size of the database and improve performance.

m) Logout

Click on this link to close your session. All sessions will be closed after a period of inactivity time. This time is the same as customer sessions and can be set in the Shop Settings section.

4.2 Managing sections

There are sections (which doesn’t contain products) and subsections (containing products). Sections can also be called categories.

The fields for sub/sections are:

Sub/Sections Database Fields

Name Name of the section.

Title Title of the section (used as title when browsing products by section/category).

Code Section ID (numeric).

Contains subsections Yes if it contains subsections (cannot contain products). No if it doesn’t (can contain products).

Pertains to Indicates the section’s parent section (none if is not a subsection).

Description Description of the section. You can use HTML code. Carriage returns will be automatically converted into <BR>. Maximum of 255 characters by default.

Browse layout Multiple or Single Addition (see below).

Image Image for the section. The image must be in the cats folder.

Show Section If you uncheck this box neither the section nor its products will be shown (browsing, my list, offers, featured products, etc.)


When a user selects a section that contains products these can be listed in two different ways:

- Multiple Addition: A list with all the products and a quantity field for each. The user will then write the quantities for all the products that wants to purchase and click a button at the bottom to add all the products to the cart at the same time. This is especially suitable for categories when users want to add many products quickly like in a supermarket on-line.

- Single Addition: A list with all the products and a quantity field for each one pre-filled with value 1. The user can add a single product to the cart clicking on the button provided for each product. This is especially suitable for categories where users are more likely to add a single product to the cart.

The following are the fields stored in the database:

Sub/Sections Database Fields

Id Internal Id field (autonumber).

CatID (number) ID for the section.

Childs (number) 1 if contains subsections and 0 otherwise.

ParentID (number) ID of the sections to which pertains (should be 0 if is a section and not a subsection).

Description (Text) Name of the section used in the navigation of the catalogue.

Titulo (text) Title to be shown when browsing the catalogue.

TxtDescription (text) Text describing the subsection shown when selecting a section. It can contain HTML code.

PicPath (text) Name of the section picture located in /cats.

Browsetype (Char) This can be either “Single Addition” (S) or “Multiple Addition” (L) and specifies the type of product browsing layout displayed. Find more information underneath.

Show 1 to display the section in the shop (default) and 0 otherwise.


4.3 Managing products

You can add, edit and delete products in this section. There are several ways of accessing and listing products based on id, name and section.

The following are the fields shown in the web interface:

Sub/Sections Database fields

Name Name of the product.

Description Description of the product. You can use HTML code. Carriage returns will be automatically converted into <BR>. Maximum of 255 characters by default.

Code Product Code/Id. This is an alphanumeric field.

Section Section to which the product pertains.

Manufacturer Manufacturer/brand. This is not required.

Thumbnail File name of the product thumbnail picture.

Image File name of the product image shown in the product details page.

Back Image This can be used to display a picture of the other side of the product. This is an optional field. If it exist a link “Turn Image” will be displayed underneath the product image in the details page.

Price Price of the product.

Tax Exempt Select “yes” if no taxes should be applied to this product. Not used in EU tax model.

Relative Price Relative price that can be displayed in the details page. (text field) E.g. $1.23/Lb.

Offer Offer/sale price.

VAT rate VAT rate to apply (only in EU tax model).

Option 1 Name Name of first product option (e.g. Colour).

Option 1 Values Comma separated list of possible values. Do not use spaces. E.g. Red,Blue,Green

Option 2 Name Name of second product option (e.g. Size).

Option 2 Values Comma separated list of possible values. Do not use spaces. E.g. S,M,L,XL.


S,M,L,XL.

Weight Product weight (numeric).

Quantity in stock Current stock level used if Stock Control is active.

Complementary Product Id

Product Id of a complementary product. If entered the complementary product will be displayed together with the current product in the product details page. E.g. a top could be a complementary product for a pair of trousers.

Show Product If unchecked the product will not be displayed in the shop.

Image Display Type Select the type of product pictures. See section below.

Availability Select product availability. By default there will be a blank product availability with id 0.

The following are the fields stored in the database:

Products Database fields

Id (autonumber) Internal Id field.

ProdID (text) ID for the product (alphanumeric).

CatID (number) Id for the section (category) to which it pertains.

Name (text) Name of the product.

PicPath (text) Name of the product picture in the folder /prodpics. Used when showing details of the product.

PicPath2 (text) Name of the product back picture in the folder /prodpics. Used when showing details of the product and the user clicks “Turn Picture”.

Thumbnail (text) Name of the product thumbnail picture in the folder /prodpics. Used when browsing the catalogue.

Price (numeric) Price of the product. Do not specify non-numeric characters.

Description (text) Description text shown when showing details of the product. It is possible to use HTML tags. The default is 255 characters maximum. If you want to change this then change the field type from Text to Memo using MS Access.

PriceRel (text) Optional relative price of the product. For example: $1/Kg.


OptionsD1 (text) Name of the first optional option for the product. For example: “Color”.

OptionsV1 (text) Comma separated list of possible values for the first option. For example: “Red,Green,Blue”.

OptionsD2 (text) Name of the second optional option for the product. For example: “Size”.

OptionsV2 (text) Comma separated list of possible values for the second option. For example: “Small,Medium,Large,Extra Large”.

Offer (numeric) Optional offer price for the product. If indicated the product will appear showing the special price in the lists and details pages. It will also make it appear in the “Special Offers” list.

Weight (number) The weight of the product (used to calc ulate the shipping cost if this option is set). See Shipping Cost section for more information.

If you are going to use the UPS module you will have to use Lbs. (pounds) as the measure unit or modify the script to convert it to lbs. Before obtaining the cost.

Units Indicates type of units (units, Kg, g, etc). Currently not used. Set to 1 always (units).

Show 1 to display the product in the shop (default) and 0 otherwise.

Stock (numeric) Stock level of product.

ManuId (numeric) Manufacturer Id (optional).

Complimentary Product Id of the complimentary product (optional).

VATRate VAT rate applied to this product (used only in EU tax model).

Taxable Indicates whether the product is taxable (1) or tax exempt (0). Used only in non-EU tax models.

ImgDisplayType (numeric)

Type of product image display. 0=Front+Back image, 10=List of images, 20=Scrollable list of images

AvailabilityId (numeric)

If of the product availability.

4.3.1 Price Options

You can also set up Price Options and Related Products for each product:

You can set up to 2 different product options that will not affect the price of the product (Option 1 and 2 mentioned above). Additionally you can set up an unlimited


number of options that will affect the price. However, you can only add up to 5 options at the same time.

The fields available are:

Price Options Fields

Name Name of the option (text displayed)

Type It can be absolute or relative: - Absolute: the price defined will override the product price

(e.g. $15). - Relative: the price defined will be added/discounted to/from

the product price (e.g. +$15).

Cost Cost/Price of the option.

The cost used in the shopping cart will use the price options when available. We recommend having at least an option with the same price as the product price for clarity.

4.3.2 Related Products (Cross-selling)

This is an advanced marketing feature available in Q-Shop. The purpose is to suggest other products to the user that he/she may be interested on.

This is used in two places:

a) When displaying the product details (details page): If there are related products associated they will be suggested to the user.

b) Products associated to any of the products in the user’s shopping cart will be suggested when displaying the cart.

This way you could, for example, associate a particular blend of coffee when displaying a coffee machine. Another example would be suggesting a bottle of champagne when displaying 12 roses.

To enable this feature simply type the Id’s of the products related to a particular product. To delete one association simply tick the “delete” check box and click on “Update Data” in the product details.

The database has been designed to allow different types in the future like up-selling (suggesting an alternative superior product). However, this hasn’t been implemented yet.

4.3.3 Product Pictures

Q-Shop allows you to display product pictures in three different layouts:

- Front image and optional back image


This option allows you to set a default picture and have an optional secondary picture that can be viewed by clicking on a “Turn Image” link that will appear only when the back image is defined. This would allow you to have an image of the back of the product and allow the customer to select the side displayed.

- Several images displayed in column and a zoom image

This option allows you to define a list of images that will be displayed in column all at the same time. You don’t need to have more that one image. Additionally you can define a zoomed image that will open in a separate pop up window.

For this option you need to enter the names of all the column images comma -separated without spaces. For example: "img1.jpg,img2.jpg".

- Scrollable list of images and zoom image

This option allows you to have a scrollable list of images; the user will be able to scroll through the list without having to reload the page. You don’t need to have more that one image. Links to the different images will be displayed below the picture displayed.

For this option you need to enter the names of all the scrollable images comma -separated without spaces. For example: "img1.jpg,img2.jpg".

Additionally you can define a zoomed image that will open in a pop up window.


Examples:

Column + Zoom

Scrollable + Zoom

Turn Image

4.3.4 Modifying the way products are listed

The standard layout used to display products is one product per row with a definable maximum of products per page. However, in some occasions it may be desired to show n products per row.

This annex explains how to use the two examples provided:

- n products per line with extended information.

- n products per line with summarised information.

There is only one small configuration difference between the two options: the name of the include file.

You can easily modify and create your own files using the templates provided as a base or simply as an example for your development.

Steps to change the configuration:

1. Chose and edit the replacement for the inc/line.asp include file.

Edit the file inc/line_mult.asp for extended information or inc/line_mult_sum.asp for summarised information.

The first option will display the same information as the default format but with n products per row/line while the second will just display product name, price and units in stock (if enabled).

Edit the following code setting the number of products per row (3 in the example):

'Define number of products per line nColsPerLine = 3 'Products (columns) per line

2. Modify browse.asp (or other files).

Edit browse.asp to use the new template file. Edit the following code (from browse.asp):

'=============================================== ' Display products. '=============================================== 'Display a maximum of MaxItems i = 1 While not rs.eof AND NumRows < rs.pagesize %>  <% i = i+1 rs.movenext NumRows = NumRows + 1 Wend '===============================================

Change it to (if using line_mult.asp):

'=============================================== ' Display products. '=============================================== 'Display a maximum of MaxItems i = 1

'While not rs.eof AND NumRows < rs.pagesize %>  <% ' i = i+1 'rs.movenext 'NumRows = NumRows + 1 'Wend '===============================================

In the templates provided the loop is included in the include file and therefore the code in browse.asp must be removed or commented out as in the example above.


Annex A. Upgrade scripts

From version 2.5 when there is a major database upgrade that requires converting data from one form to another an ASP script is provided to convert the data.

These scripts will be in \manual\update. Make sure to read the description.txt file which summarises the scripts available. Together with each script name there will be a version number. For example, if the version number is 2.5 it means that it is necessary to run the script to upgrade from the previous version to 2.5.

Please, notice that the scripts only update data; they do not create any database structure changes. Database changes need to be done manually prior running the scripts.

Each script file will have an explanation of the changes and what the script does.

When there is a database structure that doesn’t affect the existing data no script is provided. See the history file for details (/manual/history.txt).

Annex B. UPS Module

This module is available only to companies based on the U.S.A. or when the parcels are going to be sent from the U.S.A.

In order to use this module you must register at the UPS site: http://www.ec.ups.com.

To use the UPS module you will have to install a component and made several easy changes to the store files.

1. AspTear Component

In order to contact the UPS.com web site it is needed to use a component that can establish the connection and return the price quote. We recommend the use of AspTear v1.0 as it has all the functionality required and is free. You can download it from:

http://www.alphasierrapapa.com/IisDev/Components/

You will find the installation instruc tions at the Alphasierrapapa.com web site.

If you plan to use another component you will need to make some changes to the cost calculation module.

2. Modify checkout.asp

Edit the page checkout.asp and change the line:



for:

<!—#include file="ups/upsform.htm"-->

This will include the parts of the form related to UPS.

3. Modify procchkout.asp

Change:



for:



<!—#include file="ups/calcups.asp"-->

This will use the UPS calculation system included in inc/calcups.asp.


4. Edit ups/calcups.asp

Modify the parameter OriginZIP changing the line:

OriginZIP = 19116

To the origin ZIP code from where the packets will be sent.

Now remember to define the weight of all the products, as this is required to calculate the cost of UPS shipment.

5. Edit /forders.asp

In order to enable the UPS Tracking features you need to modify /forders.asp. Open the file and close to the top, where it says:

bUPSActive = False 'Set to True to use UPS system

Change it for:

bUPSActive = True 'Set to True to use UPS system

This will display the summary and the link to the details after the order details.

The page that displays the tracking details is /trackingdetails.asp

Important notes:

Please remember to register the UPS online tools at http://www.ec.ups.com/ .

QuadComm, Inc. is not nor will be responsible for the accuracy of prices provided by UPS or the UPS module.

QuadComm, Inc. does not guarantee updates to this code in case of changes on the UPS interface.

Annex C. Authorize Net 3.0 Module

Version 3.0 is now also supported. The system used is the ADC method and there is no AVS validation.

To have the system running you will have to go trough 3 steps described underneath.

1. Installation of HTTP component

In order to contact the Authorize.Net web site it is needed to use a component that can establish the connection and return the transaction results trough SSL.

We recommend the use of AspTear v1.0 as it has all the functionality required and is free. You can download it from:

http://www.alphasierrapapa.com/IisDev/Components/

If you plan to use another component you will need to make some small changes to the author30.asp file. Make sure that your component does support SSL connection as this is required by Authorize.Net for obvious reasons.

The script provided should be compatible with AspTear v1.2 as well although it hasn’t been tested.

2. Edit procchkoutend.asp

Edit the file procchkoutend.asp and modify the following.

Where it says:



Change to:



Delete the following line which is shortly after:

OrderConfirmed = true

3. Edit transactions\AuthorizeNet\author30.asp

This file contains the scripts that contact Authorize Net to validate transactions. There are some parameters that need to be configured for your account.

The code is basically divided in two parts:

- Function Authorize

- Main body of the code


The main area where to define whether to use test transactions or not is:

'----------------------------------------------------------- Dim IsTest IsTest = True '<<<<<<<<<<< Important! You need to change this to produce real transactions 'Set to False to perform real transactions 'Set to True to perform test transactions (no charges will be made) '-----------------------------------------------------------

The released file uses the testdriver account for test purposes, the transaction is not actually processed in this case. Once you have tested it you can change to your account configuring the parameters:

Login = "testdriver"

You can still do tests with your real account by editing the function Authorize and removing the initial quote in the line:

'posteddata = posteddata & "&x_Test_Request=TRUE""

When the script is configured as a test transaction the payment details are not picked up from the form and default test values are used instead.

To use your own account information you need to change the following code using your own login and password obtained from Authorize.Net:

If NOT IsTest Then 'For real transactions use this data Login = "testdriver" '<<<< Configure this with your Authorize.Net Login Password = "" '<<<< Configure this with your Authorize.Net Password

You will find plenty of comments in the code to help you configuring it. Some parameters are mentioned as optional, you can remove them or provide correct values for them. Some of these changes may require changes in the Merchant Account Manager at Authorize.Net

Name/Surname changes in version 3.0

Authorize.Net version 3.0 has a different handling of the name. In version 2.5 the full name (first name and surname) where passed together. In version 3.0 there are 2 fields: First Name and Surname.

You will find these lines in author30.asp:

'Credit Card Owner surname

SurName = Request.Form("CCOwner")

'Credit Card Owner first name

Name = Request.Form("CCOwnerName")

By default the first name field is not used. All the data is picked up in the surname field (the user just sees a text field called “Credit Card Owner Name”). In this case you will have to make sure that the first name is not required in the Merchant Account Manager at Authorize.Net.

If you want to use two fields for the name then you need to change the file procchkout.asp in the following way:

 <tr> <td></td> <td><b>Card Owner :</b></td> <td><input type="Text" name="CCOwner" size=30></td> </tr> has to become: <tr> <td></td> <td><b>Card Owner First Name:</b></td> <td><input type="Text" name="CCOwnerName" size=20></td> </tr> <tr> <td></td> <td><b>Card Owner Last Name:</b></td> <td><input type="Text" name="CCOwner" size=30></td> </tr>

Basically you remove the HTML comment tags () so that the new field and description is shown. You may modify procchkoutend.asp to make the field CCOwnerName required.

Annex D. Datacash module (beta version)

QuadComm provides a module to process credit cards using Datacash. This module is in beta version although it has been reported to be working with no problem.

Additional technical information can be obtained at http://www.datacash.com through the “software” link. You will be able to obtain the server side software, full specifications of the interface, different test data, etc.

The scripts are set up to use a test account on a test transaction. This means that the credit card details will not be obtained from the checkout form but directly from within the script.

Using different credit card numbers it is possible to obtain different return codes, check Datacash technical documentation for more details. These special credit card numbers are called “Magic Numbers”.

The steps to configure the script are very simple:

1. Install the Datacash Microsoft Windows NT software

Download and install the Microsoft component software in the server where the shop is running.

2. Edit procchkoutend.asp

Edit this file to include the inc/datacash.asp include file. Edit the following code:

If Request.Form ("payment") <> "COD" Then '--------------------------------------------------- ' Include here credit card processing "include file" ' according to manual. '--------------------------------------------------- %>  <%

and change it to:

If Request.Form ("payment") <> "COD" Then '--------------------------------------------------- ' Include here credit card processing "include file" ' according to manual. '--------------------------------------------------- %>  <%


3. Configure inc/datacash.asp

Configure the LogFile variable. This will define where to write the internal transaction log. This folder should never be available through the web server as it contains confidential information. You can access this file in case of doubts about any transaction and to check that it is running correctly during development.

You can try using different credit card numbers to obtain different return codes. You can get a list of the different numbers available (magic numbers) together with a full list of return codes at the Datacash web site (software section).

To use de credit card details entered through the checkout form change the line IsTest = True to IsTest = False.

Once it has been thoroughly tested you are ready to use a real account. Simply change all the settings provided by Datacash modifying the following code:

'Set the following settings with your own <<<<<<<<<<<<<<<<<<< Hostname = "new_auth.datacash.com" Port = "9070" EncryptionKey = "0123456789ABCDEF" RequestType = "auth" Client = "21859999" Password = "fred" LogFile = "c:\temp\datacash.log" TimeOut = 120 TranCurr = "USD"

TranCurr is the currency code to use in all transactions. You can get a list of codes at the Datacash web site together with additional information about the different variables and settings.


Annex E. Q-Shop external payment gateway framework

In the cases where the user must be re-directed to an external site to make a payment (eg WorldPay, Paypal…) Q-Shop uses a common flow. Developers wishing to add new gateways are advised to follow this framework.

The following diagram shows the steps that the framework uses:

Payment Provider custom callback

custom linkbuilder

ext_orderconfirmation.asp

procchkoutend.asp

The user goes through the standard checkout steps, however, in the last page (procchkoutend.asp) the message displayed is different and tells the user to click on a link/button to proceed to pay. To enable this two settings have been added to procchkout.asp:

- bEnablePaypal: This adds Paypal as an option in addition to the standard payment methods. (True|False)

- bExtGateway: This indicates the credit card payment is performed in an external site. (True|False)


In order to create the custom link a separate include file is used. This should be in a subfolder of the folder /transactions together with the rest of the gateway specific files. The link will normally include details like total cost, merchant id, customer details, etc.

The user is then directed to the external site where the payment is done. This will be a number of steps depending on the provider.

Once the user has made the payment s/he is directed to the shop again via the page ext_orderconfirmation.asp. This page simply tells the customer that the order has been completed. It is possible to do some extra work in this page depending on the parameters passed back. However, it is recommended not to validate the order here as users could fake the URL once they know its format. Possible actions could be sending an email or simply displaying some additional information to the customer.

Some payment providers will provide an added “server call-back” feature. When payment is completed they can call a page in your site to confirm payment. This call is completely hidden from the user. This is the best method to update the order’s billing status. Each provider will use a different system and pass different information so a custom file is required for each one.

In some cases the provider can pass back additional information like a password that you can verify in the call-back.

It is specially important to use billing status wisely to differentiate the orders that have been confirmed and those whose payment is still unconfirmed. You can add/modify your own billing statuses in the admin section. To change the default billing status when an order has been created (before the user is directed to the external payment pages), simply edit in the file inc/catfunc.asp the following constants:

CONST N_BILLINGSTATUS_NEWORDER = 0 'Billing status for new orders CONST N_STATUS_NEWORDER = 0 'Order status for new orders


Annex F. WorldPay Payment Module (beta version)

This module is still in beta version. We will appreciate any feedback from the results of using this module. Either if it works or not, please, do contact us ([email protected]).

Q-Shop supports the WorldDirect payment system from WorldPay. This implementation follows the framework defined in the section Q-Shop external payment gateway framework including WorldPay’s callback feature.

The files specific to this gateway are in /transactions/worldpay:

• worldpay_link.asp

This file generates the link to WorldPay’s server.

• worldpay_callback.asp

This file processes callback calls from WorldPay. It is never displayed to the user and a good security practice would be to rename it.

• wp_USR_confirm_msg.txt

This file contains the template for the confirmation message sent to customers when payment has been confirmed. It is called from worldpay_callback.asp.

The file /ext_orderconfirmation.asp is also used to direct the user after the payment has been finished.

For testing purposes you can use a dummy test card number “5418 5900 1234 5679 “with any expiry date up to seven years in the future.

To configure the WorldPay system follow the steps:

1) Edit worldpay_link.asp

In the configuration section there are several settings that you must configure:

- sinstId:

This is your installation id. You will get this when signing up with WorldPay. If you are a developer they can provide a test Installation Id for you.

- stestmode:

This parameter sets the test mode. 100 will always produce a successful transaction and 101 will always fail.

- scurrency:


Set the currency code desired here. Check WorldPay documentation for country codes.

- sdesc:

This will generate the order description. By default this will be a message like “Order number 2321”.

All these settings will be in the configuration section:

'---------------------------------------------------------------- 'Worldpay Configuration: 'IMPORTANT: Set your own installation number here. Do not confuse with the Worldpay Customer Reference. sinstId = 12345 'Installation number stestmode = 100 'Attention!: Remove this line or set it to 0 for live transactions '100 will always produce a successful transaction

'and 101 will always fail. scurrency = "USD" 'Set the currency code desired here. Check Worldpay documentation for country codes. sdesc = "Order number " & nOID 'End of Worldpay Configuration '----------------------------------------------------------------

2) Edit worldpay_callback.asp

WorldPay calls this file when a payment has been confirmed. You need to enable the callback feature from the WorldPay administration console. It is also advisable to set a callback password as well for added security.

This page will check the password (if one has been defined) and update the order billing status to a specific Id. An email confirmation is then sent to the customer. If an error occurs the system sends a mail to the shop owner with some additional information.

You only need to edit the following settings:

- sCallBackPwd:

This defines your callback password. Leave blank if you don’t want to check it.

- nSuccessBillStat:

Billing status id for successful transactions.

- nCancelledBillStat:


Billing status id for cancelled transactions.

The settings can be updated in the following piece of code:

'======================================================================= ' Customer Server Call-back Settings '======================================================================= Dim sCallBackPwd 'Password set in the CMS for customer server 'call-back. Recommended sCallBackPwd = "" 'SET YOU PASSWORD HERE. Default is empty. Dim nSuccessBillStat 'Billing status ID that should be set 'when successful. Set to a StatID from 'the admin billing status section. Dim nCancelledBillStat 'Billing status ID that should be set when 'unsuccessful. Set to a StatID from 'the admin billing status section. nSuccessBillStat = 1 'Set your own correct value here nCancelledBillStat = 4 'Set your own correct value here '=======================================================================

3) Edit the mail template wp_USR_confirm_msg.txt

This file contains the template for the confirmation message set to the customers. There are a number of template fields available:

E-mail template fields

#OrderID# Order ID

#transId# WorldPay Transaction ID

#name# Card holders name

#address# Card holders address

#tel# Card holders phone number

#email# Card holders email

#shop_CompanyName# Shop Company name (from shop settings)

#shop_Mail# Shop mail (from shop settings)

#shop_Title# Shop title (from shop settings)


4) Return page

Edit your settings in WorldPay’s control panel (CMS) to direct the user to the page ext_orderconfirmation.asp after completing the payment. This page will display a thank you message. The page also loads into memory the parameters passed back. You can use them if you want to display a different personalised message or want to do some extra processing.


Annex G. PayPal Payment Module (beta version)

This module is still in beta version. We will appreciate any feedback from the results of using this module. Either if it works or not, please, do contact us ([email protected]).

Q-Shop supports the PayPal payment system. This implementation follows the framework defined in the section Q-Shop external payment gateway framework but doesn’t include a callback feature.

The settings are fairly simple and include only one file to generate the link to PayPal (/transactions/PayPal/Paypal_link.asp). The settings that must be updated are:

- sPPBusiness:

Set your PayPal ID (email) here.

- sPPimage_url:

URL of your 150x150 logo. Leave blank if you want your business name to be displayed instead. Note that if the URL is not using https:// a warning message will be displayed when a user clicks on the PayPal link.

- SPPReturnURL:

This is the URL to which users will be directed after the payment. Remember to change it the the correct URL for ext_orderconfirmation.asp.


Annex H. PAYBOX Payment Module

Using the PAYBOX module shares some of the configuration with the other external payment gateways.

When a customer places an order there are a number of differences present from prochckoutend.asp (step 3):

- No cart details are displayed.

- A link to an external site is displayed from where the payment continues.

The payment link will direct the user to an external site where the payment will be processed securely.

There are different ways the system updates the billing status of an order according to what happens in the external site:

- When a payment is executed an HTTP connection is established from the PAYBOX server to /transactions/paybox/paybox_callback.asp. This checks a pre-defined password and updates the order accordingly. This URL must be agreed with PAYBOX (see section “Edit the server HTTP connection page.”).

- When the user cancels a payment or the payment is rejected the user is redirected to ext_orderconfirmation.asp, which updates the order accordingly and redirects the user to pb_annule.asp or pb_refuse.asp depending on the type of action (see “Edit transactions/paybox/paybox_link.asp”.

The payment specific files used by this module are:

\ (shop root):

\pb_annule.asp Page displayed when the user cancels a payment

\pb_refuse.asp Page displayed when a transaction is rejected.

\ext_orderconfirmation.asp Page called after any payment. It redirects users to pb_annule.asp, pb_refuse.asp or displays the payment confirmation.

\transactions\paybox\:

paybox_link.asp Creates the link to PAYBOX

paybox_callback.asp Page used to the direct HTTP connection from PAYBOX.

updateorder.asp Library used to update the order status

ext_orderconfirmation_paybox.asp

PAYBOX specific processing code used in \ext_orderconfirmation.asp


pb_USR_confirm_msg.txt This file contains the template for the confirmation email sent to the user when a payment is processed successfully.

To configure the module follow these steps:

1) Install the PAYBOX module

Follow the installation instruction provided by PAYBOX. This will include the installation of the CGI module for Windows NT and setting up a cgi-bin folder with execute permissions.

The PAYBOX software and manual will be provided to you by PAYBOX.

2) Edit prochchkout.asp

Enable the external payment settings editing the following:

'========================================= 'External payment gateway configuration '========================================= Dim bExtGateway 'Indicates whether the credit card payment is processed in an external site 'If True the credit card options including details won't be shown. (True|False) 'Choose of the two options and comment the other one: 'bExtGateway = True 'Use external gateway bExtGateway = False 'No external gateway '=========================================

With:

'========================================= 'External payment gateway configuration '========================================= Dim bExtGateway 'Indicates whether the credit card payment is processed in an external site 'If True the credit card options including details won't be shown. (True|False) 'Choose of the two options and comment the other one: bExtGateway = True 'Use external gateway 'bExtGateway = False 'No external gateway '=========================================

This will enable support for an external gateway.

3) Edit procchkoutend.asp

Change the following lines:

<% ElseIf UCASE(sExtGateWay) = "TRUE" Then %> <P> </P> <blockquote> <font face="Arial">To confirm your order please click on the button below. You will be asked to provide your payment details. An email has been sent to you with the order information but the order won't be valid until your payment has been completed. <P>Your order number is: <b><%= nOID %></b></font><br><br> </blockquote> <div align="center">  </div> <% End If

Change the above include file line in bold with:



The HTML around it may be slightly different but will always be under the “ElseIf“ line.

This will enable the link to the PAYBOX server from procchkoutend.asp.

4) Edit transactions/paybox/paybox_link.asp

This file holds key configuration parameters like account information and some necessary URL references.

You need to change your account settings from the default test ones to the ones provided by PAYBOX:

'Settings to be updated: 'Account settings: sIBS_SITE = "1999888" 'Site number (EPT) given by the bank. Exactly 7 digits. Test: 1999888 sIBS_RANG = "99" 'Rank ('machine') number given by the bank. Exactly 2 digits. Test: 99

Correct the relative URL to the correct PAYBOX CGI module:

'Location of the PAYBOX CGI module. Update with correct one: sCGIPOST = "/qsbooster/cgi-bin/module_NT_2000.cgi_.exe"


Edit the currency and language settings: 'Language/currecy settings: sIBS_DEVISE = "978" 'Purchase Currency. "250" = Franc, "978" = Euro sIBS_LANGUE = "GBR" 'Language used by PAYBOX for posting: "FRA", "GBR", "DEU"

Finally edit the return URL’s to correct ones. The three URL’s are:

Parameter Description

IBS_EFFECTUE Return URL of PAYBOX to your website after payment EFFECTED.

IBS_ANNULE Return URL of PAYBOX to your website after payment ANNULLED.

IBS_REFUSE Return URL of PAYBOX to your website after payment REJECTED.

'Update with the right domains/URL's: sIBS_EFFECTUE = "http://domain.com/qshop/ext_orderconfirmation.asp?type=effectue&OID=" & sIBS_CMD & "&CartID=" & CartID & "&UserID=" & UserID sIBS_ANNULE = "http:// domain.com/qshop /ext_orderconfirmation.asp?type=annule&OID=" & sIBS_CMD & "&CartID=" & CartID & "&UserID=" & UserID sIBS_REFUSE = "http:// domain.com/qshop /ext_orderconfirmation.asp?type=refuse&OID=" & sIBS_CMD & "&CartID=" & CartID & "&UserID=" & UserID

Note:

It is recommended to use the test account until the system has been tested and is working properly. PAYBOX can provide a test account with an HTTP connection configured in order to test the whole system.

5) Edit ext_orderconfirmation.asp

In order to enable the processing of the PAYBOX gateway, edit the external gateway settings in sPayment_Gateway:

'Define gateway used: sPayment_Gateway = "GATEWAY" '(WORLDPAY|PAYBOX)

Change to “PAYBOX” like:

'Define gateway used: sPayment_Gateway = "PAYBOX" '(WORLDPAY|PAYBOX)

To enable the PAYBOX specific processing code you need to enable one include file. Edit the file and change the following code to add “#” where necessary:

Case "PAYBOX" %>  <%

To:

Case "PAYBOX" %>  <%

6) Edit \transactions\paybox\ext_orderconfirmation_paybox.asp

Edit the billing status Id’s for rejected and cancelled orders. You should set the same Id’s as in the billing status section of the shop administration web:

'Billing status ID that should be set when "annule"/cancelled. 'Set to a StatID from the admin billing status section. Dim nAnnuleBillStat Dim nRefuseBillStat 'Billing status ID that should be set when "refuse"/rejected. 'Set to a StatID from the admin billing status section. nAnnuleBillStat = 3 'Set your own correct value here <<<<<<<<<<<<<< nRefuseBillStat = 4 'Set your own correct value here <<<<<<<<<<<<<<

7) Edit the pages displayed to the user

The system will automatically redirect the user to the following pages depending on the result of the transaction. You can edit them to change the message displayed:

- pb_annule.asp: Transactions cancelled by the user.

- pb_refuse.asp: Transactions rejected (incorrect payment details, etc).


You must copy this files to the root folder as they will originally be in the folder transactions/paybox/Root files.

8) Edit the server HTTP connection page.

When you set an account with PAYBOX you can specify a direct HTTP connection URL. The PAYBOX server will access this page when an order has been processed successfully. This is to guarantee that orders are set to “Payment confirmed” (or any order state that you choose) using a secure method, and without the user being aware of it.

You must request PAYBOX to set this up for you and provide them the URL for the file transactions/paybox/paybox_callback.asp with the parameter pwd set to the password that you want to use.

For example, if the URL for your file was “http:// domain.fr/transactions/paybox/paybox_callback.asp” and you wanted to use the password “123” then the final URL would be:

http://domain.fr/transactions/paybox/paybox_callback.asp?pwd=1234

You then need to edit the ASP script to check the password value:

Dim sCallBackPwd 'Password set in the CMS for customer server call-back. Recommended

sCallBackPwd = "" 'SET YOU PASSWORD HERE. Default is empty.

Note:

If you leave the password blank in paybox_callback.asp it won’t be checked regardless of the URL used.

9) Edit the email confirmation message template

You can edit the template of the ema il sent to the customer. The template file pb_USR_confirm_msg.txt can use one of the variables below. They will be replaced with the correct value when sent to the customer:


#OrderRef# Order ID

#Amount# Order total

#TransNumber# PAYBOX transaction number


#AuthNumber# Bank authorisation number

#shop_Mail# Admin e-mail address

#shop_CompanyName# Company name set in the administration site

Example:

Thank you for your order. This message acknowledges payment of your order: - Order ID: #OrderRef# - Amount: #Amount# - Transaction Number: #TransNumber# - Authorisation Number: #AuthNumber# #shop_Mail# #shop_CompanyName#

Which after being produce could look like:

Thank you for your order. This message acknowledges payment of your order: - Order ID: 1001 - Amount: 100.00 DM - Transaction Number: 1234567 - Authorisation Number: 4567890 [email protected] Your Shop Name Ltd.


QuadComm Q-Shop License Agreement

Only one of the following licences applies to you. Refer to your order details for your licence type. Any licence will only be valid together with an order number.

A) Single License

1. Definitions

The following expressions have the meanings given here:

“QuadComm” means QuadComm, Inc. being either the owner of all intellectual property rights in the Software, or having the right to grant licenses for the use of the Software.

“Software” means the software applications, utilities and modules included.

2. Licence Grant, Conditions and Restrictions

a) QuadComm grants you use of the software on one (1) machine, on one (1) web site and one (1) catalogue only. A website will be a copy the software running as a unit and perceived as the same website by users. This use is known as one single licence.

b) Several copies of the software pointing at the same database are considered separate sites.

c) You can take copies of the Software for back-up purposes only.

d) NO PART OF THE CODE may be redistributed, copied, published or resold under any circumstances.

e) You may transfer all of your licence rights in the Software provided that the transferee has read and agreed to accept the terms and conditions of this licence.

f) By itself, Q-Shop DOES NOT process credit card information - it delivers sales information to you. The system can be integrated with an optional automated credit card processing service.

g) Any third party that at any time may have access to the source code of the software must agree with the terms of this license and the copyright rights of QuadComm.

h) The software includes:

i. Includes quick-start documentation in MS Word format.

ii. Ready to run: all scripts and working demo.

3. Termination


This licence is effective until terminated. You may terminate the licence by destroying the Software (and all copies thereof).

QuadComm may terminate this License immediately without notice at any time if you are in breach of these terms and conditions of use. You agree that upon such breach or termination you will immediately destroy the Software (and all copies thereof) including all of the Software's documentation, source code, modules or anything provided with the Software by QuadComm. No refunds will be done in case of license termination.

Violation of this license by means of unauthorised distribution of code will lead to immediate termination of the license agreement and may result in prosecution to the fullest extent of the law of all parties involved. Use this software at your own risk.

4. Disclaimer

The software is supplied “as is” and QuadComm expressly excludes all warranties, express or implied, including (but not limited to) warranties of satisfactory quality, merchantability, fitness for purpose and non-infringement.

We have confirmed the reliability of this script to the best of our abilities through extensive testing. By using this software you agree that, in no circumstances, will QuadComm be responsible for any direct, indirect, consequential, or incidental damage (including charge-backs, errors, loss of revenue, loss of data, web server failure and downtime) or any disputes that may arise from the use of this software in modified or unmodified form. You must follow your ISP's policy if they require screening and/or approval of scripts prior to installation.

QuadComm is not responsible for the accuracy of prices provided by UPS. UPS license agreement may apply.

5. General

The above terms and conditions supersede any prior agreement, oral or written, between you and QuadComm relating to the Software.


B) Single VAR Licence

1. Definitions

The following expressions have the meanings given here:

“QuadComm” means QuadComm, Inc. being either the owner of all intellectual property rights in the Software, or having the right to grant licenses for the use of the Software.

“Software” means the software applications, utilities and modules included.

2. Licence Grant, Conditions and Restrictions

a) You MUST be a registered QuadComm VAR to use/purchase this licence and you MUST have purchased at least one single licence before this.

b) QuadComm grants you use of the software on one (1) machine, on one (1) web site and one (1) catalogue only. A website will be a copy the software running as a unit and perceived as the same website by users. This use is known as one single licence.

c) Several copies of the software pointing at the same database are considered separate sites.

d) You can take copies of the Software for back-up purposes only.

e) NO PART OF THE CODE may be redistributed, copied, published or resold under any circumstances.

f) You may transfer all of your licence rights in the Software provided that the transferee has read and agreed to accept the terms and conditions of this licence.

g) By itself, Q-Shop DOES NOT process credit card information - it delivers sales information to you. The system can be integrated with an optional automated credit card processing service.

h) Any third party that at any time may have access to the source code of the software must agree with the terms of this license and the copyright rights of QuadComm.

i) The software includes:

i. Includes quick-start documentation in MS Word format.

ii. Ready to run: all scripts and working demo.

3. Termination

This licence is effective until terminated. You may terminate the licence by destroying the Software (and all copies thereof).


QuadComm may terminate this License immediately without notice at any time if you are in breach of these terms and conditions of use. You agree that upon such breach or termination you will immediately destroy the Software (and all copies thereof) including all of the Software's documentation, source code, modules or anything provided with the Software by QuadComm. No refunds will be done in case of license termination.

Violation of this license by means of unauthorised distribution of code will lead to immediate termination of the license agreement and may result in prosecution to the fullest extent of the law of all parties involved. Use this software at your own risk.

4. Disclaimer

The software is supplied “as is” and QuadComm expressly excludes all warranties, express or implied, including (but not limited to) warranties of satisfactory quality, merchantability, fitness for purpose and non-infringement.

We have confirmed the reliability of this script to the best of our abilities through extensive testing. By using this software you agree that, in no circumstances, will QuadComm be responsible for any direct, indirect, consequential, or incidental damage (including charge-backs, errors, loss of revenue, loss of data, web server failure and downtime) or any disputes that may arise from the use of this software in modified or unmodified form. You must follow your ISP's policy if they require screening and/or approval of scripts prior to installation.

QuadComm is not responsible for the accuracy of prices provided by UPS. UPS license agreement may apply.

5. General

The above terms and conditions supersede any prior agreement, oral or written, between you and QuadComm relating to the Software.

Q-Shop Storefront System - Garrett's Muscle Car Museum Manual.pdf · Q-Shop Storefront System...

Documents

Transcript of Q-Shop Storefront System - Garrett's Muscle Car Museum Manual.pdf · Q-Shop Storefront System...