Notes on setting up scheduled jobs in CiviCRM, part of a larger series on configuring CiviCRM.
The following notes are based on Managing Scheduled Jobs, part of the CiviCRM official documentation.
SELECTING AND ENABLING JOBS
CiviCRM has many background jobs available. Out of the box none of them are enabled, which is just as well because different installations will have different needs. Go to Administer > System Settings > Scheduled Jobs and go through the list of what is available.
As an example, take the first job on the list, Clean-up Temporary Data and Files. This I will want to enable, so I select More > Execute Now. Then once it has run, I select View Job Log and review the output. If there were no errors and I am otherwise satisfied, I enable the job at More > Enable.
Repeat the previous paragraph for all jobs you wish to enable. There are so many jobs available that for an initial setup I only enable those that are wanted and run without error out of the box. I continue as below, and only later return to reconsider those jobs that require additional work.
PREPARING A COMMAND TO AUTOMATE THE JOBS
Now that the jobs have been selected and run without error, your next step is to prepare a command that will run all enabled jobs. There are several alternatives; the ones I have tried are:
PHP cli method
My preferred method. I start with the provided command to run all enabled jobs:
$ php /path/to/civicrm/bin/cli.php -u USER -p PASSWORD -e Job -a execute
On Ubuntu 12.10 I had to run this command as the user www-data. Oddly, the command executed properly even with invalid values for user and password, but refused to execute if the -u and -p options were omitted entirely.
On one Windows installation (Windows 7, WampServer with PHP 5.4, Joomla 2.5, CiviCRM 4.3) I used the following command:
C:wampbinphpphp5.4.12php.exe C:wampwwwadministratorcomponentscom_civicrmcivicrmbincli.php -u USER -p PASSWORD -e Job -a execute
Notice the version-specific path to the PHP executable. This is bad form and should be changed to a more robust alias of some sort.
Unlike my experience on Linux, on Windows I needed to specify a valid Joomla user and password.
Many PHP warning messages were printed to stdout, so much so that they overfilled the shell buffer. All jobs were completed without error, however, so I chose to be sloppy and ignore the warnings.
The result was the ever-unenlightening 500 Internal Server Error. A quick web search turned up nothing useful, so I switched to the PHP cli method above.
Testing your command
Once you have your command, run it. Ideally no error messages should appear on the command line, though as noted above I don’t always follow my own advice. Refresh CiviCRM’s Scheduled Jobs page and confirm that the appropriate enabled jobs were run without error.
AUTOMATING THE JOBS
Now that you have a working command that runs enabled jobs, your final task is to automate it by configuring your server’s environment to periodically run this command. For a small organization with a few users, every 15 minutes might be a good frequency. A large organization might need to run it more often.
Each operating system has its own tools to automate the running of a periodic task:
- Linux: Cron. On Ubuntu 12.10 I set up the cron job to execute as the user www-data.
- Windows: Task Scheduler.
These notes refer to CiviCRM 4.3 and were last updated 22 September 2013.