InterSystems IRIS for Health™ Upgrade Checklist (2025.1)
This document is meant to help you assess the impact of upgrading to the InterSystems IRIS for Health 2025.1 extended maintenance (EM) release. It lists the incompatibilities since 2024.1.0. These incompatibilities may require changes to code, configuration, or operation.
To see the incompatibilities between your current version and the current release, use the Upgrade Impact Checklist.
InterSystems News, Alerts, and Advisories
From time to time, InterSystems publishes items of immediate importance to users of our software. These include alerts, mission-critical issues, important updates, fixes, and release announcements. You can obtain the most current list at https://www.intersystems.com/support-learning/support/product-news-alerts/Opens in a new tab. InterSystems recommends that you check this list periodically to obtain the latest information on these issues.
Backup/Restore
DP-434811: Skip restoring to IRISSYS
Category: Backup/Restore
Platforms: All
Version: 2024.3.0
If ##class(Backup.Online).Restore() is called in such a way that would restore any database over the system's IRISSYS database, the system skips that particular restoration and the IRISSYS database is not restored.
To restore the system's IRISSYS database, either shut down the instance and use a different instance to restore the backup, or restore the database in an alternate location.
Containers
DP-432046: Default log location has moved
Category: Containers
Platforms: UNIX®
Version: 2024.3.0
This change moves the default log location when deployed in containers, which may break scripts that hardcoded the log location. Logs are now stored within the logs folder, not the bin folder. The names of the log files have not changed.
CSP Server
DP-429230: OPTIONS requests to run unauthenticated
Category: CSP Server
Platforms: All
Version: 2024.2.0
The system no longer calls %CSP.REST.onPreDispatch() while handling HTTP OPTIONS requests. If there is code in that method that must be run in for an OPTIONS request, add the code to the OnHandleOptionsRequest() method.
FHIR
IF-6106: Bearer token string is visible in Interop message trace and FSLOG
Category: FHIR
Platforms: All
Versions: 2023.1.6, 2024.1.3, 2024.2.0
FHIRServer no longer uses the request object (HS.FHIRServer.API.Request) to pass an OAuth bearer token string through the processing infrastructure. Instead, it uses the request object's AdditionalInfo "USER:TokenId" element to pass an identifier that can be used as a key to retrieve the bearer token information from a protected location, rather than directly from the AdditionalInfo "USER:OAuthToken" element.
See the documentation for the GetTokenInfo() and GetTokeInfoItem() methods in the HS.HC.Util.InfoCache class for details on how to use this mechanism.
In paritcular, custom ObjectScript that receives a bearer token via a request object sent by HS.FHIRServer.RestHandler, HF.FHIRServer.RestClient.FHIRService, or HS.FHIRServer.RestClient.Interop will need to be changed immediately to use the methods in HS.HC.Util.InfoCache immediately.
Any custom ObjectScript that places a bearer token string into a request object and subsequently passes the request object to HS.FHIRServer.Service or HS.FHIRServer.Interop.HTTP will continue to work as is. However, InterSystems strongly recommends that you convert this custom code to use HS.HC.Util.InfoCache as soon as possible.
Installation
- Unable to launch documentation from the cube
- remove cvencrypt from install
- Removal of Studio from Windows kits 2024.2+
DP-429584: Unable to launch documentation from the cube
Category: Installation
Platforms: All
Versions: 2023.2.0, 2023.3.0, 2024.1.0, 2024.1.1, 2024.2.0
If you are using Windows IIS as your web server or have upgraded from either 2023.2 or 2023.3, then you cannot open documentation through the launcher by default. To manually create a workaround, see the "Connect Your Web Server Manually" section of "Access the Management Portal and Other Built-in Web Applications Using Your Web Server."
DP-429883: remove cvencrypt from install
Category: Installation
Platforms: All
Version: 2024.2.0
The cvencrypt utility is no longer installed on any platform.
DP-431079: Removal of Studio from Windows kits 2024.2+
Category: Installation
Platforms: All
Version: 2024.2.0
Starting with this release, Windows kits will no longer contain Studio. This means that new installations using this kit will not install Studio and upgrading an existing instance to the version in this kit will remove Studio from the instance’s bin directory.
Developers who wish to keep using Studio will need to download the 2024.1 Studio independent component from the WRC distribution page. Studio version 2024.1 is forward compatible, so it can connect to IRIS versions 2024.2+.
Visual Studio Code is the preferred IDE for development. Refer to the documentation for more information.
Integration
DP-436276: GetSize error no longer prevents future ingestion attempts with the FTP inbound adapter
Category: Integration
Platforms: All
Version: 2025.1.0
Previously, the FTP inbound adapter could time out on a GetSize error that would prevent the adapter from attempting to ingest the file again. This is no longer the case, as files that encounter this error will not be skipped in future attempts. There is a new setting that users can use to add more error types that should not cause skipping.
Interoperability
- System Default Settings Override support for LogGeneralTraceEvents, LogTraceEvents & Schedule
- [Interoperability] Prevent Auto Starting of productions in Shard client namespaces (JGM1220)
- Correct Charset handling for SFTP
- Business Process ReplyCodeAction to handle failure to open request object
- FTP Inbound Adapter to Decode Chinese Correctly
- Ens.DataType.UTC to throw an error on invalid dates
- Raise error when re-sending a batch
DP-428768: System Default Settings Override support for LogGeneralTraceEvents, LogTraceEvents & Schedule
Category: Interoperability
Platforms: All
Version: 2024.2.0
The System Default Settings previously ignored any entries that matched an item's Schedule or LogTraceEvents setting or a production's LogGeneralTraceEvents setting, but now these settings that have matches are no longer automatically ignored. You should only set these settings from one place and should edit either the System Default Settings or the item/production settings to the system behaves as you expect.
To identify if such System Default Settings already exist, run the following SQL query from the desired namespace:
SELECT * FROM ENS_CONFIG.DEFAULTSETTINGS WHERE SETTINGNAME IN ('Schedule','LogTraceEvents','LogGeneralTraceEvents')
DP-433629: [Interoperability] Prevent Auto Starting of productions in Shard client namespaces (JGM1220)
Category: Interoperability
Platforms: All
Version: 2024.3.0
If you had an Interoperability production running in a sharded namespace, before this change it was necessary to use a workaround so that the production would not be autostarted in the shard client namespaces. (The workaround was to map the ^Ens.AutoStart global so that only the data (ECP server) node has the entry that is populated.)
With this change, the Interoperability Director framework identifies if the namespace has the core runtime data (^Ens.Queue or ^Ens.Runtime globals) served over ECP rather than locally and if so will prevent the production starting if the node is identified as a sharded cluster node.
This change still allows the configuration of a production to run on an ECP client that is not part of a sharded cluster, although it is not advised to run a production where the core ^Ens.Queue and ^Ens.Runtime globals are served from a remote database server.
It is still not permitted to run a production on multiple instances within a shared namespace.
DP-433644: Correct Charset handling for SFTP
Category: Interoperability
Platforms: All
Version: 2024.3.0
Before this change, the inbound FTP adapter did not correctly use the Charset property when used for SFTP. This change corrects the behavior. If your code had worked around the problem by performing its own character set conversion, the result will now be double conversion of the characters; to avoid this, you can set Charset to Binary, which will cause the adapter to not perform any character set conversion.
The other option is to update your code to not include the workaround.
DP-433864: Business Process ReplyCodeAction to handle failure to open request object
Category: Interoperability
Platforms: All
Version: 2024.3.0
When a request object unexpectedly cannot be opened due to a lock timeout, the ReplyCodeActions are now applied, allowing the system to catch the error and disable the host item.
DP-433968: FTP Inbound Adapter to Decode Chinese Correctly
Category: Interoperability
Platforms: All
Version: 2024.3.0
Previously, when using the FTP protocol with the UTF-8 charset when archiving is enabled, a file written in Chinese the FTP inbound adapter would produce incomprehensible content. This change resolves that issue.
Users who had produced a manual workaround should be aware of this change in behavior.
DP-434849: Ens.DataType.UTC to throw an error on invalid dates
Category: Interoperability
Platforms: All
Version: 2025.1.0
Previously, an invalid date (like June 31st) stored in Ens.DataType.UTC in a SQL query would not cause an error located in a time zone that is behind UTC, but would cause an OUT OF RANGE error on machines located in a time zone that is ahead of UTC. This behavior has been changed such that an ILLEGAL VALUE error is thrown on an invalid date, regardless of time zone.
DP-436058: Raise error when re-sending a batch
Category: Interoperability
Platforms: All
Version: 2025.1.0
If UseDefaultBatch is on and a message from an earlier batch is re-sent from a business process to a business operation, an error is raised and the message is rejected. Previously, this message would be kept in an orphaned file.
If you would like to accept such messages, manually enable AcceptDefaultBatchParentBatch.
Journaling
DP-431508: Removal of Type^JRNDUMP
Category: Journaling
Platforms: All
Version: 2025.1.0
Type^JRNDUMP has been eliminated. Use ##class(%JournalRecordType).LogicalToDisplay() instead.
Licensing
DP-428833: Save (and use) downloaded license key for next startup
Category: Licensing
Platforms: All
Version: 2024.2.0
A copy of the last downloaded license key is now saved in the iris-saved.key file in the /mgr directory of your instance. If the instance finds an iris-saved.key file in this directory on startup and does not find an iris.key file there, then the iris-saved.key file is used as the license key for startup. A message indicating which license key has been used is reported at startup.
Mirroring
DP-434559: Remove option to add async not in pending list from Management Portal and ^MIRROR interfaces
Category: Mirroring
Platforms: All
Version: 2024.3.0
The option to add a new async member not in the pending list on the primary in a mirror that uses SSL/TLS has been removed from the Management Portal and the ^MIRROR utility. This option existed only to support authorization of async members running versions earlier than 2015.2, which is no longer a supported configuration.
Natural Language Processing
DP-432596: Don't strip punctuation when normalizing user input
Category: Natural Language Processing
Platforms: All
Versions: 2024.1.2, 2024.3.0
iKnow APIs no longer strip punctuation when normalizing user input.
You can manually strip punctuation from user input to avoid unintended behavior.
NLP
DP-429728: Remove UIMA components from IRIS
Category: NLP
Platforms: All
Versions: 2023.1.5, 2024.1.1, 2024.2.0
Following the deprecation of UIMA in 2020.1, it has been removed from the product in this release.
Object Compiler
DP-437953: standardize behavior of CompileAllNamespaces() across namespaces
Category: Object Compiler
Platforms: All
Version: 2025.1.0
This change slightly modifies the behavior of %SYSTEM.OBJ.CompileAllNamespaces, specifically by applying one qspec to all namespaces, rather than the previous behavior, which slightly modified the qspec argument depending on the namespace currently being compiled. Any instance that relied on the old behavior should be aware of this change.
Object Library
- Turn on compact IEEE in server by default
- Re-throw "hard" errors that are thrown during unit test execution
- Improvements to $SYSTEM.SQL.ParseQualifiers()
- Logging with ^ISCLOG in %Net.SMTP
DP-420686: Turn on compact IEEE in server by default
Category: Object Library
Platforms: All
Version: 2025.1.0
Previous versions introduced the ability to use compact IEEE values when they are stored in a $LIST. This change makes the compact behavior the default for new installations by setting the ListFormat configuration parameter in the [Miscellaneous] section of the CPF to 1.
However, old versions of database drivers (such as JDBC, ODBC, and ADO.NET) will be unable to connect with any server that uses compact IEEE doubles. To avoid connection failures, update your database drivers to the latest version or turn compact IEEE doubles off by manually setting the ListFormat configuration parameter in the [Miscellaneous] section of the CPF to 0.
DP-434433: Re-throw "hard" errors that are thrown during unit test execution
Category: Object Library
Platforms: All
Version: 2024.3.0
The %UnitTest framework will stop text execution if it encounters a system error to alert the user that the system or process is in a troubled state, meaning any other processing is suspect. The system errors that will stop execution are: INTERRUPT, FILEFULL, DISKHARD, DATABASE, SYSTEM, STORE, EXTERNAL INTERRUPT, ALARM, DSKFUL. Previously, these errors would be treated as any other system error and test execution would continue after logging the error.
DP-435416: Improvements to $SYSTEM.SQL.ParseQualifiers()
Category: Object Library
Platforms: All
Version: 2025.1.0
With this change, the $SYSTEM.SQL.ParseQualifiers() method can now accept the empty string as a valid legacy qualifier string, accept legacy qualifier string that start with or are solely comprised of flags, and use a localized error stats when called with an OREF that is not a %DynamicObject.
DP-437821: Logging with ^ISCLOG in %Net.SMTP
Category: Object Library
Platforms: All
Version: 2025.1.0
Previously, logging from %Net.SMTP was not possible without directly editing code in the class, which would cause the logs to be stored in ^SmtpTrace; any code that relied on checking ^SmtpTrace for logs must be modified. Now, logging capabilities are set by the system logging level, which you can set with ##class(%SysLog).LogLevel.Set(), and any logs from the %NET.SMTP class are stored in the ^ISCLOG global.
If the logging level is 1, no logging is performed. If the logging level is 2, then the %NET.SMTP class only logs the SMTP login authentication mechanism. If the logging level is 3, then the %NET.SMTP class logs the entire client-server interaction.
ObjectScript
- RFC4122 randomized mac address with multicast bit set for multiple IRIS instances on one host
- On Windows, CreateGUID(1) uses internal support instead of Windows OS APIs
- Rounding changes in transcendental functions
DP-428527: RFC4122 randomized mac address with multicast bit set for multiple IRIS instances on one host
Category: ObjectScript
Platforms: UNIX®,macOS
Version: 2024.2.0
There is now a new CPF parameter, UUIDv1RandomMax, which controls how MAC addresses are treated within the UUID infrastructure. Users should refer to the documentation on this parameter and decide if they would like to set it or use the default.
DP-434694: On Windows, CreateGUID(1) uses internal support instead of Windows OS APIs
Category: ObjectScript
Platforms: Windows
Version: 2024.3.0
Previously, calling the CreateGUID() method of the %SYSTEM.Util class with the 1 option on a Windows system would use Windows OS APIs to create a v1 UUID. With this change, internal APIs are used to generate a v1 UUID. You can still use CreateGUID() without an argument to still use existing Windows APIs for backward compatibility.
Read the documentation for the CreateGUID() method in the %SYSTEM.Util class to see details about v1 UUIDs.
DP-435863: Rounding changes in transcendental functions
Category: ObjectScript
Platforms: All
Version: 2025.1.0
On Windows platforms, transcendental math functions, such as sine or cosine, are now rounded slightly differently, to better adhere to the defaults returned by Windows and Linux systems.
Security
DP-428895: Don't allow the creation of Web Application names that break the Management Portal
Category: Security
Platforms: All
Version: 2024.2.0
With this change, there are now some invalid names for web applications. You cannot modify the properties of web applications with these newly invalid names. Instead, you should delete the application and create a new one using a valid name.
Invalid web application names take the following form: /csp/{namespace}/(images | portal | deepsee)
SQL
- Safely support longer string fields in columnar storage
- Apply collation for UNION
- make FLOAT the default VECTOR/EMBEDDING type
DP-429434: Safely support longer string fields in columnar storage
Category: SQL
Platforms: All
Version: 2024.2.0
If you explicitly define a string property with MAXLEN > 300 to use columnar storage or if you create a columnar index on a string property that is MAXLEN > 300, you will now receive an error. You should lower the value for MAXLEN on the field.
Refer to the documentation on columnar storage for more information about length limits.
DP-429949: Apply collation for UNION
Category: SQL
Platforms: All
Version: 2024.2.0
This change modifies the behavior of UNIONs to consistently enforce the use of the implicit DISTINCT function. Previously, field values were taken as-is and the column was assumed to use EXACT collation for onward processing. Now, the default collation of the column (typically SQLUPPER) is applied to each value, similar to using an explicit DISTINCT clause.
To achieve the old behavior, users can use a collation function, such as %EXACT(), to get the distinct values as-is or use UNION ALL to avoid the implied DISTINCT behavior.
DP-434569: make FLOAT the default VECTOR/EMBEDDING type
Category: SQL
Platforms: All
Version: 2024.3.0
The default type for VECTOR and EMBEDDING data is now FLOAT.
In previous versions, the default type was DOUBLE. To preserve existing code and data, augment your usage of TO_VECTOR to explicity convert vectors to DOUBLE or reload your stored data with the FLOAT type. Note that operations performed on VECTORs or EMBEDDINGs that have different types results in an error.
System
- Expand per-process database file table as needed, and increase its overall size limit
- An exact number of undefined arguments may be passed with args...
- Deprecate global growth and pointer block settings
DP-434735: Expand per-process database file table as needed, and increase its overall size limit
Category: System
Platforms: All
Version: 2025.1.0
In extreme application use cases where individual process need to have greater than 1,000 I/O files or devices open at once, the new higher reservation for database volumes may cause TOOMANYFILES errors. Deployments can avoid those errors by making sure OS limits permit at least 5+MIN(x*2, 10240+x) open files, where 'x' represents the maximum number of I/O devices a process needs open at once.
This change does not apply to Windows systems where it was not previously possible to have such an extreme number of I/O files and devices open at once.
DP-437710: An exact number of undefined arguments may be passed with args...
Category: System
Platforms: All
Version: 2025.1.0
Previously, if you set a variable 'x' to an integer (and 'x' was not an array) and passed 'x...' into a method that takes a variable number of arguments, with method signature 'method(args...)', then that method would treat its passed argument, 'x...', as undefined and ignore the value of 'x'.
Now, calling 'method(x...)' passes the integer value of 'x' into 'args' and allows you to simulate calling the method with an 'x' number of omitted arguments. If 'x' is not an integer, it is ignored, as it was before this change.
This new behavior throws a
DP-437861: Deprecate global growth and pointer block settings
Category: System
Platforms: All
Version: 2025.1.0
This change depreates the New Global Growth Block and New Global Pointer Block database settings. As a result of this deprecation, these settings are now hidden from the Management Portal and ^DATABASE CHUI, when they had previously been available through those interfaces. Additionally, these options can no longer be used to trigger database expansion; if they exceed the database's current size, the allocator ignores the change.
Though the properties are deprecated, they may still be accessed and changed through the SYS.Database class.
Work Queue Manager
DP-428004: Remove 'head' count in WQM and simplify internal interface
Category: Work Queue Manager
Platforms: All
Version: 2024.2.0
As part of the ongoing work to simplify and allow for future enhancements in the work queue manager, this change removes the deprecated %occCompileUtil routine.
For Additional Help
If you need assistance with evaluating how upgrading to this extended maintenance (EM) release will affect your applications, systems, or related plans, please contact the InterSystems Worldwide Support Center:
- Phone: +1.617.621.0700
- Fax: +1.617.734.9391
- Email: support@intersystems.com
Current release notes (and complete product documentation) can be found online at https://docs.intersystems.com.