CiviCRM includes a number of "Jobs" which process data and handle batch tasks "in the background". The available jobs are listed below, with a description of their purpose and required parameters. Your site / system administrator should review the available jobs, and determine which ones need to be run on a regular basis. These jobs can be configured and enabled from the Scheduled Jobs page (Administer > System Settings > Scheduled Jobs). Jobs can also be executed manually from this page. However, for most sites it is best to run the required jobs from the server command line, often as one or more automatically scheduled "cron" jobs.
A "run frequency" can be set for each enabled job, allowing you to configure a single "master" cron task to trigger ALL enabled CiviCRM jobs whose next run is due. For example, you may want to run the CiviMail mailing scheduler every time your master cron task runs (which might be once a minute). However, you only want the Address geocoder job to run once a day. You can enable both jobs, and set the run frequency for the mailing scheduler to "Every time cron job is run", while setting the frequency for the Address geocoded to "Daily".
The format to enter the parameters for those jobs that have available parameters listed in the table below is one parameter per line. For example for Greetings Updater you can enter the following in the parameters textbox to update all Individual postal greetings:
To actually trigger all the enabled jobs in Scheduled Jobs you will have to set up a cron job on the server that does this. You can find out how below in the section "Command-line Syntax for Running Jobs".
Note that the parameters for the relevant scheduled jobs should be returned by running getfields on the relevant job. We really want the UI to leverage these getfields results for dynamic documentation
Scheduled Jobs Editing Fields
The API fields are:
Again you'll need to read the API reference or check the documentation in the files themselves for details about available command parameters and their effects.
The result of this entry is a scheduled call to the API function defined by the fields. For example, if your fields were:
civicrm_api3 Activity get with parameter contact_id=352
The result would be a call to function civicrm_api3_activity_get ($params) in file civicrm/api3/Activity.php, where $params=array(contact_id->532).
You can explore APIs, actions, and parameters at the API explorer, which is included in your CiviCRM installation at yourwebsite.com/civicrm/api/explorer. An explanation and video tour of the API explorer is here. Once you have a working API call at the API explorer you can transfer the same API call, action, and parameters to create a new Scheduled Job that will carry out that same task automatically.
Command-line Syntax for Running Jobs
/usr/bin/drush -u 1 -r /path/to/drupal @sites civicrm-api job.execute auth=0 -y
(-u 1 means user 1, put the user that has the needed permissions, with 1 you're sure it will work)
/usr/bin/drush -u 1 -r /path/to/drupal -l www.example.org civicrm-api job.execute auth=0 -y
See the drush documentation for the -r and -l options. If successful, this command will output an array with a key/value of error = 0. In addition to the Drupal user permissions, you may also need to pay attention to the file permission of the linux user that the command runs as (e.g. typically run this command as the same user as apache - "apache", "nobody", or "www-data" are the most likely candidates).
PHP cli method
This method requires a valid Username and Password (for a Drupal, Joomla or WordPress user who has adequate permissions for the job or jobs being run). If you use drupal, use the drush method, that is easier to configure and more secure (it doesn't require to put the user password)
Typical set up: Use Cron to give CiviCRM the chance to process enabled scheduled jobs according to the frequencies set. e.g. every 15 minutes is a reasonable poll time. Here's a template line you might use in your user crontab:
The -s parameter is the site name, and defaults to 'localhost'. It should be set the FQDN (fully qualified domain name) of your site (eg, 'example.com') Some jobs rely on this being set (in certain cases, the CiviMail mailing scheduler uses this FQDN to generate absolute URLs when relative URLs are in the email).
To run ALL scheduled jobs that are Enabled and are due to run based on last run and run frequency as a one-off from the command-line:
To run a specific job (regardless of Enabled status or last run time):
For example, to run Greeting updater job which requires ct (contact type) and gt (greeting type) parameters
You can run ALL scheduled jobs that are Enabled and are due to run based on last run and run frequency by invoking a URL with curl or wget. You can also invoke specific jobs via URL. This method requires a valid Username and Password (for a Drupal, Joomla or WordPress user who has adequate permissions for the job or jobs being run). It also requires you to pass in the CIVICRM_SITE_KEY which is configured by editing your copy of civicrm.settings.php (see Configuring your Site Key below).
Run ALL Scheduled Jobs via URL
Calling cron.php as shown below will run ALL scheduled jobs that are Enabled and are due to run based on last run and run frequency:
When calling these urls using wget from within a crontab, enclose the url in single quotes, like so:
An alternative way to set up cron job is using webcron like https://www.easycron.com.
Run a Specific Job via URL
You can also run any single job via URL by passing job=<api_action> as well as any required parameters. For example to run the Update Greeting job via URL:
Specific Job via URL works only for API entity = job
Note that you can execute API actions only from the API entity "job"; this is hard-coded into cron.php. So you can't call any of the built in API functions (other than those under entity "job") using cron.php, but you also can't create a new API action So for instance, if you create new API entity called "myapi" with API action "my action" then you would be able to call that action via the Scheduled Jobs page but you will not be able to call it via cron.php.
A possible workaround for this problem is here: http://forum.civicrm.org/index.php/topic,28215.0.html
Running CiviCRM crons in Aegir
If you are using the Aegir hosting environment, with the provision_civicrm sub-module, you can automate the installation of a new cron for each site using the hosting_civicrm_cron module. You can also use the Drush method below to call CiviCRM cron tasks.
Running CiviCRM crons using Drush
You can run cron manually for a site by using the drush command:
This assumes that you have an administrator account called "admin" with the correct CiviCRM permissions.
Currently (CiviCRM 4.2.x) you need to use an additional argument, 'auth=0', to work around CRM-11199.
Configuring your Site Key
If you are triggering jobs using the URL method, you must manually generate a site key, and then add it to your CiviCRM settings file.
Depending on which version of CiviCRM you've installed, you may have this setting in your file already with a value of null, or you may need to add the line. In either case, replace null with the value of your key.
EXAMPLE: If my generated site key value is: 3cx4aNkpQwxmM1hTMV~!B09iO6
* Finally, make sure that you include the key=<sitekey> parameter whenever your run any of these scripts.
DB Error: Connect failed
The connect failed error message means that CiviCRM was not able to connect to the SQL database at all. The problem may be in connecting to the CiviCRM database OR with the Drupal/Joomla/WordPress database. If your CiviCRM installation is otherwise working, the most likely cause is the connection to the Drupal/Joomla/WordPress database, which is accessed much less frequently.
The most likely cause is incorrect username, password, or other settings in the civicrm.settings.php file. Carefully check the setting for define( 'CIVICRM_UF_DSN' - your setting may have been incorrect for some time and enabling the cron process is only now exposing the problem.
DB Error: no such table
A common cause of this problem is if your Drupal installation has a table prefix. To validate the connection, CiviCRM looks at the users table while initializing the cron job. The specific name of the users table is set in yourpath/civicrm/admin/setting/uf (or civicrm/administer/system settings/CMS database integration). If the users table name set there does not match the actual table name in your Drupal SQL database you will get the 'no such table' error. Check your Drupal table prefix in settings.php (usually in sites/default) - look for a setting like $db_prefix = 'dru_';. In yourpath/civicrm/admin/setting/uf change the "Drupal Users Table Name" to match–for instance, if your prefix is dru_, change the table name to dru_users.
Wrong permissions for cli.php
If you are running cli.php directly via cron job you may need to change permissions of cli.php to allow it to execute. Depending on how cron runs and the owner of cli.php you might try one of these options–or use your ftp program to change file permission for cli.php similarly:
chmod 744 cli.php [Gives owner execute permissions]
chmod 754 cli.php [Gives owner & group execute permissions]
chmod 755 cli.php [Gives everyone execute permissions]
Running cli.php via php (as recommended above) will also solve this problem. Use this:
php /your/directory/structure/sites/all/modules/civicrm/bin/cli.php -u user -p password -e Job -a execute
Rather than this:
/your/directory/structure/sites/all/modules/civicrm/bin/cli.php -u user -p password -e Job -a execute
Also, some systems will require the cli version (e.g. /usr/bin/php-cli vs /usr/bin/php)
Using the URL method with https and cron fails silently
If your server has an older version of wget installed and you are trying to connect via https there are a couple of problems that can cause wget to exit.
The solution is to upgrade wget to a version with the proper https support. A workaround is to use the flag --no-check-certificate in your wget call.
*/15 * * * * wget --no-check-certificate -O - -q -t 1 'https://mysite.org/sites/all/modules/civicrm/bin/cron.php?name=username&pass=password&key=site-key'
If you've just upgraded to CiviCRM 4.3 on a multi-site install and your cron silently stops working, try switching to the Drush method (forum thread).
If you're using HostGator, and switched to PHP 5.3, check this thread.