Upgrade Standard Procedure to ProcessMaker 3.8.x

Overview

According to the Upgrade Road Map, this document explains the standard procedure to upgrade to ProcessMaker versions 3.8.x from the following ProcessMaker versions:

• 3.2.2 or 3.2.3
• 3.3.x
• 3.4.x
• 3.5.x
• 3.6.x
• 3.7.x Minor Release
• 3.8.x Point Release

Refer to the following sections to upgrade from ProcessMaker versions 3.2.2, 3.2.3, 3.3.x, 3.4.x, 3.5.x, 3.6.x or 3.7.x to ProcessMaker 3.8.x:

• Recommendations to Upgrade to ProcessMaker 3.8.x
• Steps to Upgrade to ProcessMaker 3.8.x

Recommendations to Upgrade to ProcessMaker 3.8.x

To upgrade from ProcessMaker 3.2.2, 3.2.3, 3.3.x, 3.4.x, 3.5.x, 3.6.x, or 3.7.x to the latest ProcessMaker 3.8.x in point release in either Linux or Windows platforms, take into account the following considerations:

• A ProcessMaker Point Release means an upgrade from one version to another one in the ProcessMaker 3.8.x range.
• Due to PHP 8.1.x code changes, the custom ProcessMaker plugins and custom code in ProcessMaker Triggers requires to be validated before the upgrade.
• ProcessMaker upgrade makes changes in the source code. ProcessMaker services and tasks must be stopped, so this action should be planned and done when ProcessMaker is not being used.
• JOBS_PENDING and JOBS_FAILED tables must not contain any task. To clean all pending tasks in these tables, use this guide.

• Before upgrading, update values in the CONTENT table only if upgrading from a ProcessMaker 3.2.x version to a Point Release such as from ProcessMaker 3.2.3 to ProcessMaker 3.8.x. Follow the next steps to update values in the CONTENT table:

• After upgrading, add the Clean web-entries option in the Task Scheduler table. For this, use the correct path and workspace as follows: INSERT INTO `SCHEDULER` (`title`, `startingTime`, `endingTime`, `everyOn`, `interval`, `description`, `expression`, `body`, `type`, `category`, `system`, `timezone`, `enable`, `creation_date`, `last_update`, `default_value`) VALUES('ID_CLEAN_WEBENTRIES', NULL, NULL, '1', 'week', 'ID_CLEAN_WEBENTRIES_DESC', '0 20 * * 5', 'su -s /bin/sh -c \"php /opt/processmaker/workflow/engine/bin/webentriescron.php +wworkflow +force +async\"', 'shell', 'case_actions', 1, NULL, 0, NOW(), NOW(), '{\"startingTime\":null,\"endingTime\":null,\"everyOn\":\"1\",\"interval\":\"week\",\"expression\":\"0 20 * * 5\",\"timezone\":null}');

Steps to Upgrade to ProcessMaker 3.8.x

Steps to upgrade from ProcessMaker 3.2.2, 3.2.3, 3.3.x, 3.4.x, 3.5.x, 3.6.x, 3.7.x or 3.8.x to the latest ProcessMaker 3.8.x point release based on these supported operating systems:

• Linux
• Windows

Linux

Follow these steps to upgrade to ProcessMaker 3.8.x in Linux platforms, which involves the Apache and NGINX web servers:

1. In the terminal, log on as root or with the root privileges:

   su or: sudo su -

2. To overwrite the correct libraries if upgrading to PHP 8.1.x, remove all libraries from the folders /opt/processmaker/vendor/ and /opt/processmaker/thirdparty/.

3. Copy the processmaker-3.8.x.tar.gz file to the /opt directory:

   cp processmaker-3.8.x.tar.gz /opt/

4. Overwrite any existing files in the /opt directory:

   cd /opt tar -xzvf processmaker-3.8.x.tar.gz

   Note: For ProcessMaker 3.8.1, after overwriting files, restart PHP-FPM by running in the console service php-fpm restart.

5. Configure the permissions for the processmaker directory:

   chmod -R 770 processmaker/

6. Give permission to access the following files in the /processmaker directory:

   cd processmaker chmod -R 775 bootstrap bootstrap/cache config/ framework/

7. To avoid problems with old updated libraries if upgrading to PHP 8.1.x, clear the cache before you run the ProcessMaker upgrade.

   cd /opt/processmaker php artisan cache:clear

8. Depending on the supported stacks, set the Apache or NGINX user as the owner of the files within the processmaker directory:

   chown -R apache:apache processmaker

   or nginx:

   chown -R nginx:nginx processmaker

9. Upgrade ProcessMaker files, the ProcessMaker database, and the translation files as described at ProcessMaker Command:

   ./processmaker upgrade [workspace]

   Warning: In case of a Point Release upgrade, to avoid downtime, DO NOT use this command if the ProcessMaker version to upgrade does not contain database upgrades. Review our current Release Notes in the front page (previous versions are in the same document) to know if the ProcessMaker version has changes in its database.

10. To update the PM_DELETECASE permission, run the following MySQL query:

    UPDATE RBAC_PERMISSIONS SET PER_STATUS = 1 WHERE PER_UID = '00000000000000000000000000000013';

11. To update the PM_FOLDERS_ALL permission, run the following MySQL query:

    UPDATE RBAC_PERMISSIONS SET PER_CODE = 'PM_FOLDERS_ALL' WHERE PER_UID = '00000000000000000000000000000015';

12. In a ProcessMaker point release, consider the following:

    Note: After every command execution, verify if there are error or warning messages. This may be due to wrong file permissions.

    • Check if ProcessMaker files have the correct owner and permissions.
    • Enable the Supervisor service with these commands:
    $ sudo supervisorctl reread
    $ sudo supervisorctl update
    $ sudo supervisorctl stop all
    $ sudo supervisorctl start all
    $ sudo supervisorctl status all

    Note: To stop properly running threads, additional to stopping the Supervisor service, find and kill duplicated processes with the following command:

    for i in `ps aux|grep artisan|awk '{print $2}'`; do kill $i; done;
    • Restart the Supervisor service:
    $ sudo systemctl stop supervisord.service
    $ sudo systemctl start supervisord.service
    $ sudo systemctl status supervisord.service

13. Depending on the supported stacks, set the ProcessMaker Task Scheduler.

Windows

Follow these steps to upgrade to ProcessMaker 3.8.x in Windows platforms:

1. Copy the processmaker-3.8.x.tar.gz file to the C:\opt directory.

2. Use a program like WinRAR or 7-Zip to extract processmaker-3.8.x.tar.gz to the C:\opt directory.

3. Start the command prompt as the administrator, and then issue the commands in the next steps.

4. Go to the C:\opt\processmaker directory:

   cd C:\opt\processmaker

5. To overwrite the correct libraries if upgrading to PHP 8.1.x, remove all libraries from the folders C:\opt\processmaker\vendor/ and C:\opt\processmaker\thirdparty/.

6. To avoid problems with old updated libraries if upgrading to PHP 8.1.x, clear the cache before you run the ProcessMaker upgrade.

   php artisan cache:clear

7. Upgrade ProcessMaker files, the ProcessMaker database, and the translation files as described at ProcessMaker Command:

   php -f processmaker upgrade [workspace]

   Warning: In case of a Point Release upgrade, to avoid downtime, DO NOT use this command if the ProcessMaker version to upgrade does not contain database upgrades. Review our current Release Notes in the front page (previous versions are in the same document) to know if the ProcessMaker version has changes in its database.

   Note: For ProcessMaker 3.8.1, after overwriting files, restart PHP-FPM by running in the console service php-fpm restart.

8. To update the PM_DELETECASE permission, run the following MySQL query:

   UPDATE RBAC_PERMISSIONS SET PER_STATUS = 1 WHERE PER_UID = '00000000000000000000000000000013';

9. To update the PM_FOLDERS_ALL permission, run the following MySQL query:

   UPDATE RBAC_PERMISSIONS SET PER_CODE = 'PM_FOLDERS_ALL' WHERE PER_UID = '00000000000000000000000000000015';

10. In a ProcessMaker point release, consider the following:

    • Check if ProcessMaker files have the correct owner and permissions.

    • The Supervisor service must be configured as a Windows service. Use the NSSM software.

      

    • Stop and restart the service from the local Windows Services in the Control Panel.

      

11. Depending on the supported stacks, set the ProcessMaker Task Scheduler.