3.2 - 3.8 - Executing Cron Scripts

Overview

ProcessMaker is a web application that normally executes actions in response to users' actions. Nonetheless, actions that aren't initiated by the user, such as timer events and sending email notifications, are only executed when the following cron scripts are run:

• cron.php: This is the principal cron script, which:
  • Sends out any emails in the notification queue,
  • Unpauses any case whose pause time has expired,
  • Calculates the elapsed time (according to the configured calendar) of all open tasks in active cases,
  • Executes any events for classic (ProcessMaker 2) processes,
  • Starts any scheduled cases for classic (ProcessMaker 2) processes,
  • Updates the labels in active cases,
  • Executes the trigger for self service cases that have a configured timeout setting,
  • Calculates the behavior of the users,
  • Calculates the behavior of a process.
• messageeventcron.php: This script executes the send and receive message events and the email intermediate throwing and email end events in BPMN processes.
• timereventcron.php: This script executes timer start and intermediate timer events in BPMN processes.
• ldapcron.php: This script executes LDAP and Active Directory synchronization, which is an option available in Advanced LDAP/AD in the Enterprise Edition.
• sendnotificationscron.php: This script sends notifications, including to mobile devices, when cases are created and when cases are routed to new tasks.
• actionsByEmailEmailResponse.php: This script reads the Action by Email receiver account inbox looking for new messages. Available Version: As of ProcessMaker 3.4.0.

For testing purposes, these cron scripts 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 the cron scripts 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 these scripts more than once every five minutes due to the heavy processing that they incur.

Setting Time Zone

In order for the cron scripts to execute correctly, it is recommended that the same time zone be set in both the servers' php.ini file and in ProcessMaker's env.ini file.

For example, a ProcessMaker server located in New York should have the following line in its workflow/engine/config/env.ini file: time_zone = "America/New_York"

Likewise, its php.ini file should contain the following line: date.timezone = America/New_York Restart Apache or reboot the server for any changes in the php.ini file to take effect.

It is also recommended to set the server's clock to use same time zone in Linux or Windows.

Manually Executing Cron Scripts

Windows

The cron scripts can be 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 installs PHP-CLI, but it may not have been installed if ProcessMaker was manually installed.

It is recommended to add the location of the php.exe file to the system's Path variable, so that PHP can executed without specifying the full path.

Right click on My PC (or This PC) in the Windows File Explorer and select Properties from the context menu.

In the "System Properties" dialog box that opens, go to the Advanced tab and click on the Environment Variables button. Under the "System Variables" section of the next dialog box, click on the Path variable in the list to select it, and then click on Edit.

Then, add the directory where php.exe is located to the end of the existing paths, such as C:\Bitnami\processmaker-3.X.X-X\php\ for a Bitnami install or C:\php\ for a manual install. Then save the changes.

To test a feature executed by a cron script, open a terminal by going to Start > All Programs > Accessories > Command Prompt on the server where ProcessMaker is installed. Enter the command to execute the workflow/engine/bin/cron.php file. The location of the file depends on the ProcessMaker installer that was used. For example:

messageeventcron.php, timereventcron.php, ldapcron.php and sendnotificationscron.php are files that are found in the same directory and are executed in the same way as the cron.php file.

If the cron script is executed without being configured, all pending activities will be automatically executed for all workspaces. To limit processing in the cron.php script, 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. Read about the cron script options in the Syntax of Cron Options section.

Linux

In ProcessMaker version 3.1.3 and later, the ProcessMaker cron scripts in Linux must be executed by the Apache or Nginx user to avoid file permission problems with ProcessMaker's new logging feature. The Apache or Nginx user varies according to the distribution of Linux/UNIX.

If unsure of which user to use with your distribution, find out who the owner of the ProcessMaker files in the shared directory is with the ls -l command. For example if ProcessMaker is installed in the /opt folder, run the following command and read the name of the owner (marked in green):

The location of the cron scripts depends on the installer that was used to install ProcessMaker.

The Apache/Nginx user doesn't have configuration files, so it not possible to log in as this user. To manually execute a cron script in Linux as the Apache/Nginx user, the path to the shell must be specified. First, change to the root user using su or sudo su -, then execute the cron script:

For example, to manually execute the cron.php file:

Where apache is the name of the Apache or Nginx user and /opt is the ProcessMaker installation directory.

Note: If an error appears such as: The stream or file "/opt/processmaker/shared/sites/workflow/log/processmaker-2018-03-05.log" could not be opened: chmod(): Operation not permitted Then, the owner of the files in the /opt/processmaker/shared directory need to be changed to the Apache or Nginx user: su   or   sudo su chown -R apache:apache /opt/processmaker/shared Where apache:apache is apache:apache or nginx:nginx in Red Hat/Cent OS, www-data:www-data in Debian/Ubuntu, wwwrun:www or nginx:nginx in SUSE/OpenSUSE, or daemon:daemon for a Bitnami install in all distributions.

messageeventcron.php, timereventcron.php, ldapcron.php and sendnotificationscron.php are files that are found in the same directory and are executed in the same way as the cron.php file.

If the cron script is executed without being configured, all pending activities will be automatically executed for all workspaces. To limit processing in the cron.php script, 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. Read about the cron script options in the Syntax of Cron Options section.

Syntax of Cron Options

Options:

• ACTIVITIES define which activities should be executed by the cron.php script:
  • 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 any pending plugins.
  • calculate : Calculate the elapsed time (according to the configured calendar) of all open tasks in active cases.
  • calculateapp : Calculate the app data of all cases in all processes.
  • unassigned-case : Run the trigger for self service cases that have a configured timeout setting.
  • clean-self-service-tables : Available Version: As of ProcessMaker 3.3.9.
    Clean unused records for Self-Service Value Based feature. It is a maintenance command.
  • report_by_user : Calculate the behavior of the users.
  • report_by_process : Calculate the behavior of a process.

  Multiple activities can be specified by separating each one with spaces:
  Ex: cron.php events emails plugins

  Note: The activities should be listed before the other options. For example: cron.php emails calculate +d"2015-01-01 01:00:00" +force

• +d"YYYY-MM-DD HH:MM:SS" Specify an alternative date and time for the script.
  By default, the script will execute using the server's current system time. It 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"2016-03-30 10:30:59"
  If manually executing the cron.php script on a Linux server, then the whole command will be enclosed in double quotation marks and the date in single quotation marks.
  Ex: su -s /bin/sh apache -c "php ./cron.php +d'2018-12-01 01:00:00' +force"
  If the date is not specified, then any pending emails from the last 7 days will be sent. The date can be specified to send out pending emails from an earlier date. For example, the following command sends out all pending emails which were scheduled to be sent since January 8, 2015:
  Ex: cron.php emails +d"2015-01-08 00:00:00"
• +w Specify 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 and the default workspace is named workflow.
  

  It is possible to use the workspace +w configuration in timereventcron, messageeventcron and sendnotificationscron, as is shown in the following examples:

  - cron.php +wworkflow - timereventcron.php +wworkflow +force - messageeventcron.php +wworkflow +force - sendnotificationscron.php +wworkflow +force
• +force This option ensures that the cron script is executed by stopping the execution of any existing cron script and deleting its temporary files, so the current cron script can be executed. Remember that only one instance of a cron script can be executed at a time, so without the +force option, the cron script will not be executed if another instance is already being executed.

When a cron script executes, it will report which activities were executed and how many workspaces were processed:

Cancelling the Cron Script Execution

To cancel the execution of a cron script, 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 a cron script 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.

Example:
Start executing a cron script 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 script without errors, add the +force option.

Cron Log Files

To keep track of what actions have been taken by a cron script, check the file shared/log/cron.log, which keeps a record of all the cron 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 a cron script, the file shared/log/cronError.log will be created if it doesn't already exist and it will contain a line like the following:

For example, this error message indicates that the email settings in ProcessMaker haven't been configured.

Checking if a Cron Script is Running

To figure out whether a cron script is currently running or the last time it was executed, check the serialized contents of the /opt/processmaker/shared/cron file. If the value of flagIsRunning 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:

Executing timereventcron.php

When the timeeventcron.php script is executed, it will print out which timer events were executed.

For example, in a manual installation in Linux:

Where apache is the Apache or Nginx user or daemon if a Bitnami installation.

Note: Bitnami is no longer used in ProcessMaker as of version 3.4.0.

For example, in a Bitnami installation in Windows:

In this example, the timereventcron.php script finds one start timer event to initiate a new case and routes it to the second task in the process. It doesn't find any intermediate timer events to execute.

Note: The (UTC + 00:00) does not represent the time of the cronjob when the trigger will be executed, but is only a referential time zone for internal calculation.

In addition, the following lines will be added to the shared/log/cron file: 2016-03-31 19:17:39 | | main | action | checking folder /opt/processmaker/shared/sites/workflow 2016-03-31 19:17:39 |workflow||timereventcron|timereventcron|START-NEW-CASES|Date "2016-03-31 19:17:39": Start new cases 2016-03-31 19:17:42 |workflow||timereventcron|timereventcron|CREATED-NEW-CASE|Case #254 created, APP_UID: 47973318956fdb013b2c178000124391, PRO_UID: 96010725556eb05fd893a42072130232 2016-03-31 19:17:45 |workflow||timereventcron|timereventcron|ROUTED-NEW-CASE|Case #254 routed, APP_UID: 47973318956fdb013b2c178000124391, PRO_UID: 96010725556eb05fd893a42072130232 2016-03-31 19:17:45 |workflow||timereventcron|timereventcron|END-NEW-CASES|Date "2016-03-31 19:17:39": End new cases 2016-03-31 19:17:45 |workflow||timereventcron|timereventcron|START-CONTINUE-CASES|Date "2016-03-31 19:17:39": Start continue the cases 2016-03-31 19:17:45 |workflow||timereventcron|timereventcron|NO-RECORDS|No existing records to continue a case 2016-03-31 19:17:45 |workflow||timereventcron|timereventcron|END-CONTINUE-CASES|Date "2016-03-31 19:17:39": End continue the cases

Executing sendnotificationscron.php

The sendnotificationscron.php script sends notifications to the mobile device when cases are created and when cases are routed to new tasks.

Information about the notifications is stored in the wf_<workspace>.NOTIFICATION_QUEUE table.

The NOT_STATUS column details the notification status: "Pending", "Sending" or "Sent".

Note that notifications will be recorded only if the mobileNotifications flag is set to True in the env.ini configuration file. Otherwise, no notification will be stored in the table or sent to the mobile device.

To send the notifications execute the following command:

For example, in a manual installation in Linux:

Where apache is the Apache or Nignx user or daemon if a Bitnami installation.

Note: Bitnami is no longer used in ProcessMaker as of version 3.4.0.

For example, in a Bitnami installation in Windows:

Notifications will be sent first to Android devices and then to iOS devices.

Configuring Crontab in Linux/UNIX

The crontab command can be used to configure the server to periodically execute the ProcessMaker cron scripts at scheduled times as the Apache/NGINX user. This command should be used instead of editing the /etc/crontab file or a file in the /etc/cron.d directory (and the /etc/cron.hourly, /etc/cron.daily, /etc/cron.weekly and /etc/cron.monthly directories in Debian).

To set up the cron scheduler on the server where ProcessMaker is installed, issue the following command (as the root or using sudo):

Change web-server-user to the name of the Apache or NGINX user in your Linux distribution which is usually apache or ngnix in Red Hat/CentOS, www-data in Debian/Ubuntu, wwwrun or nginx in SUSE/OpenSUSE, or daemon if using a Bitnami installation in any Linux distribution.

Note: Bitnami is no longer used in ProcessMaker as of version 3.4.0.

The cron file is opened in the default editor of your Linux distribution. Then, add lines to execute the different ProcessMaker cron scripts at different times in the following format:

Where:

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 that 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.

The following example executes cron.php every 15 minutes and messageeventcron.php every 20 minutes of every even hour in an installation of ProcessMaker Community Edition:

Replace web-server-user with apache or nginx in Red Hat/CentOS, www-data in Debian/Ubuntu, wwwrun or nginx in SUSE/OpenSUSE, or daemon if using a Bitnami installation in any Linux distribution. (Using NGINX to run ProcessMaker is an option available in version 3.2.2 and later).

In this example, */15 in the first line means execute cron.php at 0, 15, 30, 45 minutes of every hour. Likewise, */20 */2 in the second line means execute messageeventcron.php at the minutes 0, 20 and 40 of the hours 0, 2, 4, 6, 8, 10, 12, 14, 16, 18, 20 and 22.

To execute all the cron scripts, it is recommended to vary the time when they execute so that each script has time to finish processing before the next script starts. In this example, each of the cron scripts are executed twice each hour, but the cron.php script is given 10 minutes to finish processing before starting the next script, whereas the rest of the cron scripts are given 5 minutes to finish processing.

In a Bitnami installation, the path needs to be adjusted to use the Bitnami installation of PHP:

When done editing the cron file, the contents will be stored in the location /var/spool/cron/crontabs/user, such as /var/spool/cron/crontabs/apache in Red Hat/CentOS or /var/spool/cron/crontabs/www-data in Debian. If the cron daemon is running on the server, then the ProcessMaker cron scripts should be periodically executed at the scheduled times.

Remember to add the +force option to ensure that a cron script will be processed at a specified time. This option will cut the processing of an existing cron script short, so it is better to space out the cron scripts so they don't overlap. The cron.php script can take a long time to process if there are a large number of active cases or a large number of workspaces to process. The ldapcron.php script can also be slow if synchronizing thousands of LDAP/AD users. For a large scale deployment, it is recommended to test the cron scripts from the command line to see how long it takes to execute each one.

For example, if using a large scale deployment with thousands of active cases, it might be better to plan 20 minutes to process the cron.php script. Likewise, it might be better to only run the ldapcron.php script at midnight to synchronize the accounts of thousands of LDAP/Active Directory users.

For more information on how to configure the crontab, see this tutorial (or this tutorial in Spanish).

Scheduling a Task in Windows

The cron scripts 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. Log in to Windows as an administrator and open the system command prompt. Then, create a scheduled task to periodically execute the cron script:

Where:

• ScheduleType: Is how often the cron script will be executed. The available options are:

  Schedule type	Description
  MINUTE, HOURLY, DAILY, WEEKLY, MONTHLY	Specifies the time unit for the schedule.
  ONCE	The task runs once at a specified date and time.
  ONSTART	The task runs every time the system starts. You can specify a start date, or run the task the next time the system starts.
  ONLOGON	The task runs whenever a user (any user) logs on. You can specify a date, or run the task the next time the user logs on.
  ONIDLE	The task runs whenever the system is idle for a specified period of time. You can specify a date, or run the task the next time the system is idle.

• TaskName: The name of the task. The task name should be enclosed in double quotations.
• Command: The command to execute the cron script. The command should be enclosed in double quotation marks. If it contains any paths or options that contain spaces, then they should be enclosed in single quotations marks or escaped double quotation marks. Escaping of quotation marks is done with backslashes: \".

For example, to execute the cron.php script every hour starting at 11:25 for a ProcessMaker server installed with WampServer at c:\opt\ProcessMaker\:

Or to execute the cron.php script only on the "sales" workspace every 2 minutes:

After scheduling the periodic execution of cron.php, verify that it is in the list of Scheduled Tasks with the SCHTASKS command.

To delete a task command, use the SCHTASKS /Delete TaskName command.

For more information about the SCHTASKS command, run the following:

Scheduled Task in Windows 7

On the server running ProcessMaker, open the Task Scheduler by going to Start > Programs > Accessories > System Tools > Task Scheduler and select the "Create Basic Task" option.

The Scheduled Task Wizard will appear. Give the task a name, such as "ProcessMaker Cron Job" and click Next.

Choose the frequency with which to perform the task. For this example, the task will be executed one unique time, so select One Time and click Next.

Choose specific date and time options (this step will vary, depending on the option selected in the previous step).

Select the Start a program option and click Next.

On the next window, enter a command to execute cron.php.

For example:

In the next window, confirm the command by clicking on Yes.

Finally, review the information of the summary, and click on Finish.

Restart Cron When it is Stopped Abruptly

When a cron script is executed, it checks to see whether another instance of the cron script 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 the cron script. If the temporary cron file exists, the following message will display when executing the cron script:

To solve this problem, delete the temporary file named shared/cron

Note: To avoid this issue, it is recommended to wait until the cron script finishes its execution, or use the +force option.

Checking the Cron Log in ProcessMaker

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_SETUP_ADVANCE 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.

Location of the Cron Log File

When a cron script is executed, output from the script is stored in the shared/log/cron.log file on the ProcessMaker server. For example:

If a non-fatal error occurred while executing a cron script, it may be stored in the shared/log/cronError.log file. Some types of errors, however, will not be recorded in the log file, so it recommended to manually execute the cron scripts from the command line to check whether any error messages are printed out on screen if the cron scripts do not appear to be executing correctly.

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 following information about cron: 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: Specify the days when 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 the cron execution was about.