Skip to main content

Upgrade Compatibility Checklist for InterSystems IRIS 2019.1

This article lists the features of InterSystems IRIS® 2019.1 that, because of their difference in this version, affect the administration, operation, or development activities that have changed from previous versions.

General Upgrade Information

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.


This section contains information of interest to those who are familiar with administering prior versions of InterSystems IRIS and wish to learn what is new or different in this area for version 2019.1. The items listed here are brief descriptions. More complete descriptions are in the following section.


This section contains information of interest to those who have designed, developed and maintained applications running on prior versions of InterSystems IRIS. Since developers typically administer development system, this section also includes administrative upgrade issues.

The items listed here are brief descriptions. In most cases, more complete descriptions are available elsewhere in the documentation.

API Management Changes

Replaced Class that Implements API Management

The package %Net.APIManagement has been removed. Instead, see the new class %REST.API, which provides similar options. The %REST.API class is not formally supported in InterSystems IRIS 2019.1, but is planned for formal support soon.

Business Intelligence Changes

Change in %GetCubeMeasures Return Values

The second item in the %GetCubeMeasures() output list should be the caption. In previous releases, for calculated measures, it was returning the name not the caption as the second item. In this release, the second item correctly contains the caption. If your code relied on the name being returned in the second item for calculated measures, you should update your code.

Recompile All Cubes

When you upgrade to this release, you must recompile all Business Intelligence cubes. There are two reasons for this:

  • In this release, the %DeepSee.Generator has improved the way deletes are handled when synchronizing. In order to incorporate this change, you must recompile all Business Intelligence cubes. If you do not recompile a cube, attempting to build this cube will encounter an error.

  • In previous releases, compiling %DeepSee.Generator would not catch the error of including a list-based level that also defines a range expression. Consequently, these constructs would cause an error during build causing missing data in the cube. In this release, these errors are found during compile time and the user can correct the error.

Multicompile Setting and Asynchronous Operations

If you have disabled the Business Intelligence work queue manager’s ability to process jobs in parallel, any asynchronous business intelligence operation may fail. Since InterSystems recommends that you always enable the Business Intelligence work queue manager to process jobs in parallel, you should not encounter this problem.

Asynchronous Business Intelligence operations include %DeepSee.Utils:%BuildCube (asynchronous mode, the default), %DeepSee.ResultSet:%ExecuteAsynch, and Business Intelligence REST calls. If you have set the /multicompile qualifier to 0, you may see the following error after attempting an asynchronous Business Intelligence operation:

ERROR #5001: Can not detach from work queue which is not using workers

To enable parallel processing by setting the /multicompile qualifier, enter a command such as the following

do $system.OBJ.SetQualifiers("/multicompile=1", 1)

For more information on the /multicompile qualifier, see Using the Work Queue Manager.

Removal of %DeepSee.TaskMaster Agents and Associated Methods

As part of the transition to Work Queue Manager %SYSTEM.WorkMgr agents, Business Intelligence %DeepSee.TaskMaster agents have been removed in this release. As a result, there are no longer low or high priority agents, as all agents are managed by %SYSTEM.WorkMgr and are created automatically when needed. In addition, associated methods like %SetAgentCount() and %GetAgentCount() have been deprecated.

Interoperability Production Changes

Interoperability Message Bank Changes

In previous releases, HTTP, REST and SOAP Generic messages were sent to the Message Bank as Ens.StreamContainerOpens in a new tab and did not provide the HTTP headers. This change causes these messages to be sent to the Message Bank as an XML projection and includes the HTTP headers. Unchanged from previous releases, you cannot resend these Generic messages. If you have code that assumes that these messages are stored as StreamContainer , you should modify the code.

Java Business Hosts Changes

The Java Business Hosts BusinessOperation OnInit method has been enhanced and the method arguments have changed. The OnInit method now gets information about the production though a Production object returned in a parameter. To enable this, you must now specify credentials when creating the BusinessOperation in the same way that you specify them for the BusinessService.

The new Java method is:

public class javahostsOperation implements BusinessOperation {

  public boolean OnInit(Production arg0) throws Exception {
  // TODO Auto-generated method stub
  return false;

The Production object is passed to the BusinessOperation OnInit method in the same way that it is provided to the BusinessService OnInit method. In InterSystems IRIS 2018.1.1 the OnInit method parameter is an array of strings that provides only some of the information available from the Production object.

If you have Java Business Hosts code from the previous version, you must update the code to use the new method parameter.

There are the following other changes in Java Business Hosts:

  • In order to access the Java Business Hosts portal page, the user needs either the %Ens_JBH or %Ens_Code privilege.

  • In previous versions, Java Business Services and Operations always used Ens.StreamContainer messages within the production. In this release, they use Ens.StringContainer messages for strings unless the string is very large. In that case, they use Ens.StreamContainer messages.

Change to API Testing Presence of Interoperability Features

The class %CSP.Util.EnsStart has been removed. Any application calling the method ##class(% CSP.Util.EnsStart).IsEnsembleInstalled() must be changed to call ##class(%EnsembleMgr).IsEnsembleInstalled(). Note that on InterSystems IRIS, this method will always return true.

Change to Ens.Util.XML.SecuritySignature Class

In previous releases, the Ens.Util.XML.SecuritySignatureOpens in a new tab class extended the %XML.Security.SignatureOpens in a new tab class. In this release, it no longer extends this class. You can continue to call ValidateSAML() in Ens.Util.XML.SecuritySignatureOpens in a new tab, but if you called any other methods in Ens.Util.XML.SecuritySignatureOpens in a new tab, you must change your code to call %XML.Security.SignatureOpens in a new tab directly.

Queue Wait Time Calculation Change

To improve the efficiency of the Ens.MonitorService, this release changes the way the queue wait time is calculated. For business hosts with a pool size of 1, the amount of time the active message has taken to be processed is now counted as part of the queue waiting time. In rare cases, this could change how InterSystems IRIS behaves in responding to the QueueWaitTime alert setting.

SOAP Outbound Adapter Clears HTTP Header

The SOAP Outbound Adapter should clear the SOAP client HTTP headers after completion of the SOAP call. In previous releases, it was only clearing the HTTP headers after a successful call and was not clearing them after a failure. In this release the SOAP Outbound Adapter clears the SOAP client HTTP headers after each Invoke, InvokeMethod or InvokeWithSOAPBody call, whether the call succeeds or fails. If you are using the SOAP wizard to generate the class, there is no compatibility issue. If you have created custom code that uses the SOAP Outbound Adapter and relied on the HTTP headers not being cleared, you should modify your code to ensure that the headers are set correctly before each call.

Change in Default Behavior for Validation in Add Router Wizard

In this release, the validation default has changed when creating a new router with the Add Router wizard. This does not impact any existing routers that were created with the previous wizard. In the previous release, if you left the validation field empty for routers that support validation, such as an X12 router, validation was disabled. In this release, if you leave the field blank in the wizard, validation is set to the value specified in system defaults, if one is specified. Otherwise, it gets the default value, which enables validation for routers that support it. The wizard has a new check box to disable validation.

Developers Using Studio Need Additional Privilege for Stored Procedures

In this release, developers using Studio will need execute privileges on stored procedures for some actions. This privilege is Ens_Config.Production_Extent. If a developer has the role %EnsRole_Developer or %EnsRole_Administrator, then the developer has this privilege

Change in Management Portal Display for Settings in Custom Category

If a user defines a property in a Business Host or Adapter class, they can also include it as a setting, by adding it to the SETTINGS parameter. Within the SETTINGS parameter, if the property name is followed by ":" and additional text, that second piece is used as the category under which the settings will be displayed in the Settings tab on the Production Configuration page. There are some predefined categories, such as Info, which is displayed as "Informational Settings", and Alerting, which is displayed as "Alerting Control", but the user can also create a custom category. In previous releases, if the category specified for a setting was a custom setting, the word "Settings" would always be appended to the specified name as the display category. In this release, the category will be displayed as specified without “Settings” appended to it. If you want to have the word Settings included in the category as displayed, you should add it to the category in the SETTINGS parameter.

InterSystems Cloud Manager (ICM) Changes

Change in Behavior When Reprovisioning AWS Volumes

In this release when you are provisioning on AWS, the ICM creates the WIJ and journal volumes only on nodes running complete InterSystems IRIS systems and they are not be created on Shard Master Application Server (AM), Shard Master Data Server (DM), Shard Query Server (QS), and Shard Data Server (DS) nodes. In previous releases, the ICM created WIJ and journal volumes on all nodes. When upgrading to this release, these unused nodes will be deleted. Typically this is not a problem, but, if you made use of these volumes on some other type of node and stored data on them, you should save this data before these volumes are deleted by the upgrade.

Rancher Monitoring Requires Authentication

In previous releases, you could use Rancher monitoring without authentication, which InterSystems did not recommend because it is an insecure configuration. In this release, if you want to use Rancher monitoring, you can only use it with authentication.

Cannot Override Reserved Keys

In previous releases, you could override reserved keys in definitions.json. This caused unpredictable results. In this release, reserved keys can only be specified in defaults.json and cannot be specified in defintions.json. The reserved keys are:

  • "Label"

  • "Tag"

  • "Namespace"

In most cases overriding a reserved key causes the deployment to fail. In some cases, overriding "Namespace" did not cause a fatal error and the deployment succeeded. Although these deployments may continue to work after an upgrade, you should remove the override of the reserved key. Reprovisioning without removing the override will encounter an error.

Must Use Datastore Cluster for vSphere Storage Allocation

There are significant advantages in using a datastore cluster over using a bare datastore. Although the previous version allowed you to specify a datastore not in a cluster, in this release you must specify a datastore cluster. If you have "Datastore" in defaults.json or definitions.json, you must change it to "DatastoreCluster". If your datastore was not in a cluster, you must create one for it.

Device Letter Assignments Changed

Device names (for providers other than PreExisting) have all been shifted one letter forward in the alphabet to make room for the Docker block storage device. If you have explicitly included a device name in code or configuration you should update the device name.

iris-main Will Terminate After Errors

In previous releases, iris-main would continue to execute after some errors. In this release, iris-main correctly terminates when a command or script it calls returns a non-zero exit status.

Language Binding Changes

Java Native API Illegal Integers Now Throw Exceptions

In previous releases, the client would convert illegal integers into a valid integer value. For example “123ABC” would be converted to 123 and “Hello” would be converted to 0. This causes problems because the server would return errors for these illegal integers. In this release, illegal integers throw exceptions in the client. You may need to modify your code to handle these exceptions.

Inconsistent XEP Schemas Now Throw Exceptions

Serial classes cannot have IDkeys, but, in previous versions, a class annotated with both @Embedded and @Id did not throw an exception. A schema with a class annotated in this way would not have worked correctly, but it would not have thrown an exception. In this release, it throws an exception.

Change with Java and .NET XEP Generated Id Property

In this release, InterSystems IRIS includes a generated id property in the schema to solve a problem with bulk upload. This should not cause a compatibility problem in most cases. If your schema runs into a problem caused by this change, you can remove the id notation.

Changes to .NET Entity Framework Function Names

The following Entity Framework classes are renamed in this release:

  • CacheFunctions renamed to IRISFunctions

  • CacheMigrationSqlGenerator renamed to IRISMigrationSqlGenerator

  • CacheTableExistenceChecker renamed to IRISTableExistenceChecker

Rare Change in Projection of XEP Classes

In rare cases, importing an XEP schema produces a different class hierarchy in this release, specifically determining whether the class is serial or persistent. In these cases, the class projected by the previous release was incorrect.

Monitoring Changes

Remove Deprecated WMI and BMC Patrol Monitoring

This release excludes support for using the BMC Patrol monitoring tool and the Windows Management Integration (WMI) monitoring.

System Statistics Changes

To improve performance of large-scale systems, the statistics reported by the system utilities have changed. In most cases this will not cause any compatibility issues; however, if your code explicitly examines the statistics output for specific data, you may have to update your code to adjust for these changes. The following minor changes are visible:

  • The ^GLOSTAT utility no longer offers detailed block type statistics and no longer asks the question "Should detailed statistics be displayed for each block type? No =>".  Additionally a bug is corrected in ^GLOSTAT that caused remote reads and remote cache efficiency to be incorrect (usually zero).

  • The Management Portal System Dashboard is enhanced to show private global references and updates and WIJ writes, in the same way that ^GLOSTAT does.  The detailed block type statistics page, 'Disk and Buffer Statistics', is no longer available.

  • The ability to zero statistics (from ^GLOSTAT and the Management Portal) is not available.  This capability is not compatible with the more efficient statistics collection.  

  • The class SYS.Stats.Disk, which accesses the detailed block type statistics, reports all as zero; the class reference is updated to reflect this. The class SYS.Stats.Global, which accesses the main global statistics, continues to function as before and is enhanced to include write image journal writes as a property called 'WIJWrites'. Additionally, the internal class SYS.Metrics was previously exposed (unintentionally) as a public API; it is now properly marked as internal-only and it no longer reports values for detailed block type statistics.

  • The WS-Monitoring and BMC Patrol facilities that report the detailed block type statistics, report them zero or null.  BMC Patrol, WMI, and SNMP monitoring facilities lock counts (total, success, and fail) also report as zero.

  • The iris stat -g1 is updated to include more fields that were previously only available in ^GLOSTAT displays.  Some statistics that were available via the iris stat -c option are no longer available.


%Monitor.Process, MONLBL, PERFMON and similar performance monitoring tools are unaffected by this change and maintain their own counters.

Object Changes

MSM-Activate Support Removed

This release removes support of MSM-Activate. If your code uses MSM-Activate, it will not be able to connect to an InterSystems IRIS server. You must replace the MSM-Activate code with other code to connect to the server.

Attempting to Round %Integer in %xsd Package Now Causes Error

In previous releases, if you attempted to assign a non-integer number to an integer in the %xsd package, it would not consider it an error but would silently truncate the value to an integer. This is not the expected behavior. In this release, InterSystems IRIS treats this as an error. If your code relies on the previous behavior, you should update it to avoid this error condition.

ReadLineIntoStream Returns Different Value At End

If you call the %Stream ReadLineIntoStream() method on a stream with AtEnd set, it now returns an empty string "" at the end. In previous releases, it returned a newly created %Stream.TmpCharacter stream that contains no characters. If your code relied on the previous behavior, you must update it.

%Set(key,value,"null") and %Push(value,"null") Changes

In this release, the behavior of the %DynamicArray and %DynamicObjects %Set(key,value,"null") methods and the %DynamicArray %Push(value,"null") method has changed when the value is not an empty string. In previous releases, these methods signalled <ILLEGAL VALUE> if 'value' was not "". In this release, these methods have the following behavior:

  • If 'value' is the empty string, then the JSON value 'null' is assigned to the keyed element.

  • If 'value' is not the empty string then that value is assigned to the keyed element of the Array/Object without any conversion and no error is signalled.

If your code, depended on the <ILLEGAL VALUE> being signalled, you must modify your code to test if the keyed element has a value other than "", and, in that case, signal the error.

Change %Save Ordering to Ensure Predictability

This change revises the internal algorithm determining object graph linearization during a %Save to remove a random element, ensuring that identical graphs of connected objects will be persisted in a consistent order. User code should make no assumptions about this order, as it is dependent on the internal implementation of %Save which may change in future releases.

Security Changes

^EncryptionKey Routine Menu Changes

The ^EncryptionKey routine has new menu choices for InterSystems IRIS 2019.1 that may require changes to scripts for previous versions. The changes in the menus are primarily associated with support for storing keys on a KMIP (key management interoperability protocol) server and support for modifying the encryption status of a database. Changes include:

  • If you have configured a connection to a KMIP server, there is an additional choice (5) in the main menu, Manage KMIP server.

  • If you have configured a connection to a KMIP server, then, in the Database encryption > Activate database encryption keys menu, the options differ from the menus in previous versions; there are multiple numbered options instead of only the prompt for the key file.

  • If you have configured a connection to a KMIP server, then, in the Database encryption > Configure InterSystems IRIS startup options menu, there is a Unattended key activation with a KMIP server choice and submenu.

  • In the Database encryption menu, there is a Modify encrypted status of existing database choice and submenu.

  • If you have configured a connection to a KMIP server, then, in the Data element encryption > Activate data element encryption keys menu, the options differ from the menus in previous versions; there are multiple numbered options instead of only the prompt for the key file.

SQL Changes

Frozen Plans on Upgrade

When you upgrade InterSystems IRIS 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.

New Default for Parallel Queries Can Change Order

In this release, the default is to enable automatic parallel execution of queries (where supported) in new installs. Consequently, queries without an ORDER BY clause may return results in a different order than the same query would in previous versions. To guarantee the order of results for any query, include an appropriate ORDER BY clause. If your code assumes the order of results of a query without an ORDER BY clause you may run into this problem. If you are using an InterSystems IRIS instance upgraded from version 2018.1, you will not run into this problem because the upgrade retains the previous setting of not using automatic parallel queries. But, if you transfer your code to a system with a new install, you could run into this problem.

SQL Default Precedence Changed for New Installs

In this release the default SQL precedence is set to ANSI operator precedence on new installs. If your code is depending on strict left-to-right precedence and you are running on an install upgraded from an earlier system, there is no problem. But, if you transfer your code to a system with a new install, you can set the precedence to strict left-to-right by calling $system.SQL.SetANSIPrecedence(0). If you want to change an upgraded system to use ANSI precedence call $system.SQL.SetANSIPrecedence(1).

SQL.JDBC Throws Error for Illegal Date Time Value

The JDBC 4.1 standard does not allow Set/Get Date to Time and Time to Date columns. Although the previous release of InterSystems IRIS server correctly produced an exception on the set, it did not produce an exception on the get, and the client did not validate either. This release validates both get and set and throws an exception 17004 "Invalid column type". If your code explicitly tests for the "Field validation failed" exception text that was formerly returned for the set or relies on the get to not generate an exception and return a dummy value, you should update your code.

SQL.JDBC May Use Fast Insert for SQLType Storage

In this release, fast insert is enabled by default if the platform supports it. Using fast insert with the SQLType storage of literal values should not have any compatibility impact for most users.

You can explicitly disable fast insert by setting the ConnectionOption property to 1 or 0, as shown in the following example:

  IRISDriver driver = (IRISDriver) Class.forName("com.intersystems.jdbc.IRISDriver").newInstance();
  String url="jdbc:IRIS://localhost:1972/user/";
  Properties p = new Properties();
  p.setProperty("FeatureOption", "0");
   /* 0 disables fast insert and delete,
      1 enables fast delete but  disables fast insert, 
      2 enables fast Insert but disables fast delete,  
      3 enables both fast insert and fast delete */
  p.setProperty("user", "_SYSTEM");
  p.setProperty("password", "SYS");
  Connection c=driver.connect(url, p);

SQL.JDBC Delete Row Removes from Client and Corrects Cursor

In previous releases, if a row was deleted from updateble ResultSet, it would not be consistently deleted from the client. In this release, the deleted row will be deleted from the client. If your code depended on the previous behavior and assumes that the row would not be deleted, you should update your code. This release also ensures that cursor movements take into account deleted rows so that the client row index matches the server persistent Row ID.


The TRUNCATE TABLE command has been enhanced to delete the entire extent of the target table at once instead of row-by-row. In these cases, the resulting %ROWCOUNT value will be -1 rather than a count of rows that were deleted.

SQL Efficiency Improvements Change Internal Storage

In this release, InterSystems IRIS stores empty values in lists more efficiently. In previous releases, it stored empty values as a null string, but in this release, it stores it as a null. From SQL access, there is no compatibility issue, but if you access the underlying global storage structure and expect to find a null string, you may get a <NULL VALUE> error.

IDENTITY Column Data Type Change

In this release an identity column created via DDL that does not explicitly specify a data type defaults to a BIGINT data type. In previous releases, it defaulted to an INTEGER data type. If you have code that relies on this default, you should update it.

Error in Query in Stored Procedure Found at Compile Time

In this release, if you have a query with an error in a stored procedure, the error is reported when you compile the stored procedure. In previous releases, the error would not stop compilation but could cause problems when you executed the query.

Preserve Data Types in Dynamic SQL Arguments

In processing dynamic SQL the previous versions replaced literal with parameters but lost data type information. This caused some conversion errors. This release corrects this problem by preserving the data type information, but, consequently, the data type of the resultset may be different in this release from the previous release. If your code assumes the data type of the resultset, you may have to update it to accommodate this change.

Streams Changes

Streams are Locked for Longer Time

In this release, InterSystems IRIS locks streams earlier in the process of reading them. This ensures that the stream does not change after reading information about the stream, such as the size of the stream. This change may cause concurrency issues when multiple jobs are reading the same stream. In most cases, the stream will only be locked for a slightly longer time and this will be handled by your code that handles lock timeouts. However, if your code opens a stream and then delays before reading the stream or never reads the stream, this change can significantly increase the lockout time. This increases the chances of deadlock when multiple jobs are reading the same stream.

Stream Clones are Not in Temporary Directory

In this release the %FileCharacterStream %ConstructClone method creates the clone file in the same directory as the original file. In previous releases, it would incorrectly create the clone in a temporary directory. If you have code that assumes the file will be created in the temporary directory, you should update your code.

System Changes

Default Storage Change to %Storage.Persistent

In this release persistent storage is now in %Storage.Persistent. In previous releases, it was in %CacheStorage.

Unit Tests Changes

Autoload Resources are Deleted on Test Termination

In previous releases, if multiple autoload nested directories were created for a test, not all the levels of directories would be deleted when the unit test completed. In this release all autoload resources will be deleted. If you developed code that assumed that the directories would be retained, you should update your code.

Utility Changes

Change in Location of Temporary Files

This release changes the way %Library.File.TempFileName() creates temporary files. In previous releases the method just returned the filename and, typically, the file would later be created in the InterSystems IRIS temporary directory. In this release, the TempFileName() method creates the temporary file on disk and uses the operating system temporary directory rather than the InterSystems IRIS temporary directory.

Bulk Loader Gives Less Accurate Progress Report with Named Pipes

To improve the handling of named pipes, the Bulk Loader does not attempt to count the number of lines in the file. This decreases the accuracy of the progress report but improves the performance of the utility.

Web Services Changes

%NetHttpRequest May Require Extra Round Trip

In this release, a new authentication process for %Net.HttpRequest changes the existing %Net.HttpRequest support for Basic authentication. In previous releases, setting the Username property as a side-effect returns a Basic Authorization header. This behavior will only continue for HTTP 1.0 responses. For HTTP 1.1 responses an unsolicited Authorization header will never be sent unless the InitiateAuthentication property is set. For HTTP 1.1 responses will result in a 301 status response with a WWW-Authenticate header indicating Basic and possibly other schemes. The next request will then send the proper Authorization header. Consequently, existing code will continue to work but there may be an extra round trip.

FeedbackOpens in a new tab