Upgrading with a partial backup is the recommended upgrade strategy for any environment where retaining the message archive is not critical. It involves a standard upgrade with a backup of the non-message-related sub-directories of the datastore.

The main advantage is that the backup size should be a small percentage of the total datastore size because the message-related directories make up the majority of the total size. The main disadvantage, however, is that any messages that are live within Rhapsody (traversing routes, or on any route or communication point queues) would not be recoverable in the event of an upgrade failure.

Performing the upgrade during off-peak hours especially helps this strategy because there should not be as many in-flight messages to drain. However, Rhapsody should still be drained of live in-flight messages, as well as any route or communication point queues. The alternative is to have a plan ready to be able to find and resend these in-flight messages in the event of an upgrade failure.

Requirements
  • Sufficient disk space for a partial copy of the datastore (excluding message-related directories).
  • Sufficient downtime for:
    • Rhapsody engine to be drained of messages and/or a plan to be able to find/resend in-flight messages at the time of shutting down Rhapsody.
    • Copy to be performed
    • Upgrade to be performed.
    • Post-upgrade tasks to be completed.
Upgrade Type Standard.
Backup Type
  • Inclusion list (sub-directories within the datastore to be copied): backup, charactermap, cleanup, cleanuptrace (optional), config, idgeneration, lib, logs (optional), lookuptables, modules, monitoring, notifications, persistentmapstore, startup, store, statistics (all engine statistics that are viewable in the Management Console), users.
  • Exclusion list (the message-related tables to be excluded from the datastore copy): commpoints, filters, index, messageevents, messagestore, messagetables, queue, tracking, transaction.
Rollback
  • Reinstall original version of Rhapsody engine and IDE.
  • Use original wrapper files (to retain memory settings) and log4j file.
  • Point Rhapsody to copied datastore.
  • Initiate message resend plan.

Before You Begin

It is strongly recommended that you carry out the upgrade on a test or development server before you upgrade your production server.

Complete the following tasks before you upgrade Rhapsody:

  • Check you meet the System Requirements.
  • Read the upgrade caveats.
  • Obtain the correct licenses before installing Rhapsody.
  • Ensure installation files for the original Rhapsody version are present (in case of failure and a rollback is required).
  • Ensure installation files for new Rhapsody version are present (for the upgrade).
  • If not already done, check the size of sub-directories on the inclusion list. To find the location of the datastore, check the value of the InitialisationService.dataDirectory property in the rhapsody.properties file (located in <Rhapsody installation directory>/rhapsody).
  • If not already done, calculate an estimate of the time to perform the copy. This could be done by performing a copy in a non-production environment and extrapolating the time, or discussing this with your infrastructure team.
  • If you have not already done so, choose the location of the backup datastore.
  • Make copies of your wrapper files, log4j.properties file and java.security file, and move them to a backup location.

Preparing for an Upgrade

To prepare Rhapsody (the Rhapsody Engine and Rhapsody IDE) for upgrade:

  1. Stop all input communication points.
  2. Ensure that all messages on the route have completed processing.
  3. After all the messages are processed, stop all the output communication points and routes.

  4. Stop the Rhapsody engine.

    Because of changes to the Data Validation Service in Rhapsody 6.3, ensure you perform a clean shutdown of the engine (stop all the components before shutting down the engine) before upgrading from versions of Rhapsody before Rhapsody 6.3.

  5. Uninstall the Rhapsody IDE.

    Under certain circumstances, side-by-side installations of older and newer versions of Rhapsody IDE are possible. Refer to Rhapsody IDE's Upgrade Recommendations for details.

  6. Enable Rhapsody safe-mode so that a successful upgrade can be verified without starting message flow (as these messages would not be recoverable if a rollback must be performed).

    • Set the StartupService.safeMode property to true in the rhapsody.properties file and save it.

  7. Perform copy operation of the sub-directories within the datastore on the inclusion list to a separate location.

Upgrading Rhapsody

To upgrade Rhapsody:

  1. Obtain the Rhapsody installers from Rhapsody Support.

  2. Upgrade the Rhapsody engine using the Rhapsody engine installer:

    Environment

    Refer to...

    Windows®

    Installing the Rhapsody Engine on Windows®

    *nix

    Installing the Rhapsody Engine on *nix

    If you select the Cancel button during the upgrade, you may not be able to start your engine.

  3. Install Rhapsody IDE in a Windows® environment using the Rhapsody IDE installer. Refer to Installing Rhapsody IDE for details. Ensure you do not configure the installer to start the engine automatically upon upgrade.

  4. Manually copy any changes you have made to the new wrapper files and log4j.properties file from your backup copies.

The Rhapsody engine and Rhapsody IDE can be upgraded in any order.

Post-upgrade tasks

Verifying the Upgrade

To verify the overall success of upgrade:

  1. Start the Rhapsody engine. If using Windows®, ensure the Rhapsody Service Monitor icon indicates that the Rhapsody engine is running.
  2. Double-click the Rhapsody Service Monitor icon, or enter http://<server>:<port>/rhapsody in your browser to access the Management Console.
  3. Log on to the Management Console as an administrator. The administrator password remains unchanged after installing the upgrade.
  4. Ensure that the version number in the title bar is <majorVersion>.<minorVersion>.<servicePack>.<build>.
  5. Start Rhapsody IDE and connect to the Rhapsody engine as an administrator.
  6. If applicable, register and license your engine. Refer to  Registering and Licensing Rhapsody for details.

If the upgrade is:

  • Successful: 
    1. Stop the Rhapsody engine.
    2. Disable Rhapsody safe-mode by setting the StartupService.safeMode property to false in the rhapsody.properties file and save it.
    3. Restart the Rhapsody engine.
  • Unsuccessful and rollback is necessary, refer to Rolling Back.

Roll-back

If a failure occurs during the upgrade, a roll-back will likely be necessary. This roll-back would not require a new license.

To perform roll-back to the previous version of Rhapsody:

  1. Uninstall your newly installed engine. Refer to Uninstalling Rhapsody for details.
  2. Delete the current datastore.
  3. Make a copy of the backup datastore and move it back to the data directory.
  4. Reinstall the previous version of the engine. Ensure you set the Data Directory Location in the engine installer to the location of the backup datastore.
  5. Reinstall the previous version of Rhapsody IDE.
  6. After re-installation, stop the Rhapsody engine if it is running.
  7. Use the original wrapper files and log4j.properties file (and any other files that had customizations as backed up during pre-upgrade steps).
  8. Restart the engine.