Documentation

, by Denis Chenu

This plugin allow you to send email automatically, you can fully use an automated process to send invitation and reminder.

Sometimes you import participant by the LimeSurvey API, or your user’s import manually a lot of participant in a lot of different survey’s. And then you need a solution to send invitation automatically.

To use this plugin you need to have access to php cli on server, and to be allowed to create cron or scheduled task.

Before activating the plugin

LimeSurvey plugin cron system before this fix was broken.

Then before activating the plugin, test the LimeSurvey system with php application/commands/console.php plugin cron --interval=1

If you receive : exception 'CException' with message 'Application runtime path "/home/web/htdocs/limesurvey/application/runtime" is not valid. Please make sure it is a directory writable by the Web server process.' in /home/web/htdocs/limesurvey/framework/base/CApplication.php:294 or something similar : create manually the application/runtime directory.

The plugin settings

There are 2 part for this plugin setting : 1st part is for request settings : when mail is send by the server : this one didn’t have the host then you must set the host, directory and the script file name to have the good final url.

When you activate or view the settings for the first time : this settings is set to the actual url, directory and script.

Settings for send email by cron

After this settings : you can configure :

Maximum email to send
The maximum number of email to send for each participant in all survey : invitation and reminder.
Minimum delay between invitation and first reminder.
The minimum delay in day between the invitation and the reminder.
Minimum delay between reminders
The minimum delays between each reminders

This plugin takes all mails into account whether they are sent manually or automatically. Then if you send manually the first invitation, reminder was sent after your The minimum delay in day between the invitation and the reminder setting.

Test the plugin

The first step is testing of your LimeSurvey version php yourlimesurveydir/application/commands/console.php plugin cron --interval=1 sendMailCronSimulate=1.

With 2.6/2.06 version , you need a build up to 150729. The plugin was tested in 2.6 and 2.5X version on windows and linux.

If the test don’t send error : you can add the line to your crontab or scheduled task.

To check exactly what happen : you can use sendMailCronDebug=3 to see more details on what happen. Since sending email can be an important part of your system : always best to check it totally before adding the instruction inside the crontab.

Log of the plugin activity

You have 2 ways to log this plugin activity :

Because this plugin echo at console what happen : then you can use cron system to send an email, or test the plugin : error and info was echoed. To show more information you can use sendMailCronDebug : 0 to 3 (default is 1 to see global informations and error.

The plugin use Yii::log system too : 3 state : error, info and trace. This is loggued as application.plugins.sendMailCron

Example of usage in application/config/config.php

  1.       'log' => array(
  2.           'routes' => array(
  3.               'fileError' => array(
  4.                   'class' => 'CFileLogRoute',
  5.                   'levels' => 'warning, error',
  6.               ),
  7.               'sendMailCron' => array(
  8.                   'class' => 'CFileLogRoute',
  9.                   'levels' => 'info, warning, error',
  10.                   'categories'=>'application.plugins.sendMailCron',
  11.               ),
  12.           )
  13.       ),

Download

plugin settings by Survey

Since 2.0 release , the plugin settings use a dedicated page. You can always find it in Tools menu.

Tools menu

You can find all Survey specific settings.

Basic settings
The basic settings : Max email, minimal delay between invitation and reminder and between each reminder. By default : the Global Plugin settings
Batch size
You can specify a max batch size for each survey, remind invitation are sent before reminder. Then if you have more invitation than batch size : no reminder was sent. You can have 2 batch size : one global, one for invitation and one for reminders
When email must be sent
By day of the week : just choose day of the week for sending email for this survey.
By moment : if you add moment in global settings, you can choose here the moment to send email.
Token attribute usage
You can choose max email and delay by token attribute. Remind token selected use global parts, then only attribute with bigger part are used. For example, if you put a global max email to 2 : only token with email sent lowaer than 2 was selected and tested.

Usage of moment

By default sendMailCron send email at each cron event. But you can create moment for each cron event.

To do so :

  1. Add sendMailCronType on instruction (php application/commands/console.php plugin cron sendMailCronType=morning)
  2. Add moment list in plugin global setting : one moment by line
  3. In survey setting : you find the list of moment to send the email for this survey