NAME

make_email - generates an HPR Community News recording invitation email

VERSION

This documentation refers to make_email version 0.2.5

USAGE

make_email [-help] [-documentation] [-debug=N] [-month=DATE] [-[no]mail]
    [-from=FROM_ADDRESS] [-to=TO_ADDRESS] [-date=DATE] [-start=START_TIME]
    [-end=END_TIME] [-config=FILE] [-dbconfig=FILE]

./make_email -dbconf=$HOME/HPR/.hpr_livedb.cfg -date=2022-12-27

OPTIONS

-help

Prints a brief help message describing the usage of the program, and then exits.
-documentation -man

Prints the entire embedded documentation for the program, then exits.

Another way to see the full documentation use:

perldoc ./make_email
-debug=N

Enables debugging mode when N > 0 (zero is the default, no debugging output). The levels are:

Values are:
1. Reports all of the settings taken from the configuration file, the provided command line options or their default values. The report is generated early on in the processing of these values. Use -debug=2 for information about the next stages.
2. Reports the following (as well as the data for level 1):
  - .
    
    Details of the start date chosen
  - .
    
    Details of the year, name of month, readable date, and recording start and end times.
  - .
    
    The subject line chosen for the email.
  - .
    
    The date of the show being searched for in the database.
  - .
    
    The number of the show found in the database.
-month=DATE

Defines the month for which the email will be generated using a date in that month. Normally (without this option) the current month is chosen and the date of recording computed with in it. The month specified here is provided as a ISO8601 date such as 2014-03-08 (meaning March 2014) or 1-Jan-2017 (meaning January 2017). Only the year and month parts are used but a valid day must be present.
-[no]mail

** NOTE ** The sending of mail does not work at present, and -nomail should always be used.

Causes mail to be sent (-mail) or not sent (-nomail). If the mail is sent then it is sent via the local MTA (in the assumption that there is one). If this option is omitted, the default is -nomail, in which case the message is appended to the file mailer.testfile in the current directory.
-from=FROM_ADDRESS

** NOTE ** The sending of mail does not work at present.

This option defines the address from which the message is to be sent. This address is used in the message header; the message envelope will contain the real sender.
-to=TO_ADDRESS

** NOTE ** The sending of mail does not work at present.

This option defines the address to which the message is to be sent.
-date=DATE

This is an option provides a non-default date for the recording. Normally the script computes the next scheduled date based on the algorithm "Saturday before the first Monday of the next month" starting from the current date or the start of the month given in the -month=DATE option. If for any reason a different date is required then this may be specified via this option.

The recording date should be given as an ISO8601 date (such as 2014-03-08).
-start=START_TIME

The default start time is defined in the configuration file, but if it is necessary to change it, this option can be used to do it. The START_TIME value must be a valid HH:MM time specification.
-end=END_TIME

The default end time is defined in the configuration file, but if it is necessary to change it, this option can be used to do it. The END_TIME value must be a valid HH:MM time specification.
-config=FILE

This option defines a configuration file other than the default .make_email.cfg. The file must be formatted as described below in the section CONFIGURATION AND ENVIRONMENT.
-dbconfig=FILE

This option defines a database configuration file other than the default .hpr_db.cfg. The file must be formatted as described below in the section CONFIGURATION AND ENVIRONMENT.

The default file is configured to open a local copy of the HPR database. An alternative is .hpr_livedb.cfg which assumes an SSH tunnel to the live database and attempts to connect to it. Use the script open_tunnel to open the SSH tunnel.

DESCRIPTION

Makes and sends(*) an invitation email for the next Community News with times per timezone. The message is structured by a Template Toolkit template, so its content can be adjusted without changing this script.

In normal operation the script computes the date of the next recording using the algorithm "Saturday before the first Monday of the next month" starting from the current date or the start of the month (and year) given in the -month=DATE option.

It uses the recording date (-date=DATE option) to access the MySQL database to find the date on which the show will be released. It does that so the notes on that show can be viewed by the volunteers recording the show. These notes are expanded to be usable during the recording, with comments relating to earlier shows being displayed in full, and any comments missed in the last recording highlighted. Comments made to shows during the past month can be seen as the shows are visited and discussed.

The email generated by the script is sent to the HPR mailing list, usually on the Monday prior to the weekend of the recording.

Notes: * Mail sending does not work at present.

DIAGNOSTICS

Unable to find ...

The configuration file specified in -config=FILE (or the default file) could not be found.
Use only one of -month=MONTH or -date=DATE

These options are mutually exclusive. See their specifications earlier in this document.
Missing start/end time(s)

One or both of the start and end times is missing, either from the configuration file or from the command line options.
Missing template file ...

The template file specified in the configuration file could not be found.
Various database messages

The program can generate warning messages from the database.
Invalid -date=DATE option '...'

An invalid date has been supplied via this option.
Date is in the past '...'

The date specified in -date=DATE is in the past.
Invalid -month=DATE option '...'

An invalid date has been supplied via this option.
Date is in the past '...'

The month specified in -month=DATE is in the past.
Various Template Toolkit messages

The program can generate warning messages from the Template.
Couldn't send message: ...

The email mesage has been constructed but could not be sent. See the error returned by the mail subsystem for more information.

CONFIGURATION AND ENVIRONMENT

EMAIL CONFIGURATION

The program obtains the settings it requires for preparing the email from a configuration file, which by default is called .make_email.cfg. This file needs to contain the following data:

<email>
    server = MUMBLE_SERVER_NAME
    port   = MUMBLE_PORT
    room   = NAME_OF_ROOM
    starttime = 18:00:00
    endtime = 20:00:00
    template = NAME_OF_TEMPLATE
</email>

DATABASE CONFIGURATION

The program obtains the credentials it requires for connecting to the HPR database by loading them from a configuration file. The default file is called .hpr_db.cfg and should contain the following data:

<database>
    host = 127.0.0.1
    port = PORT
    name = DBNAME
    user = USER
    password = PASSWORD
</database>

The file .hpr_livedb.cfg should be available to allow access to the database over an SSH tunnel which has been previously opened.

DEPENDENCIES

DBI
Date::Calc
Date::Parse
DateTime
DateTime::Format::Duration
DateTime::TimeZone
Getopt::Long
Mail::Mailer
Pod::Usage
Template

BUGS AND LIMITATIONS

There are no known bugs in this script. Please report problems to Dave Morriss (Dave.Morriss@gmail.com) Patches are welcome.

AUTHOR

Dave Morriss (Dave.Morriss@gmail.com) 2013 - 2023

LICENCE AND COPYRIGHT

This program is free software. You can redistribute it and/or modify it under the same terms as perl itself.

Back to Community_News page