Upgrade PPM

This section describes the steps used to upgrade to PPM 9.63-9.65.

Supported upgrade paths

To upgrade to PPM version 9.63-9.65, you must have PPM 9.60 or later installed. If an earlier version is installed, you must first upgrade to version 9.60, and then upgrade to PPM version 9.63-9.65.

For information on how to upgrade to version 9.60, see the Upgrade Guide for version 9.60.

Note: We strongly recommend upgrading to the latest version of PPM Center. In general, each new PPM version includes important product improvements that are not provided in earlier versions.

The following table describes supported upgrade paths in more details. Versions in parenthesis can be skipped. For example, if you want to upgrade PPM to 9.65 from 9.55, you should first upgrade to 9.60, with or without upgrading to 9.61-9.64, and then upgrade to 9.65.

Current PPM Center Version Can be upgraded to
9.4x (9.41-9.42) > 9.50 > (9.5x) > 9.60 > 9.6x
9.5x (9.51-9.55) > 9.60 > 9.6x
9.60 (9.61-9.64) > 9.65
9.61 (9.62-9.64) > 9.65
9.62 (9.63-9.64) > 9.65
9.63 (9.64) > 9.65
9.64 9.65

For information on how to upgrade to version 9.60-9.62, see the Upgrade Guide for version 9.60-9.62.

Back to top

New upgrade mode

Since 9.61, the legacy upgrade mechanism is deprecated. You should use the sh upgrade.sh command to upgrade PPM.

How to upgrade PPM:

  1. Extract the ppm-<PPM version>-upgrade.zip package.

  2. Navigate to the <PPM_Home>upgrade_<PPM version> directory and run the sh upgrade.sh command.

    Parameter Description

    -n, or

    --new_PPM_Home

    Upgrades your current PPM system to a new specified <PPM_Home> folder. For details, see Standard upgrade procedures.

    As the deployment file system structure changes a lot since 9.61, we recommend you run this command because doing this can back up the existing file system and makes it easier to restore.

    To define which files or folders to copy from the existing <PPM_Home> folder to the new folder, edit the upgrade.properties file under the upgrade_<PPM version> folder, for example:

    ppm.upgrade.copypath=server.conf;ppm_server_conf.env;security;customization;content

    Note: If you upgrade your instance to a new PPM home, in some cases, the attachments, report logs, and execution logs that are placed under the old PPM home might not be accessed by the upgraded instance. For details, see Verify the paths of attachments, report logs, and executions logs are correct.

    -v, or

    --prevalidate

    Validates if your database is ready to upgrade.

    You can run this command anytime.

    Note: This command can only catch some most obvious issues. It cannot guarantee that no database related issues occur during the upgrade.

    -p, or

    --noprevalidate

    Skips the database validation.

    -f, or

    --upgrade_filsystem

    Upgrades the PPM code file system only.

    If you have multiple PPM nodes across multiple physical servers, you need to upgrade PPM code file system on each server, while upgrading the PPM database only once.

    -d, or

    --upgrade_database

    Upgrades the PPM database only.

    -w, or

    --db-password

    Enters the PPM schema password.

    Optional. You can enter it later.

    -l, or

    --install_old_langs

    Installs all the languages that have been installed in the current system to the upgraded instance.

    -i, or

    --installation_locale

    Installs the system language.

    You can use it together with the parameter "-a", but cannot use it if you already use the parameter "-l".

    -a, or

    --add_langs

    Installs extra languages in addition to the system language on the upgraded instance.

    -m, or

    --name

    Specifies the name of a non-primary node server.

    Optional. Use it when you upgrade on a non-primary node server.

Back to top

Best practices for upgrade

Standard upgrade procedures

  1. Before the upgrade, run sh upgrade.sh -v to validate your database.
  2. Before the upgrade, for each node, upgrade your PPM code file system.

    1. Run sh upgrade.sh -n <NEW_PPM_Home> -f to upgrade your PPM code file system to a new <PPM_Home> directory.
    2. Rename the old <PPM_Home> to a different name, for example, PPM_9.63_Backup.
    3. Rename the new <PPM_Home> to the initial <PPM_Home> value.
  3. On the upgrade day, back up your database, and under any of the nodes, run sh upgrade.sh -d to upgrade the database.
  4. Start PPM in the new <PPM_Home> folder.

Verify the paths of attachments, report logs, and executions logs are correct.

As the PPM code file system is upgraded to a new PPM home, to make sure the attachments, report logs, and execution logs can still be accessed by the upgraded instance, you should check the following parameters to verify the paths of these files.

  • com.kintana.core.server.ATTACHMENT_DIRNAME
  • com.kintana.core.server.BASE_LOG_DIR
  • com.kintana.core.server.DISTRIBUTION_LOG_DIR
  • com.kintana.core.server.PACKAGE_LOG_DIR
  • com.kintana.core.server.REPORT_DIR
  • com.kintana.core.server.REPORT_LOG_DIR
  • com.kintana.core.server.REQUEST_LOG_DIR
  • com.kintana.core.server.SCRIPT_DIR
  • com.kintana.core.server.TEMP_DIR
  • com.kintana.core.server.TRANSFER_PATH
  • com.kintana.core.server.VALIDATION_LOG_DIR
  • com.kintana.core.server.WEB_CACHE_DIR

If these parameters are set to the folders under the old PPM home that are mapped with shared folders where these files are actually stored, change the parameter values to mapped folders under the new PPM home.

If these parameters are set to the folders under the old PPM home where these files are actually stored, do either of the following.

  • Recommended way: Do not host all your nodes on a single server. Separate them across multiple servers. Store attachments, reports, and execution logs in shared places and configure the above parameters to point to the shared places.
  • Keep attachments/reports/execution logs in the old PPM home, and in the new PPM home, change the configurations to point to the old places.

    For report and execution logs, in the server.conf file of the upgraded PPM instance, change the above parameters to point to the old locations (e.g. locations under the old PPM home).

    For attachments, change server.conf: com.kintana.core.server.ATTACHMENT_DIRNAME=/<old_PPM_Home>/attachments, and in the Administration Console > DMS Configuration, set the dms.filesys.attachmentDir field to the old location.

Install languages during upgrade

You can install the previously deployed languages after or during the upgrade.

To install the languages after the upgrade, run the kDeploy.sh command.

To install the languages during the upgrade, do the following:

  1. Before the upgrade, run sh upgrade.sh -v to validate your database.
  2. Before the upgrade, leave one node untouched, and for each of the rest nodes, run sh upgrade.sh -n <NEW_PPM_Home> -f -l to upgrade your PPM code file system to a new <PPM_Home> directory and install the languages.

  3. On the upgrade day, back up your database, and under the not-upgraded node, run sh upgrade.sh -n <NEW_PPM_Home> -l.
  4. Start PPM in the new <PPM_Home> folder.

If you have frequent customizations, we have additional recommendations.

  1. Commit your customizations to a source control system.
  2. When you want to deploy customizations, download them from the source control system, and put them in a shared place.
  3. Use kSync.sh to merge customizations from the shared place to the PPM code file system.

Back to top