General Upgrade Information
This section provides information on upgrading from earlier versions. The ultimate goal of InterSystems is to have a release which can be installed with no, or little, effect on the applications it supports.
A special upgrade procedure is required when upgrading from Health Connect 15.03. For details, see the InterSystems IRIS In-Place Conversion Guide, which is available from the InterSystems WRC Documents
page.
Important Considerations
Health Connect 2020.2 contained the new OpenSSL 1.1.1 security libraries with TLS 1.3, but this library is not in 2021.1. On some platforms we discovered that there were conflicts with older versions of the libraries installed by the operating system or other applications. Consequently, we have removed TLS 1.3 from this release. We will include TLS 1.3 support in a future release in a way that will avoid conflicts caused by having multiple versions of the library installed on the system. Consequently, versions 2020.2 contains an incompatibility with version 2021.1. For containerized instances, upgrading from one of these instances requires an extra step. For noncontainer instances, you cannot directly upgrade from a 2020.2, 2020.3, or 2020.4 instance using the installer.
If you have an instance running any of these versions, see Upgrading from Version 2020.2 for more details.
Compatibility
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 the release-specific changes, 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.
InterSystems recommends that each application be thoroughly tested in the upgraded environment before it is deployed to customers and begins processing live data.
Preview Release
Toward the end of development for each release, InterSystems may make available a preview version of the product to its customers. Notifications of the preview are published on the website and on public blogs. The purpose of this is two-fold:
-
It provides an early opportunity for customers to determine how the changes and enhancement in the release affect existing applications, to report issues found, and verify those issues have been resolved.
-
It also provides early exposure of new features. Customers have a chance to try out the proposed ideas and give feedback on the usefulness of this feature for their business area.
InterSystems strongly encourages customers to plan on obtaining a preview release and to test their application against it.
InterSystems does not support upgrading from a preview version.
One of the goals for preview release is to expose the new release to real-world operating challenges to assure its reliability. Therefore, it is possible, although unlikely, that an unanticipated sequence of events may render Health Connect unresponsive. In this situation, it is extremely important to gather system diagnostic information while in the hung state for InterSystems to analyze. Should an instance of Health Connect become unresponsive:
-
Log in as an administrator
-
In a terminal window, run the IRISHung script in the directory, <install-dir>/bin.
The scripts corresponding to supported systems are:
-
Windows: IRISHung.cmd
-
UNIX®, Linux, AIX, and so on: IRISHung.sh
-
-
Send the resulting output file to the InterSystems Worldwide Response Center
. You can email the file to support@intersystems.com, open a new problem using the WRC Online, or call the Center directly for additional assistance.
C Runtime Requirements on AIX
Health Connect on AIX is compiled using the IBM XL C/C++ for AIX 16.1.0 compiler. If the system on which you are installing InterSystems IRIS does not have the corresponding version of the runtime already installed, you must install it.
Upgrade Specifics
This section contains specific instructions applicable to this transition.
Upgrading Containers
Because a containerized application is isolated from the host environment, it does not write persistent data; whatever it writes inside the container is lost when the container is removed and replaced by a new container. Therefore, an important aspect of containerized application deployment is arranging for data to be stored outside of the container and made available to other and future containers.
The durable %SYS features enables persistent storage of instance-specific data — such as user definitions, audit records, and the log, journal, and WIJ files — when Health Connect is run in a container, allowing a single instance to run sequentially in multiple containers over time. For example, if you run an Health Connect container using durable %SYS, you can upgrade the instance by stopping the original container and running a new one that uses the instance-specific data created by the old one. For information about upgrading, see Upgrading InterSystems IRIS Containers; for detailed information on durable %SYS, see Durable %SYS for Persistent Instance Data.
In this release, the distribution container has a nonroot default user. This improves the security of your container. If you are using a durable %SYS from a 2019.2 or earlier instance with this 2021.1 release, you need to change some file ownerships in the host’s durable directory before running Health Connect 2021.1. Please contact your InterSystems sales engineer or the InterSystems Worldwide Response Center for instructions on changing the file ownerships. If you do not make these changes, the container will encounter an error starting Health Connect.
Classes
InterSystems recommends that customers recompile all their classes contained in each namespace. This will assure that:
-
Subclasses derived from the InterSystems product library will see improved product behavior if a method call results in executing code in its superclass(es).
-
All embedded SQL will use the latest versions of the SQL infrastructure.
-
All projections involved in language bindings will be updated.
-
All generated routines and classes will be updated.
Class compiler version utility
To assist customers in determining which class compiler version a class or classes in a namespace have been compiled with, InterSystems provides two assists
-
Method – $System.OBJ.CompileInfoClass(<classname>)
This method returns the version of the class compiler used to compile this <classname> and the datetime the class was compiled
-
Query – $System.OBJ.CompileInfo(<sortby>)
This query generates a report for the current namespace that includes all classes, the version of the compiler used to compile each one, and the datetime each was compiled. The first argument <sortby> may have the following values:
-
0 – the time the class was compiled
-
1 – the class name
-
2 – the version of Health Connect the class was compiled in
-
Routines
ObjectScript routines do not need to be recompiled after upgrade with the following exception:
-
Routines containing embedded SQL must be recompiled.
Cached Queries
Cached queries are always purged during upgrade. They are recompiled and cached as needed.
Web Services and SOAP
It is not necessary to re-import any Web Service Definition (WSDL) files.
Frozen Plans for SQL Queries
When you upgrade Health Connect to a new major version, existing Query Plans are automatically frozen. This ensures that a major software upgrade will never degrade the performance of an existing query. For performance-critical queries, you should test if you can achieve improved performance. For details, see “Software Version Upgrade Automatically Freezes Plans”
in the InterSystems SQL Optimization Guide.
