Introduction

FormMail is a generic CGI script that reformats information entered via an HTML form, and sends the results to someone via e-mail. FormMail can be used by anyone publishing documents on one of the ADN Web servers (icarus and tigger, as of this writing), without requiring prior authorization from the Computer Center.

FormMail has a new feature, as of version 3.01:

• You can force use of bluestem authentication, and capture the authenticated bluestem id in a file.

FormMail has a few features and changes, as of version 3.0:

• You can write submitted info to disk, either appended to a file, and/or as separate files. This in addition to sending email.
• You can record contact email, which will be reported to the user if certain errors occur.
• The url in <form action="..." > has changed. You must use the new url to use 3.0.

FormMail has many features, new as of version 2.0:

• The format of the mail body is under your control, and you control how the information from the HTML form is organized in the email.
• Multiple mail messages can be sent, each with a different format.
• Some input validity checking can be turned on, so for example, mail will not be sent unless certain fields are filled in.
• The HTML response can be dependent on the values of the filled-out fields. So a quiz could be developed, with the results displayed to the user and mailed to the teacher.
• Whether or not certain notes are sent, and whether or not certain HTML replies are returned, can be dependent on the values of the filled-out form.

You must prepare two files:

1. The original HTML form.
2. A configuration file, to be read by the FormMail cgi script, which tells the script how to behave when your HTML form is submitted.

In more detail:

1. Prepare the HTML form, put it on the Web, and make sure the HTML is valid.
2. Prepare a configuration file for your form. This config file must also be placed on the Web on tigger or icarus, although it is not intended to be publically viewed. The name of the config file is arbitrary, and each HTML form should have its own associated config file. For purposes of this documentation, I'll assume the config file is named config.sgml. (Note: in version 1.0 of FormMail, the config file had to be named .formcap and one config file could be used for many HTML forms. Version 2.0 and higher is different because the nature of the config file has become much more powerful.)
3. You will need to know the URL of this config file; more precisely, you will need to know the path part of the URL. That is, the URL without the "http://www.uic.edu/" host name part. For example, I have a file whose URL is http://www.uic.edu/~bobg/config.sgml, and therefore the config file path is simply /~bobg/config.sgml. Make sure your config file is publically readable, using the command chmod a+r config.sgml if necessary. If you can actually retrieve the config file with a web browser using the proper url, the permissions are fine.
4. Inside the HTML form itself, you will of course need an <form action=" ..."> tag. This tag will depend on whether your config file is in your personal homespace, or in a departmental directory.

   
   <form method="POST" 
   action="http://www.uic.edu/htbin/cgiwrap/bin/formmail/FormMail/path_of_config_file"> 
   
   

   So in particular, for the above example, it would be:

   
   <form method="POST" 
   action="http://www.uic.edu/htbin/cgiwrap/bin/formmail/FormMail/~bobg/config.sgml">
   
   

   (If this was on icarus, use www2.uic.edu instead of www.uic.edu) Note: The path to the FormMail script is different from version 1.

   The URL in the action attribute is a little complicated, but don't be confused. You can break it into two parts. There's the part that specifies where the FormMail program lives:

   
   http://www.uic.edu/htbin/cgiwrap/bin/formmail/FormMail/~bobg/config.sgml
   
   

   And there's the part that specifies where the config file lives:

   
   http://www.uic.edu/htbin/cgiwrap/bin/formmail/FormMail/~bobg/config.sgml
   
   

   You must have both parts for FormMail to work. Check the examples later if you aren't sure.
5. The format of the config file can be complicated, and will be discussed in the next section. For now, you can construct a minimal config file for testing. It should look like:

          <!DOCTYPE form SYSTEM 'FormMail-3.0.dtd'>
          <form name="myform">
          </form>
          

   By the way, don't worry if the current version is 3.0x. The above DOCTYPE declaration will work fine for all version 3.xx releases.
6. Be sure to check out the examples section. They are probably easier to understand than the reference section on config file format.

You may force the user to authenticate with bluestem before submitting the form, and capture the authenticated netid. To do so:

• Make sure the user is already bluestem authenticated before the form is submitted. If not, bluestem will be invoked but the form information will not be transmitted to FormMail. (For the technically inclined this is because http posts cannot be redirected.)
• You must use the appropriate ACTION attribute in the FORM tag. Instead of this:

  
  <form method="POST" action="http://.../cgiwrap/..."> 
  
  

  Do this:

  
  <form method="POST" action="https://.../cgiwrap-auth/..."> 
  
  

• Enforce the use of bluestem with the tag <auth vtype=bluestem>
• Capture the authenticated id via the variable $fm_auth_bluestem_id

You can probably ignore this section. But if, for some reason, you need to process received mail automatically, perhaps just writing it to a file, I suggest using procmail.

NOTE: As of FormMail 3.0, you can use FormMail to write directly to a file. You won't need procmail for this, although you might need procmail for more extensive processing in rare cases.

An article on procmail in The ADN Connection describes how to do this.

Very briefly, you set up a ~/.procmailrc file with the recipes for mail handling you want. As an example:

:0
* ^X-fm_form:.*form1
! myfriend@blah.uic.edu

:0:
* ^X-fm_form:.*form2
mail/myforms

I strongly suggest you read the man pages for procmailex and procmailrc before actually using procmail. Also, be sure you test the procmail conditions by actually sending mail. And include in your tests some mail that should just go through as normal. Procmail is very powerful, and you want to be sure you know what it is doing to you!