VBN Technical Overview

Overview

The Vote-By-Net system allows shareholders of a particular company to vote their shares via proxy over the Internet. It can contains links into the parallel "Consent Gathering System" (gathers consent for the sending of annual meeting materials on line) although the two systems are independent.

Shareholders connect to http://www.vote-by-net.com and are sent to https://www.vote-by-net.com/cgi-bin/login.pl to start the voting process. Optionally, a URL of the form http://www.vote-by-net.com/login/companyname can be setup within the system allowing a "branded" start page. (Many of the pages contain custom headers and footers that bring corporate identity into the proxy process.

Notice that some of these URLS are https, i.e. ports secured/encrypted by SSL.

Proxy administrators login to http://www.vote-by-net/cgi-bin/admin/admin.pl Because of limitations on the size of files and form info that can be uploaded under Netscape's implementation of SSL, some of the admin section is not on a 'secure server'. However, it is both password and IP-access-restriction protected (via the Netscape .nsconfig directive, which uses 'Standard Unix encrypted passwords'-- BBN provides a program wa_pass_encrypt on the server for encrypting these passwords.)

See Site Outlines Below for more file information

/home/207.121.184.68/ - The Mother of All Directories
- passwd - contans the encrypted passwords for the site. Referenced by .nsconfigs within the server root directories
- ftp_21/ - Not much used-- if you do a find -exec grep over this directory you're screwed when it hits a link to /dev/zero
- proxy/ - holds proxy files. Each is named with the 4 digit issue (i.e. company) number of the company it represents. The format is outlined later in this document
- cronjobs/ - holds scripts and programs run by cron to deliver votes
  - asc2eb_stripCR* - program converts ASCII to EBSCDIC, needed for some ancient IBM mainframes
  - mpack* - MIME packing program, used in generating e-mail
  - cron.results - results of cronjobs are shipped here, eliminating nightly crontab e-mail
  - gathervotes.pl* - used to gather the days votes, convert into ebscic, and mail away
  - resendvotes.pl* - sends the gathered votes a second time for redunancy
  - massmail/ - scripts for running mass-mailings
    - runmail.pl - rough script for taking in a \n deliminated list of email address (possibly with further custom info on each line) and sending out mail. needs to be customized on a per job basis, since part of its function is to send out indivual ID numbers to each shareholder. Best run as runmail.pl > results.txt &, which will make sure the process doesn't die if the login session time-outs. (tail -f can then be used to view the results live.) Can handle on the order of a thousand e-mails per hour
- source/ - has source code for mpac and asc2eb_stripCR, used in nightly mailings
- vote/ - votes are recored live into this directory. Each company's votes are stored in a text file (layout below) named after the company's issue number
- transport/ - temporary storage for nightly mailed filed, kept around here as a backup. Each file named with a date/timestamp of when it was sent.
- votestorage/similar to the files in transport, except the files are sorted by issue number, as well as named by date/timestamp
- http_80/ - The non-SSL server root. Mostly used for several admin functions.
  - cgi-bin/
    - whattime.pl* -- returns a webage with the current time on the server
    - admin/
      - CGI_Lite.pm - special perl 5 cgi-lib needed to support the Netscape upload tag
      - cgi-lib.pl* - standard cgi parsing library used by many scripts
      - setup.pl@ - link to file containing shared functions, variables, and directories.
      - admin.pl* - generates list of avaailable admin activities
      - fyi/ - functions to upload FAQs and other documents into /fyi/
        
        setup.pl* - directory locations
        list.pl* - lists FAQs now on systems, links to view, delete, and upload functionality
        upload.pl* - requests name of file for uploading on local PC
        doload.pl* - performs actual uploading from PC desktop, requires CGI_Lite.pm
        deleteconfirm.pl* - asks for delete confirmation
        delete.pl* - performs actual file delete
- htdocs/ - main site documents, contains a lot of odd crap from Black Dog Design
  - fyi@ - link to directory containing custom FAQs that have been uploaded by the admin
  - image/
    - art@ - link to directory that arbitrary art can be uploaded to by admin
    - logo - link to directory that company logos can be uploaded to by admin
  - images/ - graphics , more of a focus on generic buttons and pix
  - info/ - link to directory that holds Proposal, Nominee, and Option info linked to in a Proxy Card
  - login/ - directory contain custom named directories holding login pages that just have a link to their secure sever bretheren
- https_443/ - The SSL server root. Most of the user experience occurs here.

Perl Files

Each screen can be associated with the perl file that generated it. Here is a flowchart of the shareholder experience:

These files make use of javascript to implement intelligent onscreen behavior. In particular, proxy.pl implements radio buttons by javascript, can automatically fill in the appropriate boxes when 'Board's Recommendation' is selected, can ensure the form is filled out before proceding, etc.

Another important file is "setup.pl". Almost every other perl script relies on this file, both for configuration information (names of directories, locations of files, etc) and commonly used functions (to produce the html to show the logo, reading in a proxy file and putting the information into global variables, etc) "cgi-lib.pl" and "CGI_Lite.pm" are standard perl modules for parsing the CGI information (CGI_lite is used because it supports handling of the netscape 'upload' tag)

The admin experience is fairly straight forward, with utilities for the creation of proxies as well as the editing of graphical logos. Javascript is used extensively in proxyedit.pl, adding some smart behavior to the page (for instance, automatically filling in the custom color blanks)

Other Files and Directories

When the proxy admin creates a new proxy, a description of that proxy is created in /home/207.121.184.68/proxy. Each proxy ini file is named after the issue number of the paper proxy is represents. The files are of the following format:
($names are variable, everything else is a constant, colors indicate fields that grouped and repreated (ie unique information needed for nominee, for each proposal, for each option)

$companyname	company name
$startdate	unix date/time stamp for when proxy is eligible for being voted on
$enddate	unix date/time stamp for when proxy is no longer valid
$colorspec	color info in ready-for-BODY-tag form
NOLOGO or $logourl	NOLOGO = Don't use a graphical logo, anything else is the URL of logo graphic for every page except the proxy page
DONAME or NONAME	DONAME = repeat name at top of proxy in bold lettering, NONAME means don't
DOREC or NOREC or $rec	NOREC = Don't Display Board's Recommendation and don't use javascript to 'autocheck' Board's Recommendation, DOREC means do autochecking and automaticlaly generate written description of board's recommendation, anything else is custom text for board's recommendation
$nomcount	nuber of nominees for director
$nomcols	number of nominees in each row (usually 3 or 4)
$nompos	Position of Nominees within all Proposals.
$nom[0]	nominee's name
DOLINK or NOLINK	DOLINK = include link to more info, NOLINK = don't
$propcount	number of propositions
$prop[0] or NODESC	proposition name
DOLINK or NOLINK	DOLINK = include link to more info, NOLINK = don't
TYPEFAA or TYPEFW	TYPEFAA = for/against/abstain options, TYPEFW = for/withhold options
ag or fr or xx	Board's Recommendation for this issue: fr=for, ag=against/withhold, xx=no recommendation
$optcount	number of options at bottom of proxy
$opt[0]	option name
$optid[0]	option number
DOLINK or NOLINK	DOLINK = include link to more info, NOLINK = don't
DOLEGAL or NOLEGAL	DOLEGAL = include legal disclaimer, NOLEGAL = no legal disclaimer
(optional legal text)	text of legal recommendation, all on one line
(optional thanks message)	Message appearing after Proxy has been record, all on one line
commentemail	Addres to send comments to via e-mail
loginpagename	Name for static login page, usually of the form https://www.v-b-n.com/login/loginpagename. (Though actually set by the variable $dirloginpage) This allows external links directly to this page.
consentjump	[JUMP] says that a jump to the corresponding "online materials consent" will be offered, otherewise [NOJUMP]
doproxylogo	if [NONE}, doproxylogo is set to 0, otherwise dorpoxylogo is set to 1 and proxylogoname is set to this value- the proxy logo is the one used only on the proxy page itself, a sopposed to the regular logo used on all other pages.
consentjumptext	Text to print when the jump to consent is offered
commenttext	A brief message inviting the shareholder to send feedback using the feedback system, displayed on thanks screen
returntext	A brief message saying the user can go to FCTC pages or vote another proxy, displayed on thanks screen
headertext	HTML appearing at top of every customized page, except the proxy itself
footertext	HTML appearing at bottom of every customized page, except the proxy itself
longboardname	The long name for the companies "Board of Directors" term
shortboardname	The long name for the companies "Board" (of directors) term
tintext	On the login page, the text asking for the Taxpayer Identification Number
tinnotetext	On the login page, the text saying the vote won't count if the company has the TIN and its not entered
doboardplural	If this holds, [PLURALYES] $verber goes to "" and doboardplural is true, else $verber holds "s" and doboardplural is false. "Verber" is stuck to the end of the word "recommend", because if the term is "The Board", the verb needs to be "recommends" but if the term is "The Directors" then the verb needs to be "recommend"
checkthisboxtext	Text on proxy form saying check this box to vote WITH the board of directors
employeeoptiontext	if this line is not blank NOR "NOEMP", then employeeoptiontext is blank, otherwise this is the text on the thanks page inviting 'special shareholders' such as employees to press the proceed button below and vote their special shares differently. The results from the second time are then mailed immediately instead of recorded in the database, because they're processed by hand.
employeeoptionemail	Email to send the 'special votes' to.
employeenotification	Message on the Proxy itself that this (second) time through the votes will be processed seperately
employeepremention	Message on the Proxy itself (first time through) that employees and special shareholders will be given the option to vote special shares special-ly will be given later.

These files are used by proxy.pl to automatically generate the proxy form. Further information (the DOLINKs) are physical HTML files generated and stored on the server in the directory /home/207.121.184.68/https_443/htdocs/info, in a directory that has the same name as the prxy ini file. Nominee descriptions are named "n#.html", Propositions "p#.html", and options "o#.html", where # is the number of the object (counted starting at zero)

Logos are kept in /home/207.121.184.68/https_443/htdocs/image/logo.

Once the shareholder votes, the vote is stored in a file named after the issue number in the directory /home/207.121.184.68/vote.
Each record is 108 characters and has the following format:

Name Length/Type Description
Issue Number 4 digits Unique proxy identifier, prepended with zeros
Sequence Number 10 digits identifier of shareholder, prepended with zeros
Social Security Number 4 digits Last Four Digits of Taxpayer ID number (SSN) OR 4 Zeros
Proxy Vote Pattern 20 characters Contains an "M" and 19 spaces if the shareholder checked "follow board's recommendation" and no other proposal checkboxes or director checkboxes.
Otherwise, If there are nominees that are voted on: The first character is an "I" if the shareholder selects "For all directors except as noted below", otherwise "W"
the other proposals contains a F (for) A (against) or N (abstain) for all 3-option proposals, or a I (for) W (withhold) for all 2-option proposals. Spaces fill up the remaining 20 characters once all proposals have been recorded
Option Patterns 10 characters Every Option has an arbitrary number (1 through 10) associated with it. Call this number n. The nth character in the Option Pattern is a "Y" if that option was checked, and "N" if not. All other placeholders in the Option Pattern are filled with spaces
Directors Withhold 30 characters 30 "Y"s if the shareholder selected "Withhold from all nominees", otherwise "Y" for every name with a check, "N" for every name without a check, and spaces filling up the remaining 30 characters. If there is no Director Vote on this proxy, 30 spaces
PIN 6 digits 6 digit Pin. The first two digits are used by proxy.pl to ensure data integrity. The first two digits must meet the following algorithm:

Take the 16 digits of issue # + sequence # + CheckDigits
Add the digits of step 1, adding every EVEN digit in twice
Take the sum of step 2 and divide by 10. the remainder is the first PIN digit
take the 15 digits of issue # + sequence # + first PIN digit from step 3.
Add the digits of step 4, adding every ODD digit in twice
Take the sum of step 5 and divide by 10. the remainder is your second PIN digit

timestamp 6 characters Time of vote in HHMMSS in 24 hour format.
datestamp 8 characters Date of vote in MMDDYYYY format, months being numbered with January as 1.
End of Line 1 character Carriage Return

Daily Procedures

Every day a script, gathervotes.pl, is kicked off by a cronjonb to gather the days votes, compile them into a single file, and send that file to FCTC.

The script lives in /home/207.121.184.68/cronjobs and does the following:

Moves every vote file from vote/ to votestorage/ and renames it with the original name followed by a date and a time stamp: PPPP.YYYYMMDD.HHMMSS
Runs through each of these files and copies each vote record to a temp file, keeping track of how many lines moved.
Copies the temp file to the directory transport\ to a file named vote.YYYYMMDD.HHMMSS, prepending one line that describes the file. This line is a FIXED-LENGTH line of the following makeup:
```
WEBVOTE FOR MM/DD/YYYY TRANSMITTED AT HH:MM:SS WITH ###### RECORDS
```
note that the # of records is the actual number of records + 1 (it includes the descriptor line as a record) Also, the line is padded with spaces until it is exactly as long as an individual vote record.
This file is then fed into cronjobs/asc2eb_stripCR which converts it to EBSCIDIC and strips the carriage returns. The output is a temp file that is then fed to cronjobs/mailmime, a mail program that mails it as an attachment.

The source code for asc2eb_stripCR and mailmime are kept in /home/207.121.184.68/source

Name	Length/Type	Description
Issue Number	4 digits	Unique proxy identifier, prepended with zeros
Sequence Number	10 digits	identifier of shareholder, prepended with zeros
Social Security Number	4 digits	Last Four Digits of Taxpayer ID number (SSN) OR 4 Zeros
Proxy Vote Pattern	20 characters	Contains an "M" and 19 spaces if the shareholder checked "follow board's recommendation" and no other proposal checkboxes or director checkboxes. Otherwise, If there are nominees that are voted on: The first character is an "I" if the shareholder selects "For all directors except as noted below", otherwise "W" the other proposals contains a F (for) A (against) or N (abstain) for all 3-option proposals, or a I (for) W (withhold) for all 2-option proposals. Spaces fill up the remaining 20 characters once all proposals have been recorded
Option Patterns	10 characters	Every Option has an arbitrary number (1 through 10) associated with it. Call this number n. The nth character in the Option Pattern is a "Y" if that option was checked, and "N" if not. All other placeholders in the Option Pattern are filled with spaces
Directors Withhold	30 characters	30 "Y"s if the shareholder selected "Withhold from all nominees", otherwise "Y" for every name with a check, "N" for every name without a check, and spaces filling up the remaining 30 characters. If there is no Director Vote on this proxy, 30 spaces
PIN	6 digits	6 digit Pin. The first two digits are used by proxy.pl to ensure data integrity. The first two digits must meet the following algorithm: Take the 16 digits of issue # + sequence # + CheckDigits Add the digits of step 1, adding every EVEN digit in twice Take the sum of step 2 and divide by 10. the remainder is the first PIN digit take the 15 digits of issue # + sequence # + first PIN digit from step 3. Add the digits of step 4, adding every ODD digit in twice Take the sum of step 5 and divide by 10. the remainder is your second PIN digit
timestamp	6 characters	Time of vote in HHMMSS in 24 hour format.
datestamp	8 characters	Date of vote in MMDDYYYY format, months being numbered with January as 1.
End of Line	1 character	Carriage Return