Skip to main content

Upgrade Overview

This topic is intended for customers who are upgrading from an earlier version of InterSystems IRIS®, InterSystems IRIS for Health™, or HealthShare® HealthConnect. Customers looking to migrate from InterSystems Caché® should see Why Migrate to InterSystems IRIS?Opens in a new tab

Important:

InterSystems recommends that each application be thoroughly tested in the upgraded environment before it is deployed to customers and begins processing live data.

Compatibility Goals

The goal of each release is a smooth upgrade to new and improved functionality with no changes required to existing applications. However, because of error corrections, significant enhancements, or changes to applicable standards, this goal cannot always be met. In this case, InterSystems discloses all identified instances where changes to applications are necessary so that customers can gauge effort required to move to the new release.

You may, after reading about the release-specific changes (linked below), conclude that none of them affect your application. Even in this case, regardless of how robustly designed and how well implemented your application is, there is no substitute for quality assurance test results that confirm your judgement and demonstrate the application remains unaffected by the upgrade.

Before Upgrading

The following upgrade tasks are necessary on all platforms. Perform these tasks before you run the upgrade procedures:

Note:

If you are upgrading to a maintenance release, the tasks marked with an asterisk (*) are optional. However, performing all tasks will ensure optimum performance.

  1. Read the Incompatibility HistoryOpens in a new tab document and make sure to account for incompatibilities as needed.

  2. Read the upgrade chapter in the Release Notes for your product and make sure to account for incompatibilities as needed.

    • Upgrading to This Release in the InterSystems IRIS Release Notes

    • Upgrading to This Release in the InterSystems IRIS for Health Release Notes

    • Upgrading to This Release in the HealthShare Health Connect Release Notes

    Follow any specific recommendations that should be performed before installing.

  3. Read the InterSystems Supported Platforms for the version of InterSystems IRIS to which you are updating — Check that your technologies are supported in the new version of InterSystems IRIS.

  4. Ensure that all source code for the application is available* — After a major upgrade, you must recompile all class code under the new version of InterSystems IRIS or else provide class code that has already been compiled under the new version. Otherwise, you will not be able to run your application after the upgrade. It is recommended that you recompile any routine code.

    Check that you have the code for any classes running in deployed mode (which you can place under deployed mode again when the upgrade is complete), as well as the code for custom routines not generated from classes (*.mac or *.int).

  5. Save custom classes, routines and globals* — On an upgrade, the IRISSYS database is modified. To prevent your own classes, routines and globals in the %SYS namespace from being affected by the upgrade installation, ensure that they have names that begin with “Z”, “z”, “%Z”, or “%z”. All .int and .obj routines (except for Z*, z*, %Z*, and %z*) are deleted from the %SYS namespace when upgrading.

    Similarly, on an upgrade, the IRISLIB, IRISTEMP, and ENSLIB databases are completely replaced.

  6. Save user files* — To ensure that your user files are not deleted or replaced during the upgrade, save them in the install-dir\mgr\User directory, which is the only directory that is not subject to modification during an upgrade.

  7. Decide whether to create an installation manifest* — A manifest is useful for silent installs, as you can invoke the post-upgrade tasks to run as soon as the upgrade is complete, eliminating the need for interactive steps. See Creating and Using an Installation Manifest for more information.

  8. Precompile any user code that runs on startup* — If your application calls any user code at instance startup (using %ZSTART, ZAUTHENTICATE, or other means), you must precompile it on an instance of the new version of InterSystems IRIS and use an installation manifest to install it as part of the upgrade process. If you do not, the instance will fail to start up.

  9. Obtain an updated license key* — See the “Managing InterSystems IRIS Licensing” chapter of the System Administration Guide for more information.

  10. Check system integrity — Run a system integrity check on existing directories to ensure there is no corruption in any of the databases. For more information, see the “Introduction to Data Integrity” chapter of Data Integrity Guide.

  11. Back up the system — Before upgrading, InterSystems recommends that you run a complete backup of your system using your customary full operating system backup procedures. If the upgrade is not successful, you may need to restore from this backup. For information about backups, see the “Backup and RestoreOpens in a new tab” chapter of Data Integrity Guide.

  12. Stop all productions and disable auto-start of productions — If your system is running any productions, follow the instructions in the Stopping a ProductionOpens in a new tab section of the “Starting and Stopping Productions” chapter in Managing Productions.

    It is important to disable auto-start so that you can recompile code before starting productions up again.

Important:

If you have removed all external language gateway configurations, you may encounter validation errors during the upgrade process. These validation errors occur when upgrading from an affected version. They will occur regardless of the version to which you are upgrading. The affected versions include: 2021.1.0, 2021.1.1, 2021.1.2, 2022.1.0, and 2022.1.1.

To prevent these errors, add a single gateway configuration of type Remote that points to the local gateway with an arbitrary port number. For example, you can set the Server Name / IP Address to 127.0.0.1 and set the Port to 1, naming it ForUpgrade. This can be done at any point prior to upgrading and will not impact normal system operation. This configuration can be deleted after the upgrade is completed.

Note:

For users of HealthShare Health Connect or InterSystems IRIS for Health, if your instance was previously migrated from Health Connect/HSAP based on the Caché/Ensemble platform, the components.ini file in your installation directory may have a reference to the database MPRLLIB, which is no longer used by the product. Comment out this reference prior to the upgrade by inserting a semicolon at the start of each line. This will prevent a misleading error message in messages.log saying that this database does not exist.

Example:

;[MPRLLIB]
;Version=15.032.9686
[HSLIB]
Version=2018.1.0
Compatibility_HSAALIB=15.0
Compatibility_HSPILIB=14.0
Compatibility_VIEWERLIB=17.0
Next sectionUpgrading or Modifying Windows
FeedbackOpens in a new tab