Please rate how useful you found this document: 
Average: 2.8 (4 votes)

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:

Use the tar command to make an archive of the ProcessMaker installation directory, which is usually located at /opt/processmaker:

tar -czf BACKUP-FILE.tar.gz /opt/processmaker

To make a backup copy of the entire MySQL database:

mysqldump -u root -p -F -x -A > BACKUP-FILE.sql

In ProcessMaker 2.5.X and earlier, each workspace has three databases. To back up the three databases used by a workspace, such as the default "workflow" workspace:

mysqldump -u root -p -F -x --databases wf_workflow rb_workflow rp_workflow > BACKUP-FILE.sql

In ProcessMaker 2.8 and later, each workspace uses a single database. To back up just the database used by a ProcessMaker 2.8+ workspace, such as the default "workflow" workspace:

mysqldump -u root -p -F -x --databases wf_workflow > BACKUP-FILE.sql

Note: Workspaces that have been upgraded from version 2.5.X or earlier to version 2.8.X or later will continue to use 3 databases per workspace. If using the Enterprise Edition, it is possible to unify the 3 databases into 1 database per workspace by using the processmaker unify-database command.

Note: If unsure what the MySQL databases are named, login to MySQL and use the SHOW DATABASES command to see the available databases.

# mysql -u root -p mysql> show databases; mysql> quit;

Windows:

Open a command prompt window by going to Start > All Programs > Accessories > Command Prompt and navigate to the directory where the mysqldump command is located:

Windows Vista/7/8/10/Server 2008/2012: cd c:\Users\USERNAME\AppData\Roaming\ProcessMaker-X_X_X_X\mysql\bin Windows XP/Server 2003: cd "c:\Program Files\ProcessMaker-X_X_X_X\mysql\bin"

Then, use the mysqldump command to backup the MySQL databases as shown above for Linux/UNIX.

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:

Login as "root" or the user with administrative powers and remove the ProcessMaker installation directory and replace it with the backup:

rm -fr /opt/processmaker tar -C /opt -xzf BACKUP-FILE.tar.gz

Then, restore the databases:

mysql -u root -p < BACKUP-FILE.sql

Windows:

Delete the current ProcessMaker installation directory, which by default is located at:

Windows XP/2003:

    c:\Program Files\ProcessMaker-X_X_X

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

    c:\Users\USERNAME\AppData\Roaming\ProcessMaker-X_X_X

Then, decompress the backup copy of the previous version of ProcessMaker in the same location.

Decompressing the backup copy should restore all the previous files, including the MySQL database, because all its files are located inside the same directory as the ProcessMaker code. However, if ProcessMaker was manually installed and uses a separate installation of MySQL, then open a command prompt window (by going to Start > All Programs > Accessories > Command Prompt as the administrator user) and navigate to the directory where the mysql command is located:

cd "c:\Program Files\ProcessMaker-X_X_X\mysql\bin" or: cd c:\Users\USERNAME\AppData\Roaming\ProcessMaker-X_X_X\mysql\bin

Then, restore the MySQL databases:

mysql -u root -p < BACKUP-FILE.sql

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

  3. 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:

Login as root (or use the sudo -i command), then:

cd /opt/processmaker
./processmaker upgrade

Note: If an error message appears, such as "/usr/bin/env: php: No such file or directory", then make sure that the PHP Command Line Interface is installed (whose package is named php-cli in Red Hat/CentOS/Fedora and php5-cli in Debian/Ubuntu). If PHP-CLI is already installed, then it is not installed in a location found in your $PATH, so use the full path when executing PHP-CLI:

cd /opt/processmaker
/usr/bin/php -f processmaker upgrade

Windows:

First, open a Command Prompt by going to Start > All Programs > Accessories > Command Prompt and navigate to the location where ProcessMaker installed. Then, run the processmaker upgrade command:

cd INSTALL-DIRECTORY\processmaker ..\php\php.exe -f processmaker upgrade

For example:

cd c:\Users\admin\AppData\Roaming\ProcessMaker-3_0_1_7\processmaker
..\php\php.exe -f processmaker upgrade

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:

Red Hat/CentOS/Fedora:
    /etc/httpd/conf.d/pmos.conf

Debian/Ubuntu/Mint:
    /etc/apache2/sites-available/pmos.conf

SuSE/OpenSUSE:
    /etc/apache2/conf.d/pmos.conf

Windows XP/Server 2003:
    c:\Program Files\ProcessMaker-X_X_X\apache\conf\pmos.conf

Windows Vista/7/8/10/Server 2008/2012:
    c:\Users\USERNAME\AppData\Roaming\ProcessMaker-X_X_X\apache\conf\pmos.conf

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:

cd /opt/processmaker ./processmaker database-upgrade

Windows XP/Server 2003:

cd "c:\Program Files\ProcessMaker-X_X_X\processmaker" ..\php\php.exe -f processmaker database-upgrade

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

cd "c:\Users\USERNAME\AppData\Roaming\ProcessMaker-X_X_X\processmaker" ..\php\php.exe -f processmaker database-upgrade

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:

cd /opt/processmaker ./processmaker migrate-new-cases-lists ./processmaker database-generate-self-service-by-value

Windows XP/Server 2003:

cd "c:\Program Files\ProcessMaker-X_X_X\processmaker" ..\php\php.exe -f processmaker migrate-new-cases-lists ..\php\php.exe -f processmaker database-generate-self-service-by-value

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

cd "c:\Users\USERNAME\AppData\Roaming\ProcessMaker-X_X_X\processmaker" ..\php\php.exe -f processmaker migrate-new-cases-lists ..\php\php.exe -f processmaker database-generate-self-service-value

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:

Go to Start > Accessories > Command Prompt and open a terminal. Then, change to the directory where MySQL is installed. For example: cd C:\Users\USERNAME\AppData\Roaming\ProcessMaker-X_X_X\processmaker\mysql

Then, login to MySQL:

mysql -u root -p Enter password: enter the root password

Linux/UNIX:

mysql -u root -p Enter password: enter the root password

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

mysql> use wf_workflow
Note: If unable to recall the name of the workspace, then use the following command to find it: mysql> show databases;

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:

C:\Users\USERNAME\AppData\Roaming\ProcessMaker-X_X_X\php\php.exe -m
[PHP Modules]
bcmath
bz2
calendar
com_dotnet
Core
ctype
date
dom
ereg
exif
fileinfo
...

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

Linux/UNIX:

Use a plain text editor (such as nano, vim or gedit) to edit the php.ini file, whose location depends on your distribution. Add or uncomment the following line:

extension=fileinfo.so

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 C:\Program Files\ProcessMaker-X_X_X\php\php.ini in Windows XP/2003 or C:\Users\USERNAME\AppData\Roaming\ProcessMaker-X_X_X\php\php.ini in Windows Vista and later.

In the php.ini file, uncomment the following line by changing it from: ;extension=php_fileinfo.dll

To:

extension=php_fileinfo.dll After changing the php.ini file, then restart the Apache server for the change to take effect. To verify that the fileinfo extension is enabled, issue the php -m command again and check whether fileinfo appears in the list.

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:

yum install php-mcrypt

Debian/Ubuntu/Mint:

apt-get install php5-mycrypt

SuSE/OpenSUSE:

zypper install php5-mcrypt

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:

Windows XP/Server 2003:
    c:\Program Files\ProcessMaker-X_X_X\php\php.ini

Windows Vista/7/8/10/Server 2008/2012:
    c:\Users\USERNAME\AppData\Roaming\ProcessMaker-X_X_X\php\php.ini

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.

Upgrading ProcessMaker Translations

When ProcessMaker is upgraded, the command processmaker upgrade doesn't upgrade the translations file to the latest version. In this case, it is required to download the language (depending on the language used) from here and upload it into ProcessMaker.

Recommendations after upgrading

After upgrading ProcessMaker, it is recommended to Delete the ProcessMaker Compiled Cache and completely clear the cache of the browser (or use it in an incognito window in Chrome or private browsing window in Firefox) when making the upgrade.

Activating the License

Note: This step is only required when installing ProcessMaker Enterprise Edition.

In the login page, click on Browse to upload the license.

After selecting the file click on Update License to upload it.

If the license is valid, after refreshing the page the following message is shown in the login page.