Documentation

Like just about every other Open Source project, the documentation is lagging behind development. All the documentation will be gathered together on this page as it becomes available.
Current topics are:

Installation

Follow these simple steps to get AKtivate up and running on your system:

Untar the source files within aktivate102.tar.gz. This creates an aktivate102 install subdirectory containing various subdirectories which in turn contain all the files you need for the installation. For example:

bash%>tar xvzf aktivate102.tar.gz

Create a MySQL database on your system. The default database name is test but you can choose any name and configure AKtivate to use it. You may need to contact your sysadmin to create the actual database, or it may alreday have been done for you. Make a note of the user name,password, hostname and port number because you'll need these to configure AKtivate later. N.B.Usually only the user name and password are required.

Now you have to edit the configuration file to reflect the values, paths and locations on your system. The file is in the source subdirectory, its called config.pl and is well commented for each value. The table below shows the most important items to configure:

Item	Default	How To Change it ....
$Orgname	Aktivate Install Demo	Overtype with your company or organisation name, e.g. Fred's Widgets.
$OrgPre	nes	Overtype with an abbreviation of your company or organisation name, e.g. for International Business Machines enter IBM. AKtivate uses this as part of its table names so that they can be unique across installations.
$Orgemail	sales@allen-keul.com	Enter a contact email address for your company or organisation, e.g. help@yourcompany.com
$FormPath	https://hostname/cgi-bin/aktivate	Enter the path to the AKtivate programs on your system. E.g https://www.yourcompany.com/cgi-bin Don't forget the protocol part, https://
$ImgPath	/home/public_html/pictures or a relative path such as ../../icons/pictures	Enter the Unix path to the directory holding your images or pictures. The supplied .gif files should be here as well as your product pictures.
$host	www.allen-keul.com or an IP address such as 192.168.100.51	This is the database host name. It can be a fully qualified domain name or an IP address. It tells Aktivate on which machine the MySQL database is running.
$hostacct	www.allen-keul.com or www.xyz.org/~myaccount	Holds the World Wide Web host name and location of HTML documents on your webserver. Overtype the default with your own domain name, e.g. www.yourcompany.com. AKtivate will use this to find some informational HTML files.
$Dbuser	adrian	The MySQL user name for the database you created in step 2 above.
$DBpass	mypassword	Use of a password depends on how your sysadmin set up the Mysql privilege system. If you need a password to connect to your database enter it here.
$DBname	test	The name of the MySQL database you created in step 2 above.
$mrchmailThreshold	30	The number of orders received before AKtivate emails the merchant. By default AKtivate will send out a reminder email when 30 orders have been placed.
$mailprog	/usr/sbin/sendmail	The location of the Mail Transport Agent/mailing program on your system.
$searchResultLimit	4	The number of search results AKtivate displays on a page before building a "Next" hyperlink.
$cartKeepDays	1	As shoppers enter your store they are automatically given a shopping cart. If they purchase something Aktivate removes the cart at the end of the transaction. If they don't buy anything the carts are not removed. You can use the Merchant Control Centre "Remove Carts" function to delete them. It will remove all carts older than the number of days you specify here.
$currSymbol	£/£	Overtype with the symbol of your choice, e.g DM for Deutschmarks.

Table 1. Config parameters for AKtivate.

Phew, well done! It gets a lot easier from here on in!

The next step is to create the database tables Aktivate needs and copy its files to the relavent destinations. There are two ways you can do this:

Using our graphical installer AktivInstall, or
Via the command line.

We'll consider AktivInstall first.

Using AktivInstall to continue the installation

To use AktivInstall you will need TCL (Tool Control Language) installed on your system. Change into the util subdirectory and start AktivInstall like this

bash/util%>./install.tcl &

This will start the installer, which looks like this:

As you can see its a simple 4-step process. Click on the "Build Tables" button to automatically define all the database tables Aktivate needs and populate them with test data. Once you've done this the installer changes:

The number is removed from the button and the "Ready" message is replaced with the "Tables Built" message. Next we need to copy all the program files into the correct cgi-bin directory. Enter the path to your cgi-bin in the first box and click on the "Copy Program Files" button. Once you've done this the installer changes:

Repeat the process for image files:

Finally, hit "Quit" and your ready to start testing the installation!

Using the CLI to continue the installation

Change into the util subdirectory and start the Command Line Interface installer like this

bash/util%>./install.sh

This will start the installer, which sets up the database tables for you. Both methods use the values you defined in config.pl to do this.

Next copy all the files from the aktivate102/source subdirectory into your cgi-bin directory, or to keep things neat a subdirectory named aktivate underneath your cgi-bin directory. Make sure you set all the programs to be executable and all the html template files to be readable. Note that the .html files in the source directory are used as templates by the AKtivate programs so they need to go in the same directory, not your usual html directory such as public_html.

Now copy the image files (*.gif) from the aktivate102/images subdirectory into your images directory.

N.B.

Amend the example credit.html page, which is used to capture payment details, to your own needs and place it with your normal html files, e.g. in the public_html directory.

Add a link from your website to the shop.cgi program. It should look something like this: <A HREF ="/cgi-bin/aktivate/shop.cgi">Shop</A>

Point your browser to the Merchant Control Centre program mcc.cgi. The path should look something like this www.yourcompany.com/cgi-bin/aktivate/mcc.cgi. You can login with a username of a and a password of b. Once logged in you MUST change the username and password with the Security button on the MCC panel. You should now be able to use the "reports" button on the MCC panel to view the supplied test customers and transactions.

The next stage is to test the shop application. Follow the link you set up previously and check that the shop starts with the aktivkart in a frame below it. Run a search against an item in the catalogue, verify the results are displayed correctly and add an item to your cart. Verify you can remove it, add another item and then click the "Check Out" button within the aktivkart. Complete the form and press submit, this should present you with a summary of your order. Finally check that you received an email correctly and then log into the Merchant Control Centre to verify that the Customer & Transaction reports show your purchase.

Now that you have the basic shop functionality running its time to return to the MCC and setup your products. Use the StoreMaster to add products to your catalogue. CatMan the Catalogue Manager will enable you to set up a hierarchy of products so that visitors can drill down to what they want.

Database Tables

The Catalogue Table

+-----------------+---------------------------------+------+-----+----------------+-------+
| Field           | Type                            | Null | Key | Default        | Extra |
+-----------------+---------------------------------+------+-----+----------------+-------+
| catlg_prod_code | char(5)                         |      | PRI |                |       |
| catlg_desc      | char(235)                       |      | MUL |                |       |
| catlg_price     | decimal(14,2) unsigned zerofill |      |     | 00000000000.00 |       |
| catlg_weight    | int(5) unsigned                 |      |     | 0              |       |
| catlg_image     | char(35)                        |      |     |                |       |
| catlg_disc      | int(3) unsigned                 |      |     | 0              |       |
| catlg_catg      | char(10)                        |      |     |                |       |
| catlg_var1      | char(10)                        |      |     |                |       |
| catlg_var2      | char(10)                        |      |     |                |       |
| catlg_oos       | char(1)                         |      |     |                |       |
+-----------------+---------------------------------+------+-----+----------------+-------+

The Catagory Table

+--------------------+------------------+------+-----+---------+----------------+
| Field              | Type             | Null | Key | Default | Extra          |
+--------------------+------------------+------+-----+---------+----------------+
| catgy_key          | int(5) unsigned  |      | PRI | 0       | auto_increment |
| catgy_desc         | char(50)         |      |     |         |                |
| catgy_higher_level | int(5) unsigned  |      | MUL | 0       |                |
| catgy_nbr          | int(11) unsigned |      |     | 0       |                |
+--------------------+------------------+------+-----+---------+----------------+

The Customer Table

+-------------------+------------------+------+-----+---------+----------------+
| Field             | Type             | Null | Key | Default | Extra          |
+-------------------+------------------+------+-----+---------+----------------+
| custkey           | int(10) unsigned |      | PRI | 0       | auto_increment |
| cust_cardnbr      | char(19)         |      |     |         |                |
| cust_expiry_dt    | char(5)          |      |     |         |                |
| cust_card_type    | char(3)          |      |     |         |                |
| name              | char(30)         |      |     |         |                |
| email             | char(30)         |      |     |         |                |
| phone             | char(30)         |      |     |         |                |
| title             | char(5)          | YES  |     |         |                |
| bill_company_name | char(30)         |      |     |         |                |
| bill_addr1        | char(40)         |      |     |         |                |
| bill_addr2        | char(40)         |      |     |         |                |
| bill_city         | char(20)         |      |     |         |                |
| bill_zip          | char(10)         |      |     |         |                |
| bill_cntry        | char(30)         |      |     |         |                |
| ship_company_name | char(30)         |      |     |         |                |
| ship_addr1        | char(40)         |      |     |         |                |
| ship_addr2        | char(40)         |      |     |         |                |
| ship_city         | char(20)         |      |     |         |                |
| ship_zip          | char(40)         |      |     |         |                |
| ship_cntry        | char(30)         |      |     |         |                |
| cust_dt_tm        | timestamp(14)    | YES  |     |         |                |
+-------------------+------------------+------+-----+---------+----------------+

The Order Table

+-----------------+---------------------------------+------+-----+----------------+----------------+
| Field           | Type                            | Null | Key | Default        | Extra          |
+-----------------+---------------------------------+------+-----+----------------+----------------+
| orderkey        | int(10) unsigned                |      | PRI | 0              | auto_increment |
| order_prod_code | char(5)                         |      |     |                |                |
| order_prod_qty  | int(5) unsigned                 |      |     | 0              |                |
| order_amount    | decimal(14,2) unsigned zerofill |      |     | 00000000000.00 |                |
| order_txn_id    | int(10) unsigned                |      |     | 0              |                |
+-----------------+---------------------------------+------+-----+----------------+----------------+

The Transaction Table

+-------------+---------------------------------+------+-----+----------------+----------------+
| Field       | Type                            | Null | Key | Default        | Extra          |
+-------------+---------------------------------+------+-----+----------------+----------------+
| txnkey      | int(10) unsigned                |      | PRI | 0              | auto_increment |
| amount      | decimal(14,2) unsigned zerofill |      |     | 00000000000.00 |                |
| txn_date    | date                            | YES  |     |                |                |
| txn_cust_id | int(10) unsigned                |      |     | 0              |                |
+-------------+---------------------------------+------+-----+----------------+----------------+

The User Table

+-------+----------+------+-----+---------+-------+
| Field | Type     | Null | Key | Default | Extra |
+-------+----------+------+-----+---------+-------+
| user  | char(16) |      | PRI |         |       |
| pwd   | char(16) |      |     |         |       |
+-------+----------+------+-----+---------+-------+

The Merchant Mailing Table

+-----------+------------------+------+-----+---------+----------------+
| Field     | Type             | Null | Key | Default | Extra          |
+-----------+------------------+------+-----+---------+----------------+
| threshold | int(10) unsigned |      | PRI | 0       | auto_increment |
+-----------+------------------+------+-----+---------+----------------+