Upgrading IBM Process Mining

You can upgrade the IBM Process Mining application directly from the existing version to the next immediate version of IBM Process Mining. For example, you can upgrade directly from version 2.0.1 to 2.0.2.

See the following sections to upgrade your IBM Process Mining deployment from 2.1.1 to 2.2.0:

Before you begin
Procedure

Before you begin

You must download the installation package from IBM® Passport Advantage®. To know more about downloading packages, see Downloading Packages.

The IBM Process Mining installation package is ibmprocessmining-update-X.Y.Z_<build number>.tar.gz, where X.Y.Z indicates the version of IBM Process Mining, and <build number> indicates the build or part number.

For troubleshooting the IBM Process Mining upgrade process, see Troubleshooting application configuration.

Procedure

To upgrade from IBM Process Mining version 2.1.1 to version 2.2.0, do the following steps:

Stop the Process Mining application services.
Copy the compressed file to the destination server and extract it to a directory. For example, /home/<mydir>/processmining-update.
Go to the processmining-update directory.
Set the environment variable PM_HOME according to your installation, such as export PM_HOME=/opt/processmining.
Run the shell script update.sh. The shell script creates a backup of your existing version in ${PM_HOME}/backup_<current date> and upgrades your IBM Process Mining deployment to version 2.2.0. By default, update.sh does not overwrite the customized files.

Important: update.sh can update a customised bin/environment.conf.

In IBM Process Mining, you can use the force option for the update.sh shell script to overwrite the customized files.

You can use the following options to run the update.sh shell script:

    ./update.sh --help
    *** USAGE:  update.sh [--help | -h] [--force]
    --help  : display this usage information
    -h      : same as --help
    --force : will overwrite any files that have changed
    original copies will still be available in backup folder

When you run the default ./update.sh command, the changed files are labelled as follows:

: file has been modified, will not overwrite.

Such files are summarized at the end of the script run. The original files remain without any change whereas the new file is saved in the same folder with the .2.2.0 file extension. This information is also stored for future reference in $PM_HOME/modified.txt.

The following script provides an example for the default update:

    ./update.sh 2>&1 | tee update-log.txt

    ...
    >crypto-utils/lib:
    crypto-utils-1.0.2.jar
    >etc:
      logback-analytics.xml
      logback-engine.xml
            logback-monitoring.xml
            logback-web.xml
            processmining.conf                   : file has been modified, will not overwrite
          ...
          ---
          upgrade complete.
          .
          Some files have been modified and unable to automatically update.
          Check these files manually.
          Your file HAS NOT been modified, compare it with the new copy '*.2.2.0'
          --
              etc/processmining.conf
              etc/processmining.conf.2.2.0
          --
          -

When you override the file changes using the ./update.sh --force command, the changed files are labelled as follows:

: file has been modified, forcing overwrite

Such files are also summarized at the end of the script run. The files are overwritten by the new 2.2.0 files. The original files are stored in the backup folder. This information is also stored for future reference in $PM_HOME/modified.txt.

The following script provides an example for the force update:

        ./update.sh --force
        ---
        upgrade complete.
        .
        Some files have been modified and have been overwritten.
        Check these files manually.
        compare it with the backup 'backup_2025-03-14_1432'
        --
            etc/processmining.conf
            backup_2025-03-14_1432/etc/processmining.conf
        --
        -

Important: When updating and editing ${PM_HOME}/etc/processmining.conf make sure to bring over the new settings including jdbc section, for PostgreSQL and to keep the existing MonetDB section.

If you do not set the environment variable when you upgrade to IBM Process Mining version 2.2.0, the update.sh returns the following error message:

    ./update.sh
    Error: PM_HOME environment variable is not set. Set it to the processmining home.

Note: Starting with IBM Process Mining 2.0.3 ${PM_HOME}/etc/brm-service.conf does not exist. BRM Host and Port can now be found in ${PM_HOME}/bin/environment.conf.

PostgreSQL update

IBM Process Mining provides a database update tool located in ${PM_HOME}/utils/database-utils.

Run the tool with the following command:
```
    pushd ${PM_HOME}/utils/database-utils
    ./postgres-utils.sh
    popd
```
Warning: Do not continue any further if the update tool failed to complete successfully. Attempting to launch IBM Process Mining without a successful migration might lead to further issues.
Change the owner of <PM_HOME> to the RUNAS user. For example, myuser:
```
    chown -R myuser:myuser ${PM_HOME}
```
Start the services.