Overview
ProcessMaker is a web application which normally executes actions in response to users' actions. Nonetheless, Events, the Case Scheduler and Notifications in ProcessMaker are only executed when the cron.php script is run.
For testing purposes, the cron.php script can be executed manually from the command line of the server where ProcessMaker is installed.
For production use, it is best to automate the execution of cron.php by following the instructions below to either configure a cron job in Linux/UNIX or set up a Scheduled Task in Windows. Note that it is not recommended to execute cron.php more than once every 5 minutes due to the heavy processing which it incurs.
Manually executing cron.php
The cron.php file is executed from the command line on the server where ProcessMaker is installed, which means that PHP-CLI should be installed on the server running ProcessMaker. The ProcessMaker Windows Installer automatically installed PHP-CLI, but it may not have been installed if ProcessMaker was manually installed.
To test a feature which is executed by cron.php, such as Events, Scheduled Cases, Notifications, unpausing of cases, etc., open a terminal on the server where ProcessMaker is installed. If using Windows, open a terminal can be opened by going to Start > All Programs > Accessories > Command Prompt. Then, enter the command to execute the workflow/engine/bin/cron.php file. The location of the file depends on the system. For example:
Windows XP/2003:
Windows Vista/7/8/10/2008/2012:
Linux/UNIX:
If the cron.php script is executing without any options, all pending activities will be automatically executed for all workspaces. To save processing, it may be useful to specify only certain workspaces or to specify that only certain types of activities (events, scheduled cases, notifications, etc.) be executed. For testing purposes, the +d option can be used to specify an alternative date and time for the script, so events and scheduled cases in the past or future can be executed.
Syntax of cron.php Options
Options:
+dSpecify an alternative date and time for the script.
By default, the script will execute using the server's current system time. If may be useful to specify an alternative date and time when testing for past or future events or scheduled cases. Remember to use 4 digits for specifying the year and 2 digits for specifying the month, day, hour, minute and seconds. The time is on a 24 hour clock.
Ex: cron.php +d"2011-09-25 07:05:59"
+wSpecify a workspace whose pending activities will executed.
By default, the pending activities in all workspaces are executed. To save processing, it can be useful to only execute the pending activities in a single workspace. Remember the workspace names are case sensitive.
Ex: cron.php +wworkflow
ACTIVITIESDefine which activities should be executed:
events - Execute any pending events.
scheduler - Execute any pending scheduled cases.
unpause - Unpause cases (which are scheduled to be unpaused).
emails - Send any pending emails.
plugins - Activate plugins.
calculate - Calculate the duration of elapsed time for tasks.
unassigned-case - Available from version 2.5.0 on. Send pending notifications for unassigned cases to be claimed. This parameter is one of the actions included when the cron is executed; however, it is not possible to set this activity as a parameter when cron will be executed.
Multiple activities can be specified by separating each one with spaces:
Ex: cron.php events emails plugins
+forceAvailable from version 2.5.0 on. This option ensures that the cron.php file is executed by stopping the execution of any existing cron job and deleting its temporary files, so the current cron can be executed. Remember that only one instance of cron can be executed at a time, so without the+forceoption, cron.php will not be executed if another instance is already being executed.
When cron.php executes, it will report which activities where executed and how many workspaces were processed:
Note: To cancel the execution of cron.php, press CTRL+C in the command line or use the kill command in Linux or the Task Manager in Windows to kill the process. The next time cron.php is run, an error message will be displayed. To avoid this problem, either delete the cron temporary file shared/cron or use the +force option.
Ex: Start the cron execution and before it ends press Ctrl+C to terminate it. Then try to execute it again, and the following message will be displayed:
To be able to execute the cron.php file without errors, add the +force option.
cron.php Log Files
If needing to keep track of what actions have been taken by the cron.php script, check the file shared/log/cron.log which keeps a record of all its actions. Each line in the log file has the following format:
If the action is "executeEvents", then the log file will list both the starting time and the ending time.
If an error occurs in the cron.php script, the file shared/log/cronError.log will be created to record it:
For example, this error message indicates that the Email Settings in ProcessMaker haven't been configured.
If needing to figure out whether the cron.php script is currently running or the last time it was executed, check the serialized contents of the shared/cron file. If the value of bCronIsRunning is "1", then the script is currently running. If it is "0", then the script is not currently running.
Alternatively, open the file with a PHP script and unserialize it:
if (file_exists("/opt/processmaker/shared/cron")) {
$aCron = unserialize(file_get_contents("/opt/processmaker/shared/cron"));
if ($aCron['bCronIsRunning'] == 0) { // if cron.php is NOT currently running
... //do something
}
}
?>
Configuring crontab in Linux/UNIX
In Linux/UNIX, commands can be executed at scheduled times with the cron daemon. To configure cron to periodically execute ProcessMaker's cron.php file, login as the root user and edit the file /etc/crontab with your favorite plain text editor such as vim or gedit (or alternatively create the file /etc/cron.d/processmaker).
In the crontab file, the timing of commands is listed according to the format:
where:
| Field | Description |
|---|---|
| minute | The minute of the hour when the command is executed. Can be between 0 and 59. |
| hour | The hour when the command is executed. Can be between 0 and 23. 0 is midnight. |
| day-of-month | Day of the month when the command is executed. For example 20 would be the 20th day in each month. |
| month | Month when the command is executed. Can be a number between 1 and 12 or the first three letters of the month in English, such as jan, feb, etc. |
| day-of-week | Day of the week when the command is executed. Can be a number between 0 and 7, where 0 and 7 are both Sunday, 1 is Monday, 2 is Tuesday, etc. Alternatively, can be the first three letters of the day in English such as sun, mon, etc. |
| user | The username which will execute the command. |
| Command | Command, script or program to execute. |
An asterisk * in the first five columns indicates all possible values. For instance, an asterisk in the minutes column indicates all the minutes in the hour. If an asterisk is divided by a number "*/#", then it stands for any time unit which can be cleanly divided without any remainder. For instance in a day with 0-23 hours, "*/5" would execute on hours 0, 5, 10, 15 and 20.
For example to execute cron.php every 15 minutes from the command line:
In this example, the first column "*/15" means execute the command every 15 minutes.
For more information on how to configure the crontab, see this tutorial (or this tutorial in Spanish).
Scheduling a task in Windows
The cron.php script can be periodically executed as a Windows Scheduled Task. To configure its execution, either use the SCHTASKS command in DOS or create a Scheduled Task in the graphical interface.
SCHTASKS command
The SCHTASKS command is used to create, delete, query, change, run and end Windows Scheduled Tasks. Login to Windows as an administrator and open the system command prompt. Then, create a Scheduled Task to periodically execute the cron.php script:
Where number-minutes is how often the cron.php script will be executed in minutes and command is the command to execute the cron.php script. The command should be enclosed in double quotation marks. If it contains any paths or options which contain spaces, then they should be enclosed in single quotations marks or escaped double quotation marks. (Escaping of quotation marks is done with backslashes: \"). To continue a command onto the next line, use "^" as the last character in the line.
For example, to execute the cron.php script every 15 minutes for a ProcessMaker server installed at c:\Users\Bob\AppData\Roaming\ProcessMaker-2_5_2\:
For example to execute the cron.php script only on the "sales" workspace every 20 minutes for a ProcessMaker server installed at C:\Program Files\ProcessMaker-2_5_2\processmaker:
After scheduling the periodic execution of cron.php, verify that it is in the list of Scheduled Tasks:
For more information about the SCHTASKS command:
For more information about the options for /Create:
Scheduled Task in Windows XP
- On the server running ProcessMaker, open the Task Scheduler by going to Start > Programs > Accessories > System Tools > Scheduled Tasks
- Double-click Add Scheduled Task
- The Scheduled Task Wizard will appear. Click Next.
- Enter a command to execute cron.php.
For example:
Then click Next.
- Give the task a Name, such as "ProcessMaker Cron Job", and choose the Frequency with which to perform the task (for example, Daily)). Click Next.
- Choose specific date and time options (this step will vary, depending on the option selected in the previous step). When finished, click Next.
- Enter your password if prompted. Change the username if required (for example, you'd like the task to run under a user with fewer privileges security reasons). Click Next.
- On the final page, select the checkbox Open advanced properties for this task when I click Finish and click Finish.
Restart cron when it is stopped abruptly
When cron.php is executed, it checks to see whether another instance of cron.php is already running by checking whether a temporary cron file already exists. If for some reason cron is stopped abruptly, the temporary cron file needs to be manually deleted in order to be able to execute cron.php. If the temporary cron file exists, the following message will display when executing cron.php:
To solve this problem, delete the temporary file named shared/cron
Note: To avoid this issue, it is recommended to wait until cron finishes its execution or use the +force option.
Checking the Cron Log in ProcessMaker
From version 2.0.44 on, the contents of the cron log are available under the ADMIN menu. The cron log can be checked after cron is executed to see the results for a specific workspace or for all workspaces. Only users such as the "admin" who have the PM_SETUPADVANCE permission in their roles have access to the cron log.
After the cron is executed, the contents of the log can be viewed at ADMIN > Settings > Logs > Cron.
Cron log options
- Cron Status: Displays Active when cron is currently being executed. It displays Inactive when cron is not currently being executed.
- View information: Shows the cron information: Status, Last Execution and Log information which specifies the folder where the cron.log file is located.
- Clear log: Click to clear the log of all workspaces where the cron is executed or just a specific one. This log is deleted in the location /shared/log/cron.log.
Search Options
- Status: Search by cron status, Failed, Completed or all.
- From and To: both specify the days on which the cron was executed.
Menu options
- Date: date when the cron was executed.
- Action: name of the action that was executed.
- Status: Cron status.
- Description: a brief description of what was the execution cron about.
Note: In version 2.8.0 and later, the option "Workspaces" is excluded. By default, the list shows all actions of the current Workspace.
