Bringing Legacy Code Into Current Versions - Tips and Tricks

Inevitably, you will eventually need to move your code up from one version of IRIS or Cache to a more recent version of IRIS. There are a few good steps you can take to set yourself up for success in that process.

Read Documentation Carefully

Before you move anything you should check out the IRIS documentation page for many useful resources on changes made to various versions of IRIS. If you are upgrading through multiple versions, you will want to check on the documentation for all of them, not just the version to which you will upgrade. For each version, if you click on the Maintenance Release Changes link, you will see a developer upgrade checklist that is very helpful in providing guidance on what you will need to change. You will also want to check the Release Notes. It has a list of what new features are available that might be of use to you, and it has a list of what is newly-deprecated. You should also check the Product News and Alerts page for more recent, urgent matters. In fact, it is a good idea to check that page periodically or subscribe to the alerts to stay on top of changes even when you are not going through an upgrade!

Know Your Alternatives

Based on what you read in the documentation, you may see a pile of issues coming. Before you start running them down, however, you should take some time to get to know what your alternative options are. If a specific ObjectScript class you like to use has been deprecated or removed, do not just look for an ObjectScript replacement if you are going to have integrated Python available. If you have been a Zen reports user, InterSystems reports is the replacement for that tool. $ZF -100 has replaced $ZF -1. Many other removed pieces have newer replacements, and you should look for them before you start reinventing the wheel.

Scan, Deprecate, Scan

Make yourself comfortable with the %SYSTEM.CodeScanner class. This class includes class queries (or class methods in earlier versions) that detect the use of deprecated items and a few other common issues such as using $ZF -1 or $ZF -2, using %this to reference the current object, use of old class keywords, etc. 

Once you have scanned your code, you will be faced with some choices as to how to address these issues. Some of them will be very simple to fix by changing your code to use new tools and methods. Other pieces will require more effort. In the midst of this decision making, remember that you can deprecate your own code! The Deprecated key word can be applied to parameters, properties, methods, and even entire classes. This is often overlooked by programmers. If you decide to deprecate some things, you can then use the code scanner class again to find out where all of those things are used, then address those issues, and so on. Depending on how deep this rabbit hole goes for you, it may take several passes to sort all of this out. It can be a lot of work now, but it can save a lot of headaches later.

Re-Tune Those Tables

Table tuning has been around for a while now, and it has gone through some changes. There have been significant improvements to that process even as recently as version 2025.2. If you are bringing forward older code and have not re-tuned your tables, you may be missing out on some great improvements to that tool. If you take advantage of that, you may be able to gain a fair amount of efficiency without touching a single line of code!

Test Thoroughly

No amount of preparedness or tools can fully replace good old-fashioned testing. Whether your preferred testing mechanism is unit testing, Postman, or just Teresa in customer support who knows exactly how your users tend to break things, make sure they are engaged and active in thoroughly testing your code on your new version. Take nothing for granted.

Engage the Community

A lot of us here have been around the block a few times. I will not name names and I definitely won’t list ages, but at any point during this process the very community website that you are on right now is a great resource. If you need a replacement for older code, you can ask if anyone has one and how they made the jump from one to the other. This is a very helpful place for any situation. 

If you have an idea for how to improve the upgrade process in the future, please post it in the Ideas Portal. InterSystems and the community users check this portal regularly for ideas on how to improve things, and you may end up saving yourself work in the future.

If you come across a problem you just can’t possibly solve on your own or with community help, there is also always the Worldwide Response Center where you can get more in-depth help directly from InterSystems.

Now let’s hear from the rest of the community too. Let everyone know how you have managed such upgrades before. Where did you succeed, where did you fail, and what will you do differently next time?