Upgrade PPM - Oracle

This topic provides detailed steps to upgrade PPM with an Oracle database to the latest version.

Upgrade PPM with Oracle database

You should use the sh upgrade.sh command to upgrade PPM.

To upgrade PPM with an Oracle database:

  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

    -o, or

    --on_current_home

    Upgrades PPM on your current PPM system.

    The current PPM must be at version 9.61 or later.

    This parameter overrides the "-n" parameter. Do not use the "-o" and "-n" parameters together.

    Tip: We recommend that you upgrade PPM to a new <PPM_Home> folder, and use the current PPM system as a backup. For details, see -n, or --new_PPM_Home.

    -n, or --new_PPM_Home

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

    You cannot use this parameter if you already use the "-o" parameter.

    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 "-a" parameter, but cannot use it if you already use the "-l" parameter.

    -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

The following are the recommended 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

Troubleshooting

If your PPM is installed with the Oracle database 19c running in CDB mode, the following error may occur during the upgrade:

"ORA-38824: A CREATE OR REPLACE command may not change the EDITIONABLE property of an existing object."

To resolve this issue:

  1. In the SQL Plus window, run the following query:

    Copy code 
    select 'alter ' || object_type || ' ' || object_name || ' editionable;' from user_objects where editionable = 'N'

  2. If no result is returned, close the SQL Plus window.

  3. If a query is returned, for example: alter procedure <procedure-name> editionable, then run the returned query in the SQL Plus window.

Back to top

See also: