2.0/Upgrading ProcessMaker

The ProcessMaker is rapidly evolving with frequent new versions being released. In order to take advantage of recent bug fixes and the new features being offered, ProcessMaker 2.0 can be upgraded by overwriting the existing code and updating the database to a more recent version. If upgrading from version 1.X to 2.0, see these instructions. If migrating from a Windows to a Linux system, see these instructions.

It is important to follow the correct upgrading procedure so that the PHP source code, the file locations, and the MySQL databases holding ProcessMaker data will all be simultaneously updated to work together. 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.

Note: When upgrading ProcessMaker, it is strongly recommended to Clear Cache or press Crtl F5 to refresh your web browser from ProcessMaker 2.0.40 +; or Deleting ProcessMaker Compiled Cache in ProcessMaker - 3.0.39.

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 in the same server) and import your processes into the test server to verify that there are no incompatibilities.

Before upgrading ALWAYS make a complete backup copy of directory where ProcessMaker is installed and use mysqldump to make a complete backup of the 3 databases 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.

NOTE: It is not very easy to restore a previous version of ProcessMaker with just a backup created with the gulliver 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

To back up just the databases for a ProcessMaker workspace, such as the "workflow" workspace:

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

TIP: If unsure what the MySQL databases are named, login to MySQL and issue the command: SHOW DATABASES;

Windows:

Use a compression program like 7-Zip or WinRar to make a backup copy of the ProcessMaker installation directory, which is usually located at c:\Program Files\ProcessMaker\processmaker (if installed version 1.6-4260 and later) or c:\Program Files\ProcessMaker\apps\processmaker (if installed a version before 1.6-4260).

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:

cd c:\Program Files\ProcessMaker\mysql\bin

Then, enter use the mysqldump to backup the MySQL databases as shown above for Linux/UNIX. Note that if ProcessMaker was installed before version 1.6.4260, then the reports database is named "rp<WORKSPACE>" (without underscore), so the command to backup the "workflow" workspace would be:

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

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 -xzf BACKUP-FILE.tar.gz

Then, restore the databases:

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

Windows:

Delete the current ProcessMaker installation directory, which by default is located at c:\Program Files\ProcessMaker-2_X_X in Windows XP/2003 or c:\Users\USERNAME\AppData\Roaming\ProcessMaker-2_X_X in Windows Vista/7/2008.

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

cd c:\Program Files\ProcessMaker\mysql\bin

Then, restore the MySQL databases:

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

Upgrading ProcessMaker 2.0

In ProcessMaker 2.0, 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 http://sourceforge.net/projects/processmaker/files/ProcessMaker and download a processmaker-2.X.X.tar.gz file, which has a new version of the ProcessMaker source code.

2. Decompress the processmaker-2.X.X.tar.gz file, overwriting the existing processmaker directory and all its contents, which is generally found at /opt/processmaker in Linux/UNIX, at C:\Program Files\ProcessMaker-2_X_X\processmaker in Windows XP/2003, and at C:\Users\USERNAME\AppData\Roaming\ProcessMaker-2_X_X\processmaker in Windows Vista/7/2008.

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 processmaker is located.

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

tar --overwrite -p -C /opt -xvzf /root/processmaker-2.0.38.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-2.0.38.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
cd /opt/processmaker/workflow/engine/
chmod -R 770 config content/languages plugins xmlform js/labels

3. Finally, change the owner of the ProcessMaker files to the user which 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 7-Zip or 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-2_X_X\processmaker in Windows XP/2003 or c:\Users\USERNAME\AppData\Roaming\ProcessMaker-2_X_X\processmaker in Windows Vista/7/2008.

Upgrading with 7-Zip

Right click on the processmaker-2_X_X.tar.gz file which was downloaded and select the option 7-Zip > Extract files... from the dropdown menu.

In the "Extract" dialog box that appears, go to the Extract to: field and enter the parent directory to the processmaker directory, which by default is located at c:\Program Files\ProcessMaker-2_X_X in Windows XP/2003 and c:\Users\USERNAME\AppData\Roaming\ProcessMaker-2_X_X in Windows Vista/7/2008. Also select the Overwrite without Prompt option in the Overwrite mode: dropdown box.

Then, click on OK to begin the extraction.

Upgrading with WinRAR

Right click on the processmaker-2_X_X.tar.gz file which was downloaded and select the option Extract files... from the dropdown menu.

In the "Extraction Path and Options" dialog box that appears, go to the Destination Path field and enter the parent directory to the processmaker directory, which by default is located at c:\Program Files\ProcessMaker-2_X_X in Windows XP/2003 and c:\Users\USERNAME\AppData\Roaming\ProcessMaker-2_X_X in Windows Vista/7/2008. Also mark the Overwrite without prompt option in the Overwrite mode section.

Then, click on OK to begin the extraction.

Modifying my.cnf file

Modify this file for MySql versions 5.5.x or greater

To avoid problems running triggers on mysql the default go to my.conf located at /etc and change parameter from binlog_format=mixed to binlog_format=row therefore is recommended to change the configuration binlog_format = MIXED.

For more information check the mysql documentation

Upgrading the ProcessMaker databases

After upgrading the processmaker source code, then use the processmaker upgrade command to upgrade the 3 databases used by each ProcessMaker workspace. The databases have 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

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
/PHP-PATH/php -f processmaker upgrade

Windows:

If you run the .exe file to install ProcessMaker run the following command from teh command line:

cd /opt/processmaker
/PHP-PATH/php -f processmaker upgrade

If you made a manuall installation, login as an Administrator and open the Command Prompt (by going to Start > All Programs > Accessories > Command Prompt) and enter:

cd C:\Program Files\ProcessMaker\processmaker
processmaker.bat upgrade

cd /opt/processmaker /PHP-PATH/php -f processmaker upgrade

Upgrading ProcessMaker translations

When ProcessMaker is upgraded, the command doesn't upgrade the translations file into the latest versions. 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

When upgrading a language, it is strongly recommended to Clear Cache or press Crtl F5 to refresh your web browser from ProcessMaker 2.0.40 +; or Deleting ProcessMaker Compiled Cache in ProcessMaker 2.0.39.

Options for the processmaker command

In most cases, running the processmaker upgrade command will be sufficient when upgrading, but other commands are available if a finer degree of control is needed:

• ./processmaker upgrade

Checks the integrity of all source code files and then runs upgrade on all available workspaces.

• ./processmaker workspace-upgrade [WORKSPACE1 WORKSPACE2 ...]

Without arguments, workspace-upgrade will upgrade all available workspaces. If the workspaces names are specified, then only those workspaces will be upgraded.

workspace-upgrade will execute the three following commands on each workspace:

• ./processmaker database-upgrade

Checks the database schema and upgrade it if necessary.

• ./processmaker translation-upgrade

Updates translations from the existing PO translation files.

• ./processmaker cacheview-upgrade

Updates the wf_<WORKSPACE>.APP_CACHE_VIEW tables and triggers.

• ./processmaker plugins-database-upgrade

Checks the database schema and upgrade it if necessary, only for tables related with the Enteprise Plugins. It creates all necessary tables, in the case they are not created.