Preparations

During the upgrade process, you must use the default application user, mzadmin, and correct password whenever you are prompted to enter it.

The preparation steps will not affect the running system and can be done in advance.

Note!

For users who have custom agents created in Development Toolkit and upgrading from 8.3:

If you have custom agents created using Development Toolkit, these agents cannot be included in the upgrade. For information on how to remove them before proceeding with the upgrade procedure, see Upgrade and Downgrade in Installation and Setup.

Note!

For systems using Configuration Spaces:

Configuration Spaces is replaced with the new Workflow Packages functionality. Prior to upgrading make sure to export the configuration from inactive configuration spaces that you want to keep, as only the active space is carried across during the upgrade process.

For further information regarding Configuration Spaces, and how to use them, please refer to Configuration Spaces in the version 8.3 documentation.

Before proceeding with the upgrade, make the following preparations:

Verify that you are running version 8.3.0.0 or later. You can check the current version by opening the About window in the Desktop, where the current version is listed in the Pico Version section. If the system is running an earlier version, you need to upgrade it to an 8.3.x version first. See the documentation space for the version you are currently running for more information.
Install either Oracle JDK 17 or OpenJDK 17 the server(s) where the Platform Container and Execution Containers are running.
Verify that the System Requirements are met. If the operating system, or database need to be upgraded, this should be done prior to the upgrade. This has to be done for all machines that are hosting the system.
Ensure that the environment variables are set correctly:

Variable

Description

MZ_HOME

This environment variable specifies where the software is installed.

JAVA_HOME

This environment variable specifies where the JDK is installed.

PATH

This environment variable specifies the search path and must contain the following directories:

$JAVA_HOME/bin:$MZ_HOME/bin

Make an online backup of the database(s). For further information regarding how to perform an online backup, see Preventive Maintenance Procedures.
Note! If you are upgrading from 8.3.x, you can find the database backup instructions in the documentation for 8.3 as the procedure may differ from that of 9.x.
It is important to make a backup of MZ_HOME for rollback purposes.
To make a backup of your MZ_HOME, you can use the following command:

Note!

Ensure that all processes in your installation are shutdown prior to the backup.

You can check which processes are running by using the mzsh status command.

$ cd $MZ_HOME/../
$ tar -zcvf mzhome_backup.tgz <MZ_HOME directory>
$ mv mzhome_backup.tgz <backup directory>

Use of MZ_HOME backup

The MZ_HOME backup is needed in case the upgrade fails.

Create a directory to use when unpacking this release and future releases. For the purpose of these instructions, this designated directory is referred to as the staging directory.
Note!

The staging directory should not be the same directory as the one you created and set up as the MZ_HOME directory.
Place the *.tgz file from your release delivery into the staging directory.
Use a command line tool, go to the staging directory, and unpack the *.tgz file by running the following command:
```
$ tar xvzf <filename>.tgz
```
A directory is then created in the staging directory, containing the software to be installed. For the purpose of these instructions, this directory is referred to as the release content directory.
Now copy the MZ license file into the release content directory.

If you are upgrading from 8.3.x, you need a new license file. https://www.digitalroute.com/contact/contact-support/ on getting the MZ license file.

$ cp mz.license <release content directory>

Enter the release content directory and prepare the install.xml file by running the following command:
```
$ cd <release content directory>
$ ./setup.sh prepare
```
The *.mzp packages have now been extracted, and the install.xml has been extracted into the release content directory. The install.xml file will automatically be populated with information from your existing installation.

Refer Platform Properties to know more about these properties and their default values.

Important!

When upgrading to this release, the install.admin.password must be set according to your current admin password before proceeding with the ./setup.sh upgrade step.

Important!

If the existing installation has additional JVM arguments configured which are obsolete in Java 17, remove them and update to use supported options.

Please refer to Java 17 docs for details on ‘Obsolete’ and ‘Removed’ Java options since Java 8.

See Managing Picos with Topo for JVM Arguments configuration.

Important!

If your existing MZ_HOME platform database is configured to use other database type rather than the default Derby, you need to check and update the respective database related properties from the install.xml file to match your current setup.

Oracle

See Properties for Oracle for details.

PostgreSQL

See Properties for PostgreSQL for details.

SAP HANA

See Properties for SAP HANA for details.

Important!

If you are upgrading from 9.0.0.0 or 9.0.1.0 and using other database type rather than the default Derby, then you need to manual copy the database 3pp jar to the $MZ_HOME/3pp folder prior the upgrade.

However this is not required if your current running version is 9.0.2.0 onwards.

Note!

If you are upgrading from 8.x and using Oracle as system database, you need to use Oracle 19c (19.20.0.0) JDBC drivers (ojdbc8.jar/ojdbc10.jar).

The jar file can be downloaded from https://www.oracle.com/database/technologies/appdev/jdbc-downloads.html