|
The Steps For Operation: Operating instructions for Dagra SORD.CGIeCommerce Home The Steps For Operation:
The system will then email the completed order to the specified company to be filled and shipped. The system will also email a confirmation copy with credit card info blocked with * to the client if the aEmail or bEmail field was filled in with a valid email address, see email verification for more. Note: The system requires that aName field be filled in correctly so that the program can use his name later (you can substitute aCardHolderName for aName if you wish). There may also be other required fields, those that are named with a leading a, c or g. In case of an error or emission the program tells the user what is wrong and gives him an opportunity to fix it. Adapting Your HTML Form for Connecting with sord.cgiThe form begins with the "<form" tag that is followed by 3 special hidden tags and some optional hidden tag that give the program needed information. The 3 must be present for the system to operate, the optional ones are explained under options. When a Mode tag is present it should always be the first hidden tag below the form beginning, the default mode is 1. <form name="sord" action="sord.cgi" method="post"> Note: These special tags do not use a prefix letter and are therefore discarded after use by the program.
In addition to these special fields there are two more that accept client input but get special handling. aName will be used to call the client by name in the thank you screen at the end of the transaction. aEmail, bEmail or eEmail will be verified as a valid email address and used to send the confirmation to the client. Optional Internal Variables iNameAll iName fields are used for passing variables to the program that are used internally and not passed on in the final data. These fields are shown in this documentation file with their default values, therefore omitting then will yield the same result as is shown. The intent is to allow you to change the value of these variables easily and to be compatible with forms that were written for previous versions of sord.cgi. Field Prefix Letter Determines ActionWe have chosen to use a single lower case letter as a prefix that the CGI program can trap and act upon. This plan is compliant with Java and JavaScript language specifications therefore providing us the greatest flexibility for our forms. Each field in your form must begin with a prefix letter for the CGI program
to process it. Program action is determined by this prefix as follows: Note: You can hide field names from sord.cgi by using a capital letter as the first letter in the name. These fields will simply be ignored by the program. Since a, c & g fields are always required you should let the client know that by marking these with an asterisk and a note to explain. You are free to change the form any way you like with a few considerations for the CGI program and security.
Following these simple rules you are free to incorporate graphics and animation within your form as you wish. Form Field Naming ConventionsIn the section above you read about the prefix that tells the system how to handle each field, here we will consider the people who use the system. As you decide on names for the fields in your form there are some of things to remember.
It is a good idea to keep the prompts short and to make the names resemble the prompts. You can use capitalization to make the names readable like bStreetAddress or bPOBox. Keep in mind that the field that identifies the person filling in the form must be named aName. Large variations in field name length make the verify and final email hard to read, bStAddress would be better than bStreetAddress for example. Linking To This Secure FormThe HTML form, the sord.cgi program and support files are all placed together
in a folder (secure) within your account. This folder is made execute only
for security. Links to this form can be made from anywhere in the following
form:
With these guidelines you can present an attractive yet secure form to your clients. Email VerificationEmail addresses are central to the operation of our system and present a special challenge to the CGI program. If the program attempts to send an email with an invalid or incorrect email address the user will see an error message that says something like "A server error has occurred, if this continues contact the system administrator." We do some additional verification to avoid this error as follows.
The validation is:
Luhn Algorithm for Credit Card ValidationThis test insures that the number is a well formed card number. If the test fails then the card number could not possibly be correct. However if the number passes the test there is no assurance that the card number is good, only that it could be. There is no way of knowing whether a card number actually belongs to the person that is presenting it. Usually a typing error will result in an improperly formed card number and be caught by the Luhn test. The Order is Time StampedThe order that is conveyed to the company has a timestamp that is generated by sord.cgi when the order is submitted. This is also the exact time that the confirmation is sent to the buyer. The timestamp is mm/dd/yyyy:hh:mm as 04/29/2001:11:33 - April 29, 2001 at 11:33 AM. 1:00 PM is represented as 13:00. The form of the timestamp can easily be used by a program later in the production cycle. This can also be saved into a database field if you wish, see the database instructions. Program OptionsIf the server permits it we can apply the clients email address to the email
that is returned to us containing the order. Should we need to correspond
with the client about an order it is really convenient to be able to hit the
reply button, add comments and send it off. This tag provides support for that. Different Modes of OperationThe default action of sord.cgi is to accept data from an HTML form (mode 1) then return a generated form for the client to verify (mode 2). To increase the flexibility of the program we have added an inquiry mode (mode 3) that does not send a confirmation and does not need a secure connection. Mode 5 is exactly like mode 1 except the verification step is skipped. These are each described in their own section below. Only modes 1, 3 and 5 are definable. Can Now Operate In Window 7/2002If you wish sord.cgi to be called from a form that is operating in a window
you will want to change the home link to instructions for closing the window.
Change the line for Home_html to the following: Thank You Message is Definable 10/2000To increase the flexibility of SORD.CGI we have added two variables that allow
the thank you message that is displayed after the final form submission to become
more user definable.
The default value is: Thank you for your order just as it was before the
change. To set this variable to a new value add these two lines to the hidden fields
at the top of the form. Form Type is Definable 10/2000Since SORD.CGI can be used for forms other than order forms we have added a variable
that allows you to change the word order that is used in the confirmation and email
from the default Order to Application, Inquiry, Request or any other single word that
describes your application. To set this variable to a new value add this line to the
hidden fields
at the top of the form. Show Reference Number is Definable 10/2000When using sord.cgi to support forms that are not order forms you may not want to assign
a reference number. If you set the hidden internal field as shown Inquiry Only Mode (3) 4/2000You can also use sord.cgi for a form that is simply an inquiry. That is the results of the form will be sent to you without showing the client the usual data verification screen and without sending a confirmation to the client. The hidden fields at the top of the form are joined by one additional field as shown in bold below to inform sord.cgi that it is to run in mode 3. When a Mode tag is present it should always be the first hidden tag below the form beginning. The default value for the thank you message is: Thank you for your inquiry. The default value for the form type is: Inquiry. Note the relative call to the home page that will only be used if the form is called as a non-secure page as shown below. <form name="sord" action="sord.cgi" method="post"> Inquiry mode is intended to simply send an inquiry and can be used with a non-secure call. When calling the form you would use this style ./secure/inquire.html. This mode should not be used with credit card or other sensitive information. The inquiry form is still placed in the secure directory with sord.cgi to avoid path confusion. It does not tell the client that he is leaving the secure environment in the final screen. Secure Without Client Verification, Mode (5) 4/2000If a form is particularly complex the client verification step may become so confusing that it would be better to eliminate it, mode 5 allows that. When the form is submitted it will do the data validation that is normally done in the first step then do the submission and conformation as is normally done in the second phase. The hidden fields at the top of the form are joined by one additional field as shown in bold below to inform sord.cgi that it is to run in mode 5. When a Mode tag is present it should always be the first hidden tag below the form beginning. The default value for the thank you message is: Thank you for your order. The default value for the form type is: Order. <form name="sord" action="sord.cgi" method="post"> Mode 5 works exactly like the default (mode 1) except that it bypasses the client verification. It does tell the client that he is leaving the secure environment in the final screen. Store Customer Names in Server Side DatabaseOptionally you can establish a flat file database on the server to accumulate a customer list from the clients that use a form. This feature requires a pair of files, one .txt and one .lck, with world write privileges. There will be a set for each form that is to store records. The files can be in the same directory as sord.cgi or in a directory that can be accessed with a relative link from it. For example if the database files are to be placed in ./secure/data and named cust1 then you would have ./secure/data/cust1.txt and ./secure/data/cust1.lck. The .lck file is simply a lock file that sord.cgi uses to prevent a data collision should more than one person be submitting the same form on your Website at the same time. The lock file contains one line, STATUS=OPEN and is used exclusively by sord.cgi. Once permissions are set to 666 you should never need to touch a lock file again. Note: Should the database function fail it will fail silently. Almost always failures occur because of a missing file, incorrect name or wrong permission setting. The program will continue to collect orders. Example of a Form Top Section With Database Tags<form name="sord" action="sord.cgi" method="post"> Explanation of Database Form FieldsThis example illustrates the setup for a form connected to cust1.txt. It is a typical name and address list as you can see by the field names. The field name that identifies the database file is always named iDatabaseName and is also the flag that triggers the process. All field names are case sensitive and the name side of the database fields all begin with iDB followed by a 2 digit number. The fields are sequentially numbered beginning with 01, there can not be missing field numbers. The value side of a database field must be an exact match for a field in the form that will collect data from your clients. The program will write a record containing the field names with the precedent character removed whenever the database file is empty. This first record will help when you import the record into your desktop database (such as Microsoft Access) as the fields will be created with the proper names. If you change the order of fields in Access it will use the names to put the data into the correct fields. Following is some data that resulted from the setup above. You will notice that each record has a field named END at the end, this will increase your confidence in the integrity of the data. Notice also that the second record has empty fields, these will do no harm and the file will import cleanly into Access. Fields are separated by the vertical bar character, this will not conflict with data and makes for a simple import procedure. Name|Email|Address|City|State|Zip|END Kim Davis|kim@dagra.com|113 Emmons Rd|Lansing|NY|14882|END Sam Smith|sam@dagra.com|||||END To retrieve data from the server you should FTP the cust1.txt file to your computer, check it and quickly FTP an empty copy back to the server. The empty copy will overwrite the one on the server leaving it empty. Note: Do not delete the file on the server or you will need to set the permissions when you create it again. The program will write the field name record whenever the file is empty. You will then simply import the text file into Access or another desktop database. Notes: Credit card numbers should not be saved into the database as it would be a security risk to accumulate them on the server. The maximum record length is 1000 characters and the maximum number of fields is 99. If you are anywhere close to these limits you will almost certainly have trouble handling and importing the resulting data. Special iTimeStamp FieldIf you want to save a timestamp into each database record there is a special field
that is generated internally just for that purpose, by calling iTimeStamp as
shown in this example. Top |