18.4. Time-Based Tasks

The Cron module provides infrastructure for executing periodic, time-based tasks within Perforce Chronicle. In addition to built-in time-based tasks, such as scheduling workflow transitions (see Section 5.7, “Scheduling Transitions”), developers may subscribe to one or more periodic pub/sub topics to execute their own tasks. The topic template is p4cms.cron.frequency, where frequency is one of hourly, daily, weekly, or monthly. Please see Section 14.2.1, “Publish/Subscribe” for additional topic details.

The Cron module only guarantees that topics described above are not published too often. For example, the p4cms.cron.hourly is executed, at most, once per hour. By itself, Chronicle cannot guarantee topic publication at appropriate times because it normally only executes when fielding a request, and only for long enough to provide a response. To ensure that topics are published regularly and often enough, a request to the Cron module must be made at least once per hour. Unix-like systems can use a cron job to make this happen. Alternatively, you can use the optional Easy Cron module provided with Chronicle (see below).

18.4.1. Setting Up a Cron Job

On a UNIX-compatible system, the following line needs to be added to the system crontab file (its usual path is /etc/crontab, but may be located elsewhere depending on the distribution you use):

  0 * * * *     wget -O - -q -t 1 http://example.com/cron

where http://example.com needs to be replaced by your site URL.

The above line executes the wget utility at the top of each hour, making a web request to the Cron each time.

The "-O -" options tell wget to write its output to standard out, "-q" runs quietly and "-t 1" limits the number of retries to one. If you do not have wget, try curl with comparable options.

The response to cron requests is a JSON encoded report for each topic:

  {"hourly":"executed","daily":"failed","weekly":"skipped","monthly":"skipped"}

The example report above says that:

p4cms.cron.hourly topic was successfully published
there were errors during publishing p4cms.cron.daily topic
p4cms.cron.weekly topic was not published (i.e. previously executed)
p4cms.cron.monthly topic was not published (i.e. previously executed)

18.4.2. Easy Cron

Easy Cron is an optional module shipped with Chronicle. When this module is enabled, a small piece of javascript is added to each page to send an AJAX request to site-url/cron. No additional system-level privileges or services are required. Please see Section 19.3, “Enabling and Disabling Modules” for further details.

Users should not notice any kind of delay or disruption when viewing the site. However, it does have a performance impact as every page view causes one additional request to the Cron module; for busy sites, the Easy Cron module should be disabled and the cron job approach described above should be followed.

	Warning
	If you use `Easy Cron`, be aware that no time-based tasks are executed until a request to your site is made. Pending tasks are only be executed once a request is made.