PNCE Calendar Docs: Automatic Emails

PNCE Calendar Application Documentation

Automatic Emailing of Seminars, Colloquia

The PNCE Calendar Application sends email out to the colloquia mailing list periodically to inform people of the following weeks colloquia and seminars, and to inform them of changes in the schedule. Normally these are done automatically from a cron job, but there is a fair degree of flexibility provided for unusual situations.

The application consists of a pair of perl scripts invoked from cron to send out the email, both located in /group/phys-admin/project/Calendar/perl-scripts:

1. mail_seminar_list.pl: This will send out an announcement of all seminars for the next calendar week from the current date (Sunday through Saturday). Typically run weekly from crontab, every late Friday afternoon.
2. mail_seminar_updates.pl: This will send out a list of changes/corrections to the calendar since the last mailing. Basically, any event with a modification date after the last mailing, that did not already occur, and whose date was covered by the last mailing, is included in the list. No email gets sent out if no events match the criteria. Typically run from crontab daily, in the early morning. Most times should not produce any email.

Both scripts are controlled by files in /group/phys-admin/project/Calendar/data/email_status. The following files are used:

• no_weekly_email: As long as this file is present, the mail_seminar_list.pl script will not send out any email.
• no_update_email: As long as this file is present, the mail_seminar_updates.pl script will not send out any email.
• no_email: This prevents either script from sending out email. If exists, equivalent to no_weekly_email and no_update_email both existing.
• last_sem_date: This file contains a time stamp giving date of the last day for which seminar announcements were mailed. It is automatically updated when mail_seminar_list.pl is called. mail_seminar_updates.pl uses this to determine the end date for the list of event errata sent out.
• last_weekly_email: This file contains the time stamp of when the mail_seminar_list.pl script last sent out mail. It is automatically updated when the script runs. The script will not send out mail again until a specified period elapses (typically 3 days); this can be used to have the cron job run multiple times (possibly on multiple machines) to eliminate some single points of failure. It is also used by mail_seminar_updates.pl to determine which events have been modified since the last mailing.
• last_update_email: This file contains the time stamp of when the mail_seminar_updates.pl was last run. It is automatically updated when the script runs, and the script will abort if run again too soon (usually just shy of a day, e.g. 22 hours). It is also used to determine which events have been modified recently enough to send email out.

The files containing timestamps should consist of a single line of text containing a number representing the number of seconds since 1970.

mail_seminar_list.pl simply takes the reference date (by default now), computes the following calendar week (Sunday through Saturday), collects all events in that time range, and mails a list out. It will not send anything out if the reference date is not at least a specified time period (e.g. 3 days) later than the timestamp in last_weekly_email.

mail_seminar_updates.pl takes the reference date (by default now), and the timestamp from last_sem_date. It also takes the later timestamp from last_weekly_email and last_update_email, as last_mail. It makes a list of all events in the time range from the reference date to midnight on last_sem_date with a modification date after last_mail. This list, if not empty, is then mailed out. No mail is sent if the list is empty, or if reference date is too close to last_update_email date (typically must be at least 22 hours after). Note that last_update_email is updated even if the list of events is empty (even though no mail sent out).

Both scripts take a number of optional arguments, mainly for testing and debugging. When used in production, would most likely only use the argument --quiet, or maybe no arguments. The arguments are basically the same for both scripts:

• --help: Displays a brief help summary and exits. No mail sent out.
• --[no]quiet: In quiet mode, no output is produced unless a serious error occurs. In particular, no message is output if email is skipped because of an email_status file, etc. Default is noquiet.
• --[no]verbose: In verbose mode, several lines of output would typically be produced describing what the code is doing. E.g., outputs that mail is being sent, when week of events read, etc. Default is noverbose.
• --date "DATE": Sets the reference date to DATE, which can be in any reasonable, human readable format. If omitted, the reference date is the current time. Mainly for testing, debugging, and even there can have weird consequences.
• --[no]force: In force mode, the program will continue to run even if status files in email_status directory would normally prevent running. Default is noforce.
• --[no]update: In update mode the files email_status/last* get updated with new timestamps as appropriate. In noupdate mode, they are not updated. Default is update.
• --[no]mail: In mail mode, mail might get sent (will get sent if there is something to send). In nomail mode, the event list is generated, but no mail is ever sent. Default is mail.
• --[no]stdout: In stdout mode, any mail that might have gone out also gets printed out to stdout. This happens independently of the mail setting. In nostdout mode, the email is not printed to stdout. Default is nostdout.
• --[no]test: Test mode is the same as --nomail --noupdate --stdout. notest mode does nothing. Default is notest.