Please rate how useful you found this document: 
Average: 3 (2 votes)

Overview

This document is a detailed guide to upgrading to ProcessMaker 3.2. 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.

Note: To follow quick steps to upgrade your Processmaker installation to ProcessMaker 3.2, please read the ProcessMaker 3.2 Upgrade Plan page as the same ProcessMaker 3.2.2 Upgrade Plan.

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

About old processes:

  • Classic processes (created in the old designer in ProcessMaker 2) can be used in version 3.2, 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.2, 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.2 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.2. 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, maintaining 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.2.
  • ProcessMaker version 3.2 or later requires PHP 5.6 in Linux and PHP 5.5 in Windows.
  • 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 to upgrade ProcessMaker from a Community to an Enterprise edition. Don't forget that a license is required to use the Enterprise Edition. For more information, see activating the Enterprise license.

Safety Precautions Before Upgrading

The blacklist.ini file (used by the Code Security Scanner) is autogenerated during the upgrade process. If a customized blacklist is currently being used, take care to back up the file before starting the update process.

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.

Upgrading ProcessMaker

Step 1: Backing up ProcessMaker

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

Follow the steps below according to your operating system:

Linux/UNIX

  1. Make an archive of the ProcessMaker installation directory using the tar command, which is located at /opt/processmaker:

    tar -czf BACKUP-FILE.tar.gz /opt/processmaker
  2. Make a backup copy of the entire MySQL database using the mysqldump command:

    ProcessMaker 2.5.x and earlier

    For ProcessMaker 2.5.X and earlier, it is necessary to back up the three databases used by a workspace.

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

    ProcessMaker 2.8 and later

    In ProcessMaker 2.8 and later, each workspace uses a single database. Use the code below to back up the single database used by a ProcessMaker 2.8+ workspace.

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

    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.

    Nevertheless, the Enterprise Edition has the option to consolidate the 3 databases into 1 database per workspace using the processmaker unify-database command.

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

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

Windows

  1. 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 back up the MySQL databases.

    ProcessMaker 2.5.X and earlier

    For ProcessMaker 2.5.X and earlier, it is necessary to back up the three databases used by a workspace.

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

    ProcessMaker 2.8 and later

    In ProcessMaker 2.8 and later, each workspace uses a single database. Use the code below to back up the single database used by a ProcessMaker 2.8+ workspace.

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

After making a backup copy of the existing installation of ProcessMaker, 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.

Step 2: Updating the Content Table

To upgrade from ProcessMaker 3.0.x to ProcessMaker 3.2, it is necessary to run the following query in the ProcessMaker database that will be upgraded:

UPDATE CONTENT SET CON_VALUE = 'none' WHERE CON_CATEGORY = 'WEE_DESCRIPTION' AND CON_LANG = 'en' AND CON_VALUE = '';
UPDATE CONTENT
SET CON_VALUE = 'untitled'
WHERE CON_CATEGORY IN ('WEE_DESCRIPTION', 'WEE_TITLE', 'DYN_TITLE', 'OUT_DOC_TITLE', 'REP_TAB_TITLE', 'TRI_TITLE') AND CON_VALUE = '' AND CON_LANG = 'en';

Note: As of ProcessMaker 3.2.2, the Content upgrade above is validated with the upgrade-content command only if all labels of the corresponding tables are migrated.

Step 3: Upgrading the Source Code

Follow the steps below to install the new ProcessMaker source code and overwrite the old source code.

  1. Go to the ProcessMaker's SourceForge page and download the processmaker-3.2.tar.gz file.
  2. Decompress the processmaker-3.2.x.tar.gz file, overwriting the existing processmaker directory found at:

    Linux/UNIX:
        /opt/processmaker

    Windows 7/8/10/Server 2008/2012:
        C:\Users\USERNAME\AppData\Roaming\ProcessMaker-3.2.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).

    Use the commands that are consistent with your operating system.

Linux/UNIX

  1. Log in 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.2.tar.gz:

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

    If the ProcessMaker directory isn't named "processmaker", then temporarily rename it "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 /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.2.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

    As of ProcessMaker 3.2.2, the thirdparty folder is no longer part of the gulliver folder. Then the thirdparty folder is configured directly from /opt/processmaker as follows:

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

    Also, ProcessMaker 3.2.2 has new files that require especial permissions as follows:

    cd /opt/processmaker
    chmod -R 775 bootstrap bootstrap/cache config framework
    cd thirdparty/html2ps_pdf/
    chmod -R 775 cache/ out/ temp/
  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:\Users\USERNAME\AppData\Roaming\ProcessMaker-x.x.x\processmaker in Windows Vista/7/8/10/Server 2008/2012.

Right-click on the processmaker-3.2.x.tar.gz file that was downloaded and select 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.

Step 4: 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).

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

Step 5: Upgrading the Workspaces

After upgrading the ProcessMaker source code, use the processmaker upgrade command so that all workspaces are also upgraded to the new version.

  1. Go to the ProcessMaker installation directory and run the processmaker upgrade command from the command line.

    Linux/UNIX:

    Log in as root (or use the sudo -i command), then run the following command:

    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_2\processmaker
    ..\php\php.exe -f processmaker upgrade

Step 6: Changing the Apache Configuration

ProcessMaker 3.2 has a different VirtualHost configuration in Apache than in version 2.8.X and earlier. Please take note that the upgrade process does NOT update the Virtual Host configuration automatically. If upgrading to ProcessMaker 3.2 and later, it is necessary to change the Virtual Host configuration for ProcessMaker manually.

  1. To change the configuration, edit the pmos.conf file where the ProcessMaker Virtual Host is defined. The pmos.conf 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 according to the following examples, depending on the Apache Version.

  2. VirtualHost in Apache 2.4

  3. In the following pmos.conf file configuration, 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>
  4. Restart the Apache service for the changes to take effect.

If these changes in the rewrite rules are not made, it will no longer be possible to access ProcessMaker through a web browser. Either the ProcessMaker login screen will not load or the following error will appear:

Step 7: Upgrade the Databases

Note: When restoring a workspace backup from a different server, make sure the /shared/sites/<WORKSPACE>/db.php file content is properly configured to work on the new workspace server.

After upgrading the ProcessMaker source code, the MySQL database(s) used by ProcessMaker need to be upgraded as well.

  1. Run the processmaker database-upgrade command from the command line with the name of the workspace included at the end. Execute the command for each workspace in the ProcessMaker installation.

    Linux/UNIX:

    cd /opt/processmaker ./processmaker database-upgrade workflow

    Windows XP/Server 2003:

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

    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 workflow
  2. The unifying process may take several minutes (or hours) depending on the amount of information in the database. It takes more time if there is a large amount of cases, users, plugins, and other additional information. A message will be shown after the unification is complete indicating that it was successful.

  3. Run the processmaker flush-cache command after the unification of the databases.

    Linux/UNIX:

    cd /opt/processmaker ./processmaker flush-cache

    Windows XP/Server 2003:

    cd "c:\Program Files\ProcessMaker-X_X_X\processmaker" ..\php\php.exe -f processmaker flush-cache

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

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

Step 8: Migrating the List of Cases

ProcessMaker 3.2 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.

  1. To move the 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

Additional Configurations

Case Number for New Cases is Incorrect

ProcessMaker 3.2 has improved the speed of generating new cases by storing the last case number in the ID field of the wf_<workspace>.APP_SEQUENCE table in the database. However, this field did not exist in ProcessMaker 2.x. If upgrading from version 2.x to 3.x, the case number of the last case needs to be inserted into this field.

If using ProcessMaker Enterprise Edition, 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:

Windows:

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

Then, log in to MySQL:

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

Linux/UNIX:

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

Once logged into MySQL, 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, use the following command to find it: mysql> show databases;

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 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, 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 mcrypt Extension

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

Linux/UNIX:

To install the mcrypt module use the package from your Linux/UNIX distribution:

Red Hat/CentOS/Fedora:

yum install php5-mcrypt

Debian/Ubuntu/Mint:

apt-get install php5.6-mcrypt

SuSE/OpenSUSE:

zypper install php5-mcrypt

Windows:

For Windows, use a plain text editor to edit the php.ini file, which by default is located at:

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

Windows Server 2012 Manual Installation:
    c:\Users\USERNAME\AppData\Roaming\ProcessMaker-X_X_X\php\php.ini

Windows Bitnami Installation:
    c:\Bitnami\processmaker-3.x.x.bx-0\php\php.ini

In the php.ini file, uncomment (remove the semicolon ; symbol) the following line:

extension=php_mcrypt.dll

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

After Upgrading

Deleting the Cache

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

Upgrading ProcessMaker Translations

When ProcessMaker is upgraded, the command processmaker upgrade doesn't upgrade the translation files 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.

Activating the License

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

On 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, the following message is shown on the login page after refreshing the page.

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:

Log in 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