3.0 - 3.1 - Upgrading ProcessMaker

Overview

This document is a guide to upgrade ProcessMaker. The structure of the databases and the file locations may be changed from one version of ProcessMaker to the next, so do NOT try to use data from one version of ProcessMaker in a different version of ProcessMaker, without first following the upgrade procedure.

The upgrade procedure will update the processes and data to the new version. However, take into account the following considerations once the upgrade is completed:

About old processes:

• Classic processes (created in the old designer in ProcessMaker 2) can be now used in version 3.0, but they will not be converted into BPMN processes. The only way to convert a classic process to a BPMN process is to manually recreate it in the new BPMN designer from scratch.
• After upgrading to version 3.0, classic processes will automatically be opened in the old designer and they will work as expected, meaning that information related to users and cases won't be modified.
• Classic processes that have been upgraded to version 3.0 can still be edited in the classic designer and cases can be executed. However, it is not possible to create new classic processes in version 3.0. Instead, all new processes will need to be created using the BPMN Designer.
• The case list will show both cases created by classic processes and new BPMN processes, respecting their numbering.

About old Dynaforms:

• Old Dynaforms cannot be converted into the new responsive forms. Instead, they will keep their old structure from the classic designer.

Requirements

See the requirements for ProcessMaker 3. Note that ProcessMaker version 3.0.1.7 or later requires PHP 5.4 or later. ProcessMaker version 3.0.1.8 and later requires PHP 5.5.33 or later, but this requirement can be relaxed. If using an older version of PHP, make sure to upgrade PHP before upgrading ProcessMaker.

Upgrading from a Community to an Enterprise Edition

This guide can also be used if planning to upgrade ProcessMaker from a Community to an Enterprise edition. Don't forget that a license is required in order to use the Enterprise Edition. For more information, see activating the Enterprise license.

Safety Precautions Before Upgrading

If using ProcessMaker in production, before upgrading ProcessMaker it is recommended to first install the new version of ProcessMaker on a separate test server (or in a separate port or domain on the same server) and import your processes onto the test server to verify that there are no incompatibilities.

Before upgrading, ALWAYS make a complete backup copy of the directory where ProcessMaker is installed and use mysqldump to make a complete backup of the database(s) used by each workspace. If an error arises, it will be possible to go back to the previous version of ProcessMaker and restore its data.

Warning: It is not very easy to restore a previous version of ProcessMaker with just a backup created with the processmaker workspace-backup command, so it is recommended to make full ProcessMaker backups using the method below.

Linux/UNIX:

Windows:

Restoring ProcessMaker if Problems Arise

If problems arise due to the upgrade, use the backup files to rollback to the previous version of ProcessMaker.

Linux/UNIX:

Windows:

Upgrading ProcessMaker

After making a backup copy of the existing installation of ProcessMaker, then the old version of ProcessMaker can be replaced with a new version. The upgrade procedure overwrites all existing source code, which is why ProcessMaker can't be upgraded from the graphical interface. Note that any custom changes made to the source code will be overwritten with each upgrade. After upgrading, use the processmaker upgrade script to update the database and file locations for the new version.

Upgrading the Source Code

After making a backup of the existing ProcessMaker installation, follow the steps below to install the new ProcessMaker source code, overwriting the old source code.

1. Go to ProcessMaker SourceForge page and download a processmaker-X_X_X.tar.gz file, which has a new version of the ProcessMaker source code.

Note: The blacklist.ini file (used by the Code Security Scanner) is autogenerated in the upgrade process. If a customized blacklist is currently being used, take care to backup the file before decompressing ProcessMaker.

2. Decompress the processmaker-X.X.X.X.tar.gz file, overwriting the existing processmaker directory and all its contents, which is generally found at:

   Linux/UNIX:
       /opt/processmaker

   Windows XP/Server 2003:
       C:\Program Files\ProcessMaker-X_X_X\processmaker

   Windows Vista/7/8/10/Server 2008/2012:
       C:\Users\USERNAME\AppData\Roaming\ProcessMaker-X_X_X\processmaker

   Warning: DO NOT delete the old processmaker directory and then copy the new processmaker directory into the same place, because all the essential configuration information and all the uploaded input documents and attached files from the old installation will be lost. Instead, decompress the file so it will overwrite any existing files but won't effect any other files (such as the contents of the shared and workflow/engine/config directories and the workflow/engine/test/bootstrap/gulliverConstants.php file).

Linux/UNIX:

1. Login as the "root" user (or use the sudo command). Then, use the tar command to overwrite the existing installation of ProcessMaker. Use the --overwrite option to replace the existing files and the -p option to preserve the permissions of existing files. Use the -C option to specify the parent directory where the processmaker directory is located.

   For example, to upgrade an installation of ProcessMaker located at /opt/processmaker with the file /root/processmaker-3.0.1.7.tar.gz:

   tar --overwrite -p -C /opt -xvzf /root/processmaker-3.0.1.7.tar.gz

   Note: If the ProcessMaker directory isn't named "processmaker", then temporarily rename it as "processmaker" so it will be correctly overwritten when the tar.gz file is decompressed. Then rename it back to its original name.

   For example, if ProcessMaker is installed at /usr/local/bin/pm, then rename it to /usr/local/bin/processmaker before overwriting the code files.

   mv /usr/local/bin/pm /usr/local/bin/processmaker
   tar --overwrite -p -C /usr/local/bin -xvzf /root/processmaker-3.0.1.7.tar.gz
   mv /usr/local/bin/processmaker /usr/local/bin/pm

2. Then, issue the following commands so that ProcessMaker can access the necessary files when run by the Apache server:

   cd /opt/processmaker
   chmod -R 770 shared workflow/public_html gulliver/js gulliver/thirdparty/html2ps_pdf/cache
   cd workflow/engine/
   chmod -R 770 config content/languages plugins xmlform js/labels

3. Finally, change the owner of the ProcessMaker files to the user who runs Apache. This user depends upon your distribution:

   Debian/Ubuntu:

   chown -R www-data:www-data /opt/processmaker

   RedHat/CentOS/Fedora:

   chown -R apache:apache /opt/processmaker

   SUSE/OpenSUSE:

   chown -R wwwrun:www /opt/processmaker

Windows:

Use a decompression program like WinRAR, which supports the tar.gz format, to decompress the source code and overwrite the existing processmaker directory, which by default is located at c:\Program Files\ProcessMaker-X_X_X\processmaker in Windows XP/Server 2003 or c:\Users\USERNAME\AppData\Roaming\ProcessMaker-X_X_X\processmaker in Windows Vista/7/8/10/Server 2008/2012.

Upgrading with Winrar

Upgrade ProcessMaker with Winrar by right-clicking on the processmaker-X.X.X.tar.gz file that was downloaded and selecting the option Extract here from the dropdown menu.

In the window prompt, select the Yes to All option to overwrite files and begin the extraction.

Modifying my.cnf file

binlog_format in MySQL 5.5.x or Greater

To avoid problems running triggers on MySQL 5.5 or greater, it should log by rows instead of by statements (which is the default).

Edit the MySQL configuration file, which is named my.cnf in Linux/UNIX and my.ini in Windows. Its location depends on the operating system.

Make sure that the following line appears in the MySQL configuration file:

binlog_format=row

For more information, see the MySQL documentation.

Upgrading the ProcessMaker Databases

After upgrading the ProcessMaker source code, then use the processmaker upgrade command to upgrade the three databases used by each ProcessMaker workspace. The databases have to be upgraded because the table structure may have been modified in the new version.

Go to the ProcessMaker installation directory and run the processmaker upgrade command from the command line.
Linux/UNIX:

Windows:

Changing the Apache Configuration

ProcessMaker 2.8.0 and later has a different VirtualHost configuration in Apache than in version 2.5.X and earlier. If upgrading to ProcessMaker 2.8.0 and later, it is necessary to change the rewrite rule in the VirtualHost configuration for ProcessMaker.

To change the rewrite rule, edit the pmos.conf file where the ProcessMaker VirtualHost is defined. Its location depends on your operating system:

Open the pmos.conf file with a plain text editor and make sure the configuration is set as the following examples, depending on the Apache Version.

VirtualHost in Apache 2.2

If using Apache 2.2, then use the following VirtualHost configuration in the pmos.conf file. Replace your_ip_address and your_processmaker_domain with the IP address and domain name used by your ProcessMaker server:

# Please change the IP address with your server IP address and # the ServerName with your own subdomains. NameVirtualHost your_ip_address #processmaker virtual host <VirtualHost your_ip_address > ServerName "your_processmaker_domain" DocumentRoot /opt/processmaker/workflow/public_html <Directory /opt/processmaker/public_html/workflow> AddDefaultCharset UTF-8 AllowOverRide All Options FollowSymlinks Order allow,deny Allow from all RewriteEngine On RewriteCond %{REQUEST_FILENAME} !-f RewriteRule ^(.*)$ /app.php [QSA,L] ExpiresActive On ExpiresDefault "access plus 1 day" ExpiresByType image/gif "access plus 1 day" ExpiresByType image/png "access plus 1 day" ExpiresByType image/jpg "access plus 1 day" ExpiresByType text/css "access plus 1 day" ExpiresByType text/javascript "access plus 1 day" #Deflate filter is optional. It reduces download size, but adds slightly more CPU processing: AddOutputFilterByType DEFLATE text/html </Directory> </VirtualHost>

VirtualHost in Apache 2.4

If using Apache 2.4, then use the following VirtualHost configuration in the pmos.conf file. Replace your_ip_address and your_processmaker_domain with the IP address or domain name used by your ProcessMaker server:

#processmaker virtual host <VirtualHost your_ip_address > ServerName "your_processmaker_domain" DocumentRoot /opt/processmaker/workflow/public_html DirectoryIndex index.html index.php <Directory /opt/processmaker/public_html/workflow> Options Indexes FollowSymLinks MultiViews AddDefaultCharset UTF-8 AllowOverride All Require all granted ExpiresActive On <IfModule mod_rewrite.c> RewriteEngine On RewriteCond %{REQUEST_FILENAME} !-f RewriteRule ^.*/(.*)$ app.php [QSA,L,NC] </IfModule> #Deflate filter is optional. It reduces download size, but adds slightly more CPU processing: AddOutputFilterByType DEFLATE text/html </Directory> </VirtualHost>

Then restart the Apache web server for the changes to take effect.

If this change in the rewrite rule is not made, it will no longer be possible to access ProcessMaker in a web browser. Either the ProcessMaker login screen will not load or the following error will appear:

Upgrade the Databases

Note: In case of restoring a workspace backup from a different server, make sure the /shared/sites/<WORKSPACE>/db.php file content is properly defined to work in the new workspace server.

After upgrading the ProcessMaker source code, the MySQL database(s) used by ProcessMaker need to be upgraded as well. After changing to the ProcessMaker installation directory, run the processmaker database-upgrade command from the command line.

Linux/UNIX:

Windows XP/Server 2003:

Windows Vista/7/8/10/Server 2008/2012:

The unifying process may take several minutes (or hours) depending on the amount of information on the databases. It takes more time if there is a great amount of cases, users, plugins, and other additional information. A message will be shown after the unification is complete indicating that it was successful.

It is recommended to run the processmaker flush-cache command after the unification of the databases.

Migrating the List of Cases

ProcessMaker 3 Enterprise Edition has improved its performance since older versions by organizing the list of cases according to their status into different tables in the database. To move these cases to their corresponding tables, execute the processmaker migrate-new-cases-lists command. Then, execute the processmaker database-generate-self-service-by-value command to move the unassigned cases to a separate table in the database.

Note: This command will ONLY be used if you are migrating from a version 2.x and NOT from the versions 2.8, 2.5.2.4 to versions 3.0.x, 3.1.x or 3.2.x. It is not recommended to use this command for other versions as the data is already migrated and for version 3.3.x is deprecated.

LINUX/UNIX:

Windows XP/Server 2003:

Windows Vista/7/8/10/Server 2008/2012:

Some Additional Configurations

Case Number for New Cases is Incorrect

ProcessMaker 3 has improved the speed of generating new cases by storing the last case number in the wf_WORKSPACE.APP_SEQUENCE.ID field in the database. However, this field did not exist in ProcessMaker 2. If upgrading from version 2 to 3, then the case number of the last case needs to be inserted into this field. If using ProcessMaker Enterprise Edition, then use the processmaker migrate-new-cases-lists command above to automatically insert the last case number into this field.

If using ProcessMaker Community Edition, then the last case number will have to be manually inserted in MySQL. First, login as the root user in MySQL:

Windows:

Linux/UNIX:

Then, change to the wf_WORKSPACE database, which is named wf_workflow by default:

mysql> use wf_workflow

Then, insert the last case number into the APP_SEQUENCE.ID field:

mysql> UPDATE APP_SEQUENCE SET ID=(SELECT MAX(APP_NUMBER) FROM APPLICATION); Query OK, 0 rows affected (0.00 sec) Rows matched: 1 Changed: 0 Warnings: 0

Finally, exit MySQL:

mysql> exit bye

Enabling the fileinfo Extension

The fileinfo extension in PHP must be enabled in order to upload files as input documents. In the definition of input documents, it is now possible to specify which types of files may be uploaded in the Allowed File Extensions field. Fileinfo is used to check the file extension and content of files before adding them as input document files.

The fileinfo extension is included by default in PHP 5.3.0 and later. To check whether it is enabled, issue the following command from the command line:

php -m

In Windows, it is necessary to specify the path where the php.exe file is located. For example:

If fileinfo doesn't appear in the list, then it needs to be enabled by editing the php.ini file.

Linux/UNIX:

Windows:

Enabling the mcrpyt Extension

The Enterprise Edition for ProcessMaker 2.8 and later needs to have the mcrypt extension enabled in PHP.

Linux/UNIX:

It is recommended to install the mcrypt module using the package from your Linux/UNIX distribution:

Red Hat/CentOS/Fedora:

Debian/Ubuntu/Mint:

SuSE/OpenSUSE:

Windows:

Use a plain text editor (such as notepad, Notepad++ or the DOS edit command) to edit the php.ini file, which by default is located at:

In the php.ini file, uncomment the following line by changing it from:

;extension=php_mcrypt.dll

To:

extension=php_mcrypt.dll

Then restart the Apache server for the mycrypt extension to be enabled.