Installation

1. create_form.cgi - script to auto-generate forms
2. submit_data.cgi - script to process forms
3. admin.cgi - back-end admin script
4. admin.setup - setup for admin
5. routines.pl - script library
6. routines2.pl - script library
7. links.pl - update links definition file
8. Sendmail.pm - smtp mail module
9. sample.td - sample table definition
10. sample.setup - sample table setup
11. sample.db - sample database (blank)
12. default_form.html - web page template for auto-generated forms
13. splash.html - web page template for successful form submission response
14. splashlink.html - sample return page from link response
15. required_field_error.html - web page template for form error response
16. cust_email.htm - template for customer submission acknowledgement e-mail (HTML format)
17. cust_email.tpl - template for customer submission acknowledgement e-mail (text format)
18. merc_email.tpl - template for submission notification e-mail to site owner (text format)
19. atm_help.html - frameset for online help documentation
20. atm_help_home.html - online help file
21. atm_help_menu.html - online help file
22. atm_help_menu_terms.html - online help file
23. atm_introduction.html - online help file
24. atm_installation.html - online help file (this file)
25. atm_help_terms.html - online help file
26. atm_users_manual.html - online help file
27. atm_about.html - online help file

1. FTP access to your webserver. You will most likely need to be able to change directory and file permissions (chmod on a Unix server).
2. An active Perl CGI-BIN. You will also need to know if your server can run CGIs with either a .cgi or .pl extensions.
3. The path to Perl on your hosting/server (usually /usr/bin/perl or /usr/local/bin/perl)
   
4. The path to sendmail (Unix) or the URL for your SMTP server (Win or Unix)

1. DIRECTORY SETUP
Several directories are needed to store the various @-Manager files. You will need to determine your directory structure prior to configuring and installing the files. The following provides a list of file groups and recommendations on the directory structures needed for them.

• Core Files (#1-#10) - These are the core executable scripts and their associated configuration files. They will need to go in your root CGI-BIN or other Perl CGI enabled directory. Your CGI-BIN should already exist, i.e. /cgi-bin, /cgi, /scripts.
• Table Data Files (#11) - Table data files (.db) holds the actual data in a tab delimited text file. To prevent theft of your data you should place this directory somewhere where a web browser can not access it or at least give it a name that no one would guess, i.e. /data_485323.
• HTML Page Templates (#12-#15) - These are the templates for auto-generated forms and their responses. It is recommended that you put these in a directory inside of your @-Manager cgi directory, i.e. /pages
• Email Templates (#16-#18) - The bulk e-mail engine allows you to specify one or more directories for it to search for e-mail messages. It is recommended that you put these in a directory inside of your @-Manager cgi directory, i.e. /emails
• Online Documentation - These files are used as online help and support files for the @-Manager. It is recommended that you create a directory under your standard HTML documents directory, i.e. /atm_help. Note some cgi-bins have disabled serving .html/.htm files, so your help files may not be viewable in those directories.

/web
|---/data (new)
|---/html (existing)
    |---/atm_help (new)
    |---/cgi-bin (existing)
         |---/emails (new)
         |---/pages (new)
|---/logs (existing)

or

/web
|---/cgi-bin (existing)
    |---/emails (new)
    |---/pages (new)
|---/data (new)
|---/html (existing)
    |---/atm_help (new)
|---/logs (existing)

Make sure when you create your files that the file permissions are set to read, write, execute (chmod 777) for the core scripts and their directory, and read, write (chmod 755) for all others.

2. FILE SETUP & INSTALLATION
2.1 Files 1-3 are the main .cgi executables. You will need to set the path to perl for your server on the first line of each file. By default it is #!/usr/bin/perl, #!/usr/local/bin/perl is another common setting.

2.2 Next we will edit the admin.setup and sample.setup. These files contain variables that are used to configure various aspects of the @-Manager. The admin.setup configures the merchant admin features. The sample.setup is a HTML form action setup file. Every form you use will have an associated form action setup file.

The setup files are self-documented with comments for each variable setting. Each setting is numbered. For the first part of our installation we will only need to set items 1-10 for admin.cgi and 2-10 for sample.setup. Do this in any text editor.

2.3 Load all files (1-27) to the server in the directories specified above in the 1. Directory Setup section. Make sure to set the file permissions to execute (chmod 777) for all .cgi files (1-3) and chmod 755 for all other files (some versions of Unix may require chmod 777 for all files and directories).

2.4 Test the create form script by typing the URL into a browser:

http://www.yourdomain.com/thecgidirectory/create_form.cgi?setup=sample

Where your domain is the domain where you have installed @-Manager, and the cgi directory is the path to the directory where you have installed the @-Manager core files.

If everything works correctly your browser will display the sample form. If not, see the troubleshooting guide below. Now fill in the form, making sure to enter an e-mail address where you can receive e-mails. Click submit. If you get a Thank You page, then it processed correctly. Wait a minute and check your e-mail. You should receive two @-Manager Success e-mails, one if you put in your address in the form and another if you put in your address in the sample.setup file.

When you receive the sample customer e-mail click the link at the bottom. If you get a Success page back then you have set up the customer side scripts successfully.

Now go to the admin.cgi by typing the URL you used for the create_form.cgi but replace "create_form.cgi?setup=sample" with admin.cgi

Customizing @-Manager
Now that the sample table is up and running we can build a new table/form that will be more useful for your needs. If you have not read the @-Manager Introduction (atm_introduction.html) it is highly recommended that you read it before customizing the system.

CREATING TABLES
At the heart of the @-Manager is a set of tables that define form fields and the data to be stored/e-mailed. To create a new table you will need to configure three files:

1. Table Definition (.td) - specifies the fields and their characteristics that a table/form will use.
2. Table Setup (.setup) - determines the actions forms take when submitted.
3. Table Data (.db) - The actual stored data.

Creating a new Table Definition requires a little bit of planning. The Table Definition is the focal point for specifying a table. Each table definition defines a list of fields as a series of line entries. Each entry has three tab delimited elements:

1. Label - The name of the field (no spaces)
2. Parameter - Defines fields as a key and/or required
3. Type - Defines the type of data a field will store and how to display the input on a form

The .setup files will customize auto-generated forms and the actions taken on submission. You can actually have more than one .setup file per table if you wanted different characteristics for the forms. In general you will only need one per table, so it is best to name them to match the table name, i.e. sample.setup for sample.db.

The main use of the .setup files is to configure the e-mails that are sent after a form submission is made. You can specify whether you want to send an e-mail to the merchant (and their e-mail address) and/or one back to the customer. You specify what templates you want to use for those e-mails and the subjects. To configure a .setup follow the comments for each variable included in the file. By default, @manager uses the smtp mailserver, the same as your e-mail client, which is better able to handle successive hits. If you have problems with it, and you are on a Unix-type system (Unix, FreeBSD, Linux, Solaris, Irix, etc), you can change the default service to the built-in sendmail routine (sendmail may have problems with large mailing lists).

IMPORTING AND CHANGING DATA FILES
When you first install a new table you will need to load an empty file (.db) to the data directory to store your data. @-Manager uses tab delimited files that will work on any server with no need for additional Perl modules or database engines.

In some installations, you may want to initialize a table with data imported from another source. To do this all you have to do is to create a tab delimited file where the columns match the fields in the table description. Spreadsheets, and most database applications, are capable of exporting files in this format. When you have your file just upload it to the data directory with the correct name and the @-Manager will automatically start working with it.

When you build your imported file there are a few rules you should follow for some of the data types.

• Date - all dates in the @-Manager are in the format YYYY/MM/DD. If you do not keep this format the date functions will not work properly in the admin
• Boolean - these fields are single characters; '1' for Yes/True and '0' for No/False.

If you want to change the table definition for a data file that has already been use there are several options. Once a data table has been used you cannot simply make a change in the table definition because field count would be off in the data file. To make a change, you can use the 'Add Field' feature in the admin. This will update the table definition and add columns to the existing data file. You can also manually add a field to the table definition and use a spreadsheet program to add another tab delimited column to the data file.

CUSTOM FORMS
While auto-generated forms are a nice time-saving feature, they are limited. To get around these limitations, the @-Manager provides for a simple method for you to hard-code custom forms. You may want to use hard-coded forms when you want to do JavaScript data validation, create custom field layouts, use hidden fields, etc.

For a custom form:

• All input tag names must match the associated table definition field names.
• The form action must equal [CGI-Directory]/submit_data.cgi, i.e.,
  <form action="http://www.atmanager.com/cgi-bin/submit_data.cgi" method="POST">
  Note you can use the "Get" method also.
• A hidden field must be included with the name=setup and value=[name of setup file without .setup ext].
  <input type="hidden" name="setup" value="sample">
  

The only tricky part is using date fields. One feature of the @-Manager is that dates are stored in a most to least significant format (YYYY/MM/DD) so that boundary searches are useful for searching date ranges. When a date is input in a form it is divided into 3 elements; year, month, and day. Each element should be named [name of field]_[date element], i.e Birthdate_year, Birthdate_month, Birthdate_day.

TEMPLATE FILES & DATA MERGE
All e-mails and customer-side HTML files are created using templates. One of the primary advantages of templates is that they maintain the custom look and feel of your site. The @-Manager also features a powerful data merge engine that makes your templates even more dynamic.

Data merge allows you to display dynamic data in your e-mails and web pages along with static text and graphics. The way this works is that you embed special tags that the @-Manager reads and replaces with text from a form submission, table data, and other sources. A data merge tag follows the format

%%datasource.specifier%%

The three major datasources of data are forms, tables, and date. Form and data are easy, just use the name of the form or table field for the specifier. For example:

%%form.Email%% or %%data.FirstName%%

For dates you have the following available specifiers:

time	3:48 pm
time24	15:48
hour	15
minute	48
second	22
date	8/13/2001
year	2001
month	8
monthbyname	August
day	13
dayofweek	Monday

You can use the same data merge tags in e-mails and web page files and in the direct input text box in the admin bulk e-mail engine.

Each form that you use should have three HTML web pages and up to two e-mail templates. The paths and names of these files are set in the .setup file you specify when calling a form. The .setup file provides comments to work with these template files.

UPDATE LINKS
Update links are a method for embedding a hyperlink in an e-mail or web page that when clicked will change the value of a field in a table. The most popular use of an update link is for unsubscribe links. For more on the use of update links see the 'Admin Features' section of the Introduction.

You can embed an update link in an e-mail/page using the link data merge tag (%%link.specifier%%). You can define as many specifiers as you want in the links.pl. You can set

• The field to update in a specific table
• The value to update the field to
• Link text to display if it is an HTML page. Note that update links automatically detect if the page is plain text or HTML and create the appropriately formatted code.
• The page to display after the link is processed

CUSTOMIZING ADMIN
The merchant admin requires little customization. There are a few features that can be changed in the admin.setup file that control display of data and other related items. To learn more about how to use the admin see the Users Manual (atm_users_manual.html).