Please rate how useful you found this document: 
Average: 1 (1 vote)

Contents: [hide]

Overview

This document explains how to upgrade to ProcessMaker 3.3.X from an older version of ProcessMaker. Read this document carefully before beginning to upgrade to ProcessMaker 3.3.X. Due to changes in the code, it is necessary to first upgrade to version 3.2.2 or 3.2.3. Then, upgrade to version 3.3.X.

If you are upgrading between versions in ProcessMaker 3.3.X, read the point release upgrading.

ProcessMaker is here to help. If you need technical assistance or would like to request a Professional Services engagement, please submit a support ticket: http://bugs.processmaker.com/login_page.php. If upgrading from ProcessMaker 1.X, Professional Services must perform the upgrade for you.

Disclaimer

ProcessMaker does not support third-party integrations or external plugins as part of the upgrade process. ProcessMaker Support cannot properly offer timely and accurate support when an application not explicitly stated in the documentation for your ProcessMaker 3.3 stack does not state is required.

Prerequisites for the Upgrade

Ensure the following prerequisites are met as you prepare to upgrade:

  • Determine how to prepare a ProcessMaker test environment based on whether your current ProcessMaker production server meets ProcessMaker 3.3 supported stack requirements. Review version 3.3 stack requirements.

    • Current production environment meets ProcessMaker 3.3.X supported stack requirements.

      Action: Create a test environment that is a clone of your current production server that includes all core files and data.

    • Current production environment does not meet ProcessMaker 3.3.X supported stack requirements.

      Action: Create a test environment that meets ProcessMaker 3.3.X supported stack requirements. Then, copy your current production server, including all core files and data, to the test environment.

  • ProcessMaker Support requires remote access to both the current production server and the new test environment either through a VPN or any Remote Assistance Tool, to perform the upgrade in the new test environment.

Upgrade Road Map

The Upgrade Road Map, shown below, depicts steps to upgrade to ProcessMaker 3.3.X:

  • Upgrading from 1.6.X or older: ProcessMaker Professional Services must perform the upgrade to version 3.3.X for you. This upgrade path is not supported.
  • Upgrading from version 2.0 or 2.0.4: Your upgrade path involves these ProcessMaker versions:
    • Version 2.5.0
    • Version 2.5.2
    • Version 3.2.2 or 3.2.3
    • Version 3.3
  • Upgrading from version 2.8 or 2.9 to 3.2.2 or 3.2.3: Your upgrade path is direct to version 3.3.X.
  • Upgrading from 3.0.X or 3.1.X to 3.2.2 or 3.2.3: Your upgrade path is direct to version 3.3.X.

Plan Your Upgrade with ProcessMaker Support

Use the schedule template below to plan your upgrade path to ProcessMaker 3.3.X. Outline each step that must occur on the upgrade path through each ProcessMaker version until ProcessMaker 3.3 is installed in the test environment. After each upgrade is completed, this template becomes an audit that documents each upgrade.

Download a PDF of this template here.

Schedule Template to Upgrade the Test Environment
Task Task Responsibility Completion Time (Hours) Task Description Date Completed
1 Deploy the new test environment with a supported OS Customer Verify that the new test environment uses a supported operating system.
2 Install the Supported Stack (Apache, PHP, and MySQL) ProcessMaker Support If the new test environment does not have a supported stack, install the appropriate ProcessMaker 3.3.X stack.
3 Backup Creation Customer and ProcessMaker Support Back up the core files.
4 Database backup creation Customer and ProcessMaker Support Backup the database files.
5 Additional Setup ProcessMaker Support Restore the connection hash and service settings.
6 Standard upgrade procedure ProcessMaker Support Run the standard upgrade procedure. Any issue found during this procedure needs to be documented in a new row below this one with all the details how to fix it.
7 Test all basic functionalities ProcessMaker Support Test all basic functions in the new test environment.
8 Customer functional tests Customer The CUSTOMER needs to test all the processes and custom plugins to ensure correct functionality.

Note: Each issue found that ProcessMaker Support is to fix must be documented in a new row of this table before continuing to upgrade to the next ProcessMaker version.

Template to Document Steps to Upgrade the Production Server

Use the template below for the following purposes:

  • Document a consolidated list of all steps and hours involved to perform your entire upgrade path in the test environment. Update this list after each upgrade to complete until ProcessMaker 3.3 is installed in the test environment.
  • Meticulously document any issues discovered on the test server during the upgrade path. Include extra settings required to fix each issue before starting the upgrade path on the production server.

Download a PDF of this template here.

Steps to Upgrade the Production Server
Step Task Description Task Responsibility Completion Time (Hours) Comments (Including ProcessMaker Version)

ProcessMaker Support Recommendations

ProcessMaker Support strongly recommends to follow these recommendations:

  1. All the steps in this document must be followed to successfully upgrade to ProcessMaker 3.3.X
  2. ProcessMaker Support begins each upgrade only after the Customer completes exhaustive functional testing, and then provides approval to continue.
  3. The production environment upgrade must be done only after the test environment upgrade is completed.

Upgrade Standard Procedure

The following sections outline the standard procedure to upgrade from ProcessMaker versions 2.X and 3.X to ProcessMaker 3.3.X based on these supported operating systems:

Linux

To upgrade to ProcessMaker 3.3.X on the supported Linux operating system, refer to the section below based on from which ProcessMaker version you are upgrading:

Upgrade from ProcessMaker 2.0.X to ProcessMaker 2.5.0

Follow these steps to upgrade from ProcessMaker 2.0.X to ProcessMaker 2.5.0:

  1. First, login as root or with the powers of root: su or: sudo su -
  2. Copy the processmaker-2.5.0.tar.gz file to the /opt directory. cp processmaker-2.5.0.tar.gz /opt/
  3. Overwrite any existing files in the /opt directory: cd /opt tar -xzvf processmaker-2.5.0.tar.gz
  4. Configure the permissions for the processmaker directory: chmod -R 770 processmaker/
  5. Set the Apache user as the owner of the files within the processmaker directory: chown -R apache:apache processmaker Note: The Apache user and group are named apache:apache in CentOS/Red Hat, www-data:www-data in Debian/Ubuntu and wwwrun:www in SUSE/OpenSUSE.
  6. Change to the processmaker directory: cd /opt/processmaker
  7. Upgrade ProcessMaker files, the ProcessMaker database, and the translation files as described at ProcessMaker Command: ./processmaker upgrade

    Note: If you are upgrading from ProcessMaker Community edition 2.x or later to ProcessMaker Enterprise edition 3.2.2, perform the following command to migrate your cases from the Community edition to the upgraded Enterprise edition: ./processmaker migrate-new-cases-lists If you want to check the database schema and upgrade it if necessary you can use: ./processmaker database-upgrade

  8. Flush the cache: ./processmaker flush-cache

Upgrade from ProcessMaker 2.5.2 or later to ProcessMaker 3.3.X

This section describes how to upgrade from the following ProcessMaker versions:

  • 2.5.2
  • 2.8
  • 2.9
  • 3.0.X
  • 3.1.X
  • 3.2.X Minor Release

Refer to the following sections to upgrade from ProcessMaker 2.5.2 or later to ProcessMaker 3.3.X:

Before Upgrading to ProcessMaker 3.3.X

Before upgrading to ProcessMaker 3.3.X, login to MySQL as the "root" user (or as the user listed in the shared/sites/workspace/db.php file): mysql -u root -p Then, switch to workspace's database (which is named wf_workflow by default): USE database;

Note: To see a list of the available databases, use: SHOW DATABASES;
Then, issue the following two commands to update values in the CONTENT table:
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';
If more workspaces were created, then issue these same commands for each workspace database. Finally, exit MySQL: EXIT;
Steps to Upgrade to ProcessMaker 3.3.X

Refer to the following sections to upgrade to ProcessMaker 3.3.X using these supported databases:

Upgrade to ProcessMaker 3.3.X with Apache

If using the Apache web server, follow these steps to first upgrade to ProcessMaker 3.2.2 or 3.2.3. Then, upgrade to ProcessMaker 3.3.X:

  1. First, login as root or with the powers of root: su or: sudo su -
  2. Copy the processmaker-3.2.X.tar.gz file to the /opt directory.
  3. cp processmaker-3.2.X.tar.gz /opt/
  4. Overwrite any existing files in the /opt directory: cd /opt tar -xzvf processmaker-3.2.X.tar.gz
  5. Configure the permissions for the processmaker directory: chmod -R 770 processmaker/
  6. Enter the directory: cd processmaker
  7. Give permission access to the following files: chmod -R 775 bootstrap bootstrap/cache config framework cd thirdparty/html2ps_pdf/ chmod -R 775 cache/ out/ temp/
  8. Set the Apache user as the owner of the files within the processmaker directory: chown -R apache:apache /opt/processmaker Note: The Apache user and group are named apache:apache in CentOS/Red Hat, www-data:www-data in Debian/Ubuntu and wwwrun:www in SUSE/OpenSUSE.
  9. Change to the /opt/processmaker directory: cd /opt/processmaker
  10. Use the processmaker command to upgrade the ProcessMaker files, the workspace database(s) and the translation files. As root (or sudo), issue the following command which is executed as the Apache user: su -s /bin/sh apache -c "./processmaker upgrade" Note: Change apache to www-data if using Debian/Ubuntu or to wwwrun if using SUSE/OpenSUSE. Also after upgrading the ProcessMaker source code, the MySQL database(s) used by ProcessMaker need to be upgraded as well, to do that use: su -s /bin/sh apache -c "./processmaker database-upgrade workflow"
  11. Flush the cache: su -s /bin/sh apache -c "./processmaker flush-cache"
  12. Note: If upgrading from ProcessMaker Community edition 2.x or later to ProcessMaker Enterprise edition 3.2.2 or 3.2.3, perform the following command to migrate your cases from the Community edition to the upgraded Enterprise edition: su -s /bin/sh apache -c "./processmaker migrate-new-cases-lists"

  13. Repeat all the previous steps but this time with the 3.3 version of the file.

Upgrade to ProcessMaker 3.3.X with NGINX

If using the NGINX web server, follow these steps to first upgrade to ProcessMaker 3.2.2 or 3.2.3. Then, upgrading to ProcessMaker 3.3.X:

  1. First, login as root or with the powers of root: su or: sudo su -
  2. Copy the processmaker-3.2.X.tar.gz file to the /opt directory.
  3. cp processmaker-3.2.X.tar.gz /opt/
  4. Overwrite any existing files in the /opt directory: cd /opt tar -xzvf processmaker-3.2.X.tar.gz
  5. Configure the permissions for the processmaker directory: chmod -R 770 processmaker/
  6. Enter the directory: cd processmaker
  7. Give permission access to the following files: chmod -R 775 bootstrap bootstrap/cache config framework cd thirdparty/html2ps_pdf/ chmod -R 775 cache/ out/ temp/
  8. Configure the owner of the files within the processmaker directory: chown -R nginx:nginx processmaker/
  9. Change to the /opt/processmaker directory: cd /opt/processmaker
  10. Upgrade ProcessMaker files, the ProcessMaker database, and the translation files as described at ProcessMaker Command: su -s /bin/sh nginx -c "./processmaker upgrade WORKSPACE" Note: Also after upgrading the ProcessMaker source code, the MySQL database(s) used by ProcessMaker need to be upgraded as well, to do that use: su -s /bin/sh nginx -c "./processmaker database-upgrade workflow"
  11. Flush the cache: su -s /bin/sh nginx -c "./processmaker flush-cache WORKSPACE"
  12. Note: If you are upgrading from ProcessMaker Community edition 2.x or later to ProcessMaker Enterprise edition 3.2.2 or 3.2.3, perform the following command to migrate your cases from the Community edition to the upgraded Enterprise edition: su -s /bin/sh nginx -c "./processmaker migrate-new-cases-lists"

  13. Repeat all the previous steps but this time with the 3.3 version of the file.

Point Release - Upgrade between two versions in ProcessMaker 3.3.X

Refer to the following sections to upgrade a version to another one in ProcessMaker 3.3.X:

Upgrade to ProcessMaker 3.3.X with Apache

If using an Apache web server, follow these steps to upgrade to ProcessMaker 3.3.X:

  1. Log on as root or with the root permissions: su or: sudo su -
  2. Copy the processmaker-3.3.X.tar.gz file to the /opt directory.
  3. cp processmaker-3.3.X.tar.gz /opt/
  4. Overwrite any existing files in the /opt directory: cd /opt tar -xzvf processmaker-3.3.X.tar.gz
  5. Configure the permissions for the processmaker directory: chmod -R 770 processmaker/
  6. Enter the directory: cd processmaker
  7. Give permission access to the following files: chmod -R 775 bootstrap bootstrap/cache config framework cd thirdparty/html2ps_pdf/ chmod -R 775 cache/ out/ temp/
  8. Set the Apache user as the owner of the files within the processmaker directory: chown -R apache:apache /opt/processmaker
  9. Change to the /opt/processmaker directory: cd /opt/processmaker
  10. Use the processmaker command to upgrade the ProcessMaker files, the workspace database(s) and the translation files. As root (or sudo), issue the following command which is executed as the Apache user: su -s /bin/sh apache -c "./processmaker upgrade"

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

  11. Depending on the point release, run the flush-cache command: su -s /bin/sh apache -c "./processmaker flush-cache"

    Note: If the point release version to upgrade does not contain a solution that requires to run the flush-cache command, the upgrade process does not requires to run the command. In the front page (previous versions are in the same document), review the requirements of the Release Notes to know if the ProcessMaker version requires to run the flush-cache command.

Upgrade to ProcessMaker 3.3.X with NGINX

If using the NGINX web server, follow these steps to upgrade to ProcessMaker 3.3.X:

  1. Log on as root or with the root permissions: su or: sudo su -
  2. Copy the processmaker-3.3.X.tar.gz file to the /opt directory. cp processmaker-3.3.X.tar.gz /opt/
  3. Overwrite any existing files in the /opt directory: cd /opt tar -xzvf processmaker-3.3.X.tar.gz
  4. Configure the permissions for the processmaker directory: chmod -R 770 processmaker/
  5. Enter the directory: cd processmaker
  6. Give permission access to the following files: chmod -R 775 bootstrap bootstrap/cache config framework cd thirdparty/html2ps_pdf/ chmod -R 775 cache/ out/ temp/
  7. Configure the owner of the files within the processmaker directory: chown -R nginx:nginx processmaker/
  8. Change to the /opt/processmaker directory: cd /opt/processmaker
  9. Upgrade ProcessMaker files, the ProcessMaker database, and the translation files as described at ProcessMaker command: su -s /bin/sh nginx -c "./processmaker upgrade WORKSPACE"

    Warning: 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. Depending on the point release, run the flush-cache command: su -s /bin/sh nginx -c "./processmaker flush-cache WORKSPACE"

    Note: If the point release version to upgrade does not contain a solution that requires to run the flush-cache command, the upgrade process does not requires to run the command. In the front page (previous versions are in the same document), review the requirements of the Release Notes to know if the ProcessMaker version requires to run the flush-cache command.

Windows

To upgrade to ProcessMaker 3.3.X on the supported Windows operating system, refer to the section below based on from which ProcessMaker version you are upgrading:

Upgrade from ProcessMaker 2.X to ProcessMaker 2.5.0

Follow these steps to upgrade from ProcessMaker 2.X to ProcessMaker 2.5.0:

  1. Copy the processmaker-2.5.0.tar.gz file to the C:\opt directory.
  2. Use a program like WinRAR or 7-Zip to extract processmaker-2.5.0.tar.gz to the C:\opt directory.
  3. In a terminal, go to the C:\opt\processmaker directory: cd C:\opt\processmaker
  4. Upgrade ProcessMaker files, the ProcessMaker database, and the translation files as described at ProcessMaker Command: php -f processmaker upgrade

    Note: If you are upgrading from ProcessMaker Community edition 2.x or later to ProcessMaker Enterprise edition 3.2.2 or 3.2.3, perform the following task to migrate your cases in the Community edition to the upgraded Enterprise edition: php -f processmaker migrate-new-cases-lists If you want to check the database schema and upgrade it if necessary you can use: php -f processmaker database-upgrade workflow

  5. Flush the cache: php -f processmaker flush-cache

Upgrade from 2.5.2 or later to ProcessMaker 3.3.X

This section describes how to upgrade from the following ProcessMaker versions:

  • 2.5.2
  • 2.8
  • 2.9
  • 3.0.X
  • 3.1.X
  • 3.2.X Minor Release

Refer to the following sections to upgrade from ProcessMaker 2.5.2 or later to ProcessMaker 3.3.X:

Before Upgrading to ProcessMaker 3.3.X

Before upgrading to ProcessMaker 3.3.X, first change the directory which contains the msql.exe file. For example: cd "C:\Program Files\MySQL\mysql-5.6.42-winx64\bin" Then, login to MySQL as the "root" user (or as the user listed in the shared/sites/{workspace}/db.php file): mysql -u root -p Then, switch to workspace's database (which is named wf_workflow by default): USE database;

Note: To see a list of the available databases, use: SHOW DATABASES;
Then, issue the following two commands to update values in the CONTENT table:
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';
If more workspaces were created, then issue these same commands for each workspace database. Finally, exit MySQL: EXIT;
Steps to Upgrade to ProcessMaker 3.3.X

Follow these steps to upgrade to ProcessMaker 3.2.2 or 3.2.3:

  1. Copy the processmaker-3.2.X.tar.gz file to c:/opt directory.
  2. Extract processmaker-3.2.X.tar.gz to the /opt directory.
  3. Go to the c:/opt/processmaker directory: cd c:\opt\processmaker
  4. Upgrade ProcessMaker files, the ProcessMaker database, and the translation files as described at ProcessMaker Command: php -f processmaker upgrade

    Note: If you are upgrading from ProcessMaker Community edition 2.x or later to ProcessMaker Enterprise edition 3.2.2 or 3.2.3, perform the following task to migrate your cases in the Community edition to the upgraded Enterprise edition: php -f processmaker migrate-new-cases-lists If you want to check the database schema and upgrade it if necessary you can use: php -f processmaker database-upgrade workflow

  5. Flush the cache: php -f processmaker flush-cache
  6. Repeat all the previous steps, but this time with the 3.3.X version of the file.

Point Release - Upgrade between two versions in ProcessMaker 3.3.X

Refer to the following sections to upgrade a version to another one in ProcessMaker 3.3.X:

  1. Copy the processmaker-3.3.X.tar.gz file to c:/opt directory.
  2. Extract processmaker-3.3.X.tar.gz to the /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. Upgrade the ProcessMaker files, database and the translation files as described at ProcessMaker Command. php -f processmaker upgrade

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

  6. Depending on the point release, run the flush-cache command: php -f processmaker flush-cache

    Note: If the point release version to upgrade does not contain a solution that requires to run the flush-cache command, the upgrade process does not requires to run the command. In the front page (previous versions are in the same document), review the requirements of the Release Notes to know if the ProcessMaker version requires to run the flush-cache command.

Contact Us

If you would like to request support, provide feedback, and/or report an issue, please go to http://bugs.processmaker.com.