#!/usr/bin/perl
use strict;
#---------------------------------------------------------------------#
# scheduled_mailings.pl (Beatitude)
# For instructions, see the pod of this file. try:
# pod2text ./scheduled_mailings.pl | less
#
# Or try online:
# http://dadamailproject.com/support/documentation/scheduled_mailings.pl.html
#
#---------------------------------------------------------------------#
# Required:
$|++;
#Change! the lib paths
use FindBin;
use lib "$FindBin::Bin/../";
use lib "$FindBin::Bin/../DADA/perllib";
BEGIN {
my $b__dir = ( getpwuid($>) )[7].'/perl';
push @INC,$b__dir.'5/lib/perl5',$b__dir.'5/lib/perl5/x86_64-linux-thread-multi',$b__dir.'lib',map { $b__dir . $_ } @INC;
}
use CGI::Carp qw(fatalsToBrowser set_message);
BEGIN {
sub handle_errors {
my $TIME = scalar(localtime());
print qq{
Yikes! App/Server Problem!
We apologize, but the server encountered a problem when attempting to complete its task.
More information about this error may be available in the program's own error log.
};
my $r = DADA::Template::Widgets::screen(
{
-data => \$t,
-vars => {
key => $key,
},
-list_settings_vars => $li, # Uh, ok - $li is global. That's stupid.
-list_settings_vars_param =>
{
-dot_it => 1,
},
},
);
return $r;
}
sub file_test {
my $fn = shift || undef;
my $r;
return '' if ! $fn;
$r .= $q->p({-class => 'error'}, 'Can\'t read file! ' . $fn) unless -r $fn;
$r .= $q->p({-class => 'error'}, 'File doesn\'t exist!' . $fn) unless -e $fn;
return $r;
}
sub url_test {
my $url = shift;
my $r = '';
require LWP::Simple;
return $r if ! $url;
eval { $LWP::Simple::ua->agent('Mozilla/5.0 (compatible; ' . $DADA::CONFIG::PROGRAM_NAME . ')'); };
if(!LWP::Simple::get($url)){
$r .= $q->p({-class => 'smallred'}, $q->i('Error fetching URL!'));
}
return $r;
}
sub show_help {
print q{
arguments:
-----------------------------------------------------------
--list a list's shortname
--help
--verbose
--test
--log filename
--version
-----------------------------------------------------------
Example: To run the schedules for "mylistshortname":
./schedule_mailings.pl --list mylistshortname
-----------------------------------------------------------
for instructions, try:
pod2text ./schedule_mailings.pl | less
-----------------------------------------------------------
};
exit;
}
sub version {
print "$DADA::Config::PROGRAM_NAME Version: $DADA::Config::VER\n\n";
exit;
}
sub logit {
my $action = shift;
open_log($Plugin_Config->{Log});
log_action($action);
&close_log;
}
sub open_log {
my $log = shift;
if($log){
open(LOG, ">>$log") or warn "Can't open '$log' because: $!";
chmod($DADA::Config::FILE_CHMOD, $log)
if $log;
$Have_Log = 1;
return 1;
}
}
sub log_action {
my ($action) = @_;
if($Have_Log){
print LOG $action;
}
}
sub close_log{
if($Have_Log){
close(LOG);
}
}
sub self_url {
my $self_url = $q->url;
if($self_url eq 'http://' . $ENV{HTTP_HOST}){
$self_url = $ENV{SCRIPT_URI};
}
return $self_url;
}
=pod
=head1 NAME
Beatitude - A Scheduled Mailer for Dada Mail
=head1 Obtaining The Plugin
Beatitude is located in the, I directory of the Dada Mail distribution, under the name: I
=head1 Description
Beatitude is a plugin for Dada Mail that allows you to compose
email messages to be scheduled for sending in the future.
Highly configurable, messages themselves can be in PlainText, HTML
or multipart/alternative and have an unlimited number of attachments.
The message itself can be composed in the plugin itself, fetched from a
file or from a webpage.
The schedules themselves can be anywhere from one minute to years
into the future and can be repeated infinitely. Schedules also have many
safegaurds to help send only new content; for example: if a scheduled mailing
is created to send the contents of a URL once a day, it will only send that
URL if the contents are different from the previous day.
=head1 REQUIREMENTS
=over
=item * Familiarity with setting cron jobs
If you do not know how to set up a cron job, attempting to set one up for Beatitude will result in much aggravation. Please read up on the topic before attempting!
=item * The Storable Module
If you have perl 5.8, this should already be installed. If it's not, you can grab it here:
http://search.cpan.org/~ams/Storable
=item * Shell Access to Your Hosting Account
Shell Access is sometimes required to set up a cronjob, using the:
crontab -e
command. You may also be able to set up a cron tab using a web-based control panel tool, like Cpanel.
Shell access also facilitates testing of the program.
=back
=head1 Installation
This plugin can be installed during a Dada Mail install/upgrade, using the included installer that comes with Dada Mail. The below installation instructions go through how to install the plugin manually.
If you do install this way, note that you still have set the cronjob, which is covered below.
=head1 Lightning Configuration/Installation Instructions
To get to the point:
=over
=item * Upload the scheduled_mailings.pl script into the cgi-bin/dada/plugins directory (if it's not already there)
=item * chmod 755 the scheduled_mailings.pl script
=item * run the plugin via a web browser.
=item * Set the cronjob
=back
=head1 Manual Installation
=head2 Configuring scheduled_mailings.pl Plugin Side
=head2 Change permissions of "scheduled_mailings.pl" to 755
The, C plugin will be located in your, I diretory. Change the script to, C<755>
=head2 Configure your .dada_config file
Now, edit your C<.dada_config> file, so that it shows the plugin in the left-hand menu, under the, B heading:
First, see if the following lines are present in your C<.dada_config> file:
# start cut for list control panel menu
=cut
=cut
# end cut for list control panel menu
If they are, remove them.
Then, find these lines:
# {
# -Title => 'Scheduled Mailings',
# -Title_URL => $PLUGIN_URL."/scheduled_mailings.pl",
# -Function => 'scheduled_mailings',
# -Activated => 1,
# },
Uncomment the lines, by taking off the, "#"'s:
{
-Title => 'Scheduled Mailings',
-Title_URL => $PLUGIN_URL."/scheduled_mailings.pl",
-Function => 'scheduled_mailings',
-Activated => 1,
},
Save your C<.dada_config> file.
=head1 Configuring the Cronjob to Automatically Run Beatitude
We're going to assume that you already know how to set up the actual cronjob, but we'll be explaining in depth on what the cronjob you need to set is.
=head2 Setting the cronjob
Generally, setting the cronjob to have Beatitude run automatically just means that you have to have a cronjob access a specific URL. The URL looks something like this:
http://example.com/cgi-bin/dada/plugins/scheduled_mailings.pl?run=1&verbose=1
Where, I is the URL to your copy of scheduled_mailings.pl
You'll see the specific URL used for your installation of Dada Mail in the web-based control panel for Beatitude, under the fieldset legend, Manually Run Beatitude. under the heading, Manual Run URL:
This will have Beatitude check any awaiting messages.
You may have to look through your hosting account's own FAQ, Knowledgebase and/or other docs to see exactly how you invoke a URL via a cronjob.
A Pretty Good Guess of what the entire cronjob should be set to is located in the web-based crontrol panel for Beatitude, under the fieldset legend, B, under the heading, B:
From my testing, this should work for most Cpanel-based hosting accounts.
Here's the entire thing explained:
In all these examples, I'll be running the script every 5 minutes ( */5 * * * * ) - tailor to your taste.
=over
=item * Using Curl:
*/5 * * * * /usr/local/bin/curl -s --get --data run=1 --url http://example.com/cgi-bin/dada/plugins/scheduled_mailings.pl
=item * Using Curl, a few more options (we'll cover those in just a bit):
*/5 * * * * /usr/local/bin/curl -s --get --data run=1\;verbose=0\;test=0 --url http://example.com/cgi-bin/dada/plugins/scheduled_mailings.pl
=back
=head3 $Plugin_Config->{Allow_Manual_Run}
If you DO NOT want to use this way of invoking the program to check awaiting messages and send them out, make sure to change the variable, $Plugin_Config-{Allow_Manual_Run}> to, 0:
$Plugin_Config->{Allow_Manual_Run} = 0;
at the top of the scheduled_mailings.pl script. If this variable is not set to, 1 this method will not work.
=head2 Security Concerns and $Plugin_Config->{Manual_Run_Passcode}
Running the plugin like this is somewhat risky, as you're allowing an anonymous web browser to run the script in a way that was originally designed to only be run either after successfully logging into the list control panel, or, when invoking this script via the command line.
If you'd like, you can set up a simple Passcode, to have some semblence of security over who runs the program. Do this by setting the, C<$Plugin_Config-{Manual_Run_Passcode}> variable in the scheduled_mailings.pl source itself.
If you set the variable like so:
$Plugin_Config->{Manual_Run_Passcode} = 'sneaky';
You'll then have to change the URL in these examples to:
http://example.com/cgi-bin/dada/plugins/scheduled_mailings.pl?run=1&passcode=sneaky
=head3 Other options you may pass
You can control quite a few things by setting variables right in the query string:
=over
=item * passcode
As mentioned above, the C<$Plugin_Config-{Manual_Run_Passcode}> allows you to set some sort of security while running in this mode. Passing the actual password is done in the query string:
http://example.com/cgi-bin/dada/plugins/scheduled_mailings.pl?run=1&passcode=sneaky
=item * verbose
By default, you'll receive the a report of how Beatitude is doing checking the schedules and if it does send out one.
This is sometimes not so desired, especially in a cron environment, since all this informaiton will be emailed to you (or someone) everytime the script is run. You can run Beatitude with a cron that looks like this:
*/5 * * * * /usr/local/bin/curl -s --get --data run=1 --url http://example.com/cgi-bin/dada/plugins/scheduled_mailings.pl >/dev/null 2>&1
The, >/dev/null 2>&1 line throws away any values returned.
Since all the information being returned from the program is done sort of indirectly, this also means that any problems actually running the program will also be thrown away.
If you set verbose to, ``0'', under normal operation, Beatitude won't show any output, but if there's a server error, you'll receive an email about it. This is probably a good thing. Example:
* * * * * /usr/local/bin/curl -s --get --data run=1\;verbose=0 --url http://example.com/cgi-bin/dada/plugins/scheduled_mailings.pl
=item * test
Runs Beatitude in test mode by checking the messages awaiting and parsing them, but not actually carrying out any sending.
=back
=head3 Notes on Setting the Cronjob for curl
You may want to check your version of curl and see if there's a speific way to pass a query string. For example, this:
*/5 * * * * /usr/local/bin/curl -s http://example.com/cgi-bin/dada/plugins/scheduled_mailings.pl?run=1&passcode=sneaky
Doesn't work for me.
I have to use the --get and --data flags, like this:
*/5 * * * * /usr/local/bin/curl -s --get --data run=1\;passcode=sneaky --url http://example.com/cgi-bin/dada/plugins/scheduled_mailings.pl
my query string is this part:
run=1\;passcode=sneaky
And also note I had to escape the, ; character. You'll probably have to do the same for the & character.
Finally, I also had to pass the actual URL of the plugin using the --url flag.
=head1 Command Line Interface
There's a slew of optional arguments you can give to this script. To use Beatitude via the command line, first change into the directory that Beatitude resides in, and issue the command:
./scheduled_mailings.pl --help
=head2 Command Line Interface for Cronjobs:
One reason that the web-based way of running the cronjob is better, is that it
doesn't involve reconfiguring the plugin, every time you upgrade. This makes
the web-based invoking a bit more convenient.
=head2 #1 Change the lib path
You'll need to explicitly state where both the:
=over
=item * Absolute Path to the site-wide Perl libraries
=item * Absolute Path of the local Dada Mail libraries
=back
I'm going to rush through this, since if you want to run Beatitude this way
you probably know the terminology, but:
This script will be running in a different environment and from a different location than what you'd run it as, when you visit it in a web-browser. It's annoying, but one of the things you have to do when running a command line script via a cronjob.
As an example: C
