Skip to main content

Upgrade Compatibility Checklist for Health Connect 2021.1

This article lists the features of the 2021.1 release that, because of their difference in this version, affect the administration, operation, or development activities of existing systems. Some of the items discussed apply to the underlying Health Connect technology and might not apply to Health Connect users.

Customers upgrading their applications from earlier releases are strongly urged to read the upgrade checklist for the intervening versions as well. Also see General Upgrade Information.

The following sections contain the checklists for Administrators and Interface Developers. Since developers typically administer their own systems, they should also read the section for administrators, especially Issues Upgrading from Version 2020.2, 2020.3, or 2020.4 Due to TLS Changes.


This section contains information of interest to those who are familiar with administering prior versions of Health Connect and wish to learn what is new or different in this area for version 2021.1.

Issues Upgrading from Version 2020.2 Due to TLS Changes

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.

This downgrade of the SSL libraries means upgrading from version 2020.2, 2020.3, or 2020.4 to version 2021.1 requires switching your instance to an earlier version of TLS. In addition to incompatible TLS API changes, there are significant configuration changes between TLS 1.2 and TLS 1.3. You would have to revert API changes and undo multiple configuration settings in order to successfully downgrade from TLS 1.3 to TLS 1.2. Depending on how you deployed your instance, this may or may not be possible. (If you are upgrading from 2020.1 or earlier, you may disregard this section.) You could also defer upgrading until TLS 1.3 support is included in a future release.

Upgrading a containerized instance running version 2020.2, 2020.3, or 2020.4 involves additional steps. When you upgrade the container to version 2021.1, the upgraded container will have no enabled protocols rendering it non-operational. To complete the upgrade, you must enable the protocols, as described below:

  1. Back up your configurations to have a record of which protocols are enabled.


    In release 2020.2 protocol values are stored using TLSMinVersion and TLSMaxVersion. These properties along with the Protocols property are stored and exported as bitmap values, as described in Configuration Definitions.

  2. Perform the container upgrade as usual. When finished, the new container is non-operational.

  3. Enable the necessary protocols recorded in the first step. Once you do, the container is operational once more.


Although Continuous Delivery (CD) releases are usually available in containers only, some customers have received installer kits for server platforms of 2020.2. If you attempt to upgrade one of these instances to 2021.1, the installer will not allow you to proceed. It is possible to do a clean install of 2021.1 and then move your configuration information and databases to the new instance. Contact InterSystems Worldwide Response Center (WRC) for more information about this procedure.

Memory Usage Changes for Global and Routine Buffers

This release improves performance on newly installed systems where the database cache size has not been configured. Under most circumstances, you should carefully configure cache sizes and Configure Huge and Large Pages for optimal system performance. Configuring cache sizes is especially important for live production systems, systems with heavy loads, and systems with multiple instances.

However, when users initially evaluate InterSystems IRIS for Health, they typically run it without configuring the database cache size. The new behavior in allocating memory on systems where cache size has not been configured is (first in 2020.3):

  1. When database cache (global buffers) is unspecified in the configuration, the instance auto-selects 25% of total physical memory for database cache. Previously, the calculation used 12.5% with an upper limit of 1GB (so effectively a flat 1GB for most systems). There is now no upper limit imposed. Additionally, this changes the calculation on Windows systems to be based on physical memory rather than "available" memory so that the behavior is consistent across restarts (and also consistent with Linux and UNIX® platforms).

    While this may result in a large allocation, If the instance isn't used to load a large amount of data, then most of this memory is not touched and, in most operating system environments, will not occupy physical memory. If the operating system has enough large pages available for this memory allocation, InterSystems IRIS will use them, and thus will occupy physical memory. In this case, however, that large page memory is known to be available. Control over use of large pages is available via the memlock configuration parameter.

  2. On startup, if database cache is unspecified, a message "Global buffer setting requires attention. Auto-selected 25% of total memory." will be emitted.

  3. Leaving routine cache (routine buffers) unspecified in the configuration no longer means a minimal amount routine cache (36MB) but instead is taken as 10% of the amount of global buffers with a minimum of 80MB and maximum of 1020MB. (More precisely, it's the number of global buffers multiplied by 8KB multiplie by 10%, so the simple 10% applies as long as only 8KB-size global buffers are used). This applies regardless of whether the database cache was configured or auto-selected as described above. In this way, most systems may be able to select only database cache size and leave routine cache size unaltered.

See Memory Management and Scaling for InterSystems IRIS for more information about memory management.

Cloud Containers Upgrade Checklist — Changes for the Arbiter Container with ISCAgent Using a Nondefault Port

The arbiter is an independent system hosting ISCAgent for mirror members (see Arbiter). By default ISCAgent uses port 2188. In previous releases you could specify a nondefault port by arguments such as $IRISSYS/ 2000, but in this release you must replace these arguments with -p 2000 to use port 2000. Using arguments other than -p will be ignored and the container will run with port 2188 (first in 2020.3).

InterSystems Cloud Manager (ICM) Upgrade Checklist

Only InterSystems API Manager (IAM) 1.5 and Later can be Used with ICM

In this release, ICM can only be used with the InterSystems API Manager (IAM) version 1.5 or later.

If you were using the Rancher or Weave Scope monitoring solutions with a previous ICM version, with this version you need to deploy these manually or use generic ICM commands.

The parameters in CPF have changed from the beta version. This change only impacts beta users of ICM.









JDBCGatewayPort Change

If you were overriding the JDBCGatewayPort parameter using the JSON field "JDBCGatewayPort", you should delete that parameter and instead do so directly in their custom CPF file (pointed to by "UserCPF"). For example:

%JDBC Server=JDBC,,53773

(first in 2020.3)

Installation Upgrade Checklist

Security Upgrade Checklist — Cannot Import Encryption Settings from Previous Releases

With this release, you cannot import security settings which were exported using ^SECURITY from a previous release; you must use the Management Portal to set the encryption settings. Also, if you export the system settings from this release, the encryption settings are not included; consequently, if you export system settings from this release and then import them into another instance of this release, you also must use the Management Portal to set the encryption settings.

Change to Default SuperServer Port

In this and future releases, the default SuperServer port is 1972. If this port is not available, then the default port will be 51773 or the next free port after this. This change was first in release 2020.3. In releases before 2020.3, the default SuperServer port was 51773.

If you are upgrading a system using the InterSystems Cloud Manager (ICM) and relied upon 51773, you may need to add the following override to your JSON defaults:

  "SuperServerPort": "51773"

If you are upgrading an instance of an earlier release with full installation kits on a server platform, this change does not impact you. The SuperServer port from the instance is preserved through the upgrade.

Installation Leaves Duplicate ODBC Driver on Windows

To allow both Caché and InterSystems IRIS for Health to both exist on a system, the installer should not remove the Caché ODBC driver. On Windows a new InterSystems IRIS for Health install may result in a duplicate entry for "IRIS ODBC Driver" in add/remove programs applet. You can safely uninstall the older "IRIS ODBC Driver".

How the Gateway Installer Treats an Existing CSP.ini File

In environments where a third party Web Server is running remotely, the Web Gateway installer tried to modify some settings in CSP.ini which could result in unwanted changes in terms of service accessibility. A review of the configuration after each upgrade was always recommended. In this release the Web Gateway installer will not modify an existing CSP.ini in any way. For details on configuring the web server and Web Gateway, see Configuring the Web Server and Web Gateway (first in 2020.2)

ISCAgent in Containers Upgrade Checklist

ISCAgent is now started automatically and is started on port 2188 by default in Health Connect containers. You can disable ISCAgent with "--ISCAgent false". You can control the port used with the new syntax "--ISCAgentPort <port>" instead of the previous syntax "--before /home/irisowner/irissys/ <port>".

Journaling Upgrade Checklist — ^JCONVERT Changes

^JCONVERT now creates and processes common journal files in the enhanced format, which supports long strings. It has a new prompt to control whether common journal files are created in the enhanced format or in the previous format. If you need to create common journal files that can be read by ^%JREAD or ^JCONVERT from a previous version, you must specify that you do not want the enhanced format.

Monitoring Upgrade Checklist — New Metrics in %Monitor.Process

This release has new metrics from %Monitor.Process and the counter index numbers have changed. The new metrics are MONBLKWAIT, MONBLKWAKE, MONMEMALLOC, and MONMEMFREE.

Tasks Upgrade Checklist — Task Termination Changes

In previous releases, tasks that were terminated by shutdown were marked as suspended. In this release, they are not marked as suspended by default. If you want tasks terminated by shutdown to be marked as suspended, set the new SuspendTerminated property.

Interface Developers

This section contains information of interest to those who have designed, developed and maintained productions running on prior versions of Health Connect. Since interface developers typically administer development system, developers should also read the previous section for administrators.

.NET Gateway Changes

The Interoperability .NET Gateway now supports Core 2.1 version and the default value is now 4.5 instead of 2.0. If your application is dependent on the default value and needs the 2.0 version, you must explicitly specify it (first in 2020.4).

X12 Schema Changes

This release includes additional keyfields in X12 schemas. In some places unnecessary schemas or incorrect loops have been removed. If your code relies on the existence of these incorrect elements of the schema, you must revise it (first in 2020.4).

Export Can Now Include Base Schemas

The Interoperability Production Code Export will now include custom base schemas if appropriate. The query EnumerateVDocSchemas now return also returns the Base value.

Error Checking on Timeout Setting

This release adds error checking to the timeout settings in the production configuration page. If the requested timeout interval exceeds 1 hour, the page treats it as an error and does not allow the setting. Since it is extremely unlikely that you would want to delay the instance shutdown for an hour, this is most likely an error. However, if you really need such an extended time to wait for the production component to stop, you can still set shutdown to be longer than an hour using a script that calls an Ens.Director method (first in 2020.2).

System Defaults Setting Checks Values

In previous releases, invalid values in the default system settings would not be checked until the values were applied in a production. This change ensures that system default settings are valid when specified. If you have invalid system default settings that were saved by a previous release, saving them in this release removes the values. Settings are validated by calling the IsValid() method of the appropriate class. If no IsValid() method is defined, then no validation is performed (first in 2020.2).

Activity Monitoring Changes

The activity monitoring pages (see Monitoring Activity Volume) now distinguish between days based on the combination of UTC and local time. This means when querying the Ens_Activity_Data.Days table for a specific TimeSlotUTC or TimeSlot it is necessary to check if there are 2 rows per unique TimeSlotUTC or TimeSlot : One row when TimeSlot is different from TimeSlotUTC and one row when TimeSlot is the same as TimeSlotUTC. The actual value is the sum of these two rows (first in 2020.3).

Creating Interoperability Namespace with %Installer Changes

In previous releases if you used the %Installer.Installer class to make an interoperability production enabled namespace, it would set the node to a fixed portal URL. It now sets it to the empty string, which is the typically desired behavior. If you wish to set the node to a fixed portal URL, you can do this with the following:

 Set ^%SYS("Ensemble","InstalledNamespace",tNSUpper)="<fixed-url>"

(first in 2020.3)

Removal of Deprecated Java Business Hosts, Use PEX Instead

Java Business Hosts was deprecated in release 2019.3 and has been removed from this release. PEX replaces the Java Business Hosts feature. For information on migrating existing Java Business Hosts productions to use PEX, see the community article Migrate from Java Business Host to PEX. For a description of PEX, see PEX: Developing Productions with Java and .NET (first in 2020.3).

Custom Business Process Accessing %MessageSent or %MessageReceived Changes

In this release if custom business process code accesses the internal %MessagesSent or %MessagesReceived array then the class parameter SKIPMESSAGEHISTORY needs to be overwritten and set to 0 (first in 2020.3).

Message Viewer Changes for XML Objects

To improve efficiency in displaying XML-enabled objects, large XML objects may not be fully serialized in the message viewer Contents tab. To see the fully serialized value, you must now use the Full Contents link. For more information, see “Changing the Character Limit for XML Messages in the Contents Tab” (first in 2020.3).

PEX Class Changes

The PEX class hierarchy has changes to reduce errors when users overloaded methods rather than overrode them. In this release, all methods that should be overrode by user code are marked as abstract. If you define a subclass and do not override these methods, you will get a compile error. In previous versions, the compile would succeed but the user callback code would not execute correct because the default code would be called instead. The documentation stated that these methods were abstract and needed to be overridden but it was not enforced by the code (first in 2020.3).

PEX Library Changes

This release uses a different serialization library; it no longer uses the jackson library. Consequently, your production settings should point to the intersystems-utils-3.1.0.jar provided and not to the jackson library. If your code references the jackson library, you must update it or install the jackson library (first in 2020.3).

RecordMap Error Handling Changes

The error detection for the RecordMap service is now stricter with the ParseOnly flag selected. In previous releases, errors would be ignored with ParseOnly even if the AlertOnError flag was enabled. In this release, if the AlertOnError flag is enabled and a record fails validation, then an alert is sent even if ParseOnly is selected (first in 2020.3).

X12 Changes

There are several changes in how X12 documents are handled (first in 2020.3):

  • Change handling poorly formatted documents — improved handling of certain poorly formatted documents means that the issues with these documents are logged in the Event Log and then handled by sending an appropriate Reply document, rather than these documents resulting in the service failing and documents not being deleted. If you are relying on service failures to identify flaws in the X12 document, you should look at the Reply document instead.

  • Validation change — this change now includes code values in validations that were previously ignored. If you are using validation with the flags r, u, or t, then some errors that would have been missed in previous versions will now be caught. This change also adds a new segment, CTX-11, to the validation style schema for HIPAA_5010:999. This does not impact any code for setting the CTX-5() segment, but does mean that if a user has code for getting values from the CTX segments, and the document they are inspecting has a Business Unit Identifier, then that CTX segment will have to be accessed using path 2000().2100().CTX-11 instead of the 2000().2100().CTX-5() which is used for Segment Context. This makes no difference in either setting or getting values using the new style schema.

  • Change in allowed order of segments — this change allows segments to be in any order permitted by the standard rather than requiring them to be in the specific order as listed in the standard. This allows valid documents to pass validation where in previous releases, they would have failed. This change should not require any change in your code unless you were using the wrong property path to get the value from some segment to workaround this incorrect behavior, in that case you need to switch to using the correct property paths.

XML VDoc Character Escape Changes

In XML VDoc, when you use setValueAt() to set the value at a node, you can specify a value that consists of mixed content (that is, a value that consists of a mix of element and text nodes). This change ensures that if a < (left-angle) character appears without a closing XML /> or </, then the < is treated as normal text and is XML escaped (replaced by &lt;). In previous releases, this would have been treated as mixed content and would have caused an error. If you have code to handle this expected error, you should examine this case. See “Using Mixed Content When Setting Paths” (first in 2020.3).

GenericService Return Value Change for OneWay

Prior to this change for any custom code that subclassed EnsLib.HTTP.GenericService and had enabled OneWay an "HTTP/1.1 200 OK" would be returned to the caller. This is now corrected to ensure returning an "HTTP/1.1 202 Accepted" to the caller.