Upgrading InterSystems IRIS for Health

You can validate that your upgraded system behaves the way you expect it to by using the Production Validator. The Production Validator extracts HL7 V2 headers, messages, and operation messages to a temporary database, which is then copied to an upgraded InterSystems IRIS for Health instance and replayed. By comparing the original messages to the messages processed on the upgraded system, you can evaluate and address differences.

If you are upgrading from a version prior to 2022.2 and your system is configured for secure communication, meaning that you had an Active configuration in the Configure SSL Access option in the Installer Wizard prior to your upgrade, note that the Configure SSL Access dialog in the Installer Wizard has been renamed to Configure Secure Communication. In the new dialog you must now specify an SSL/TLS Configuration in order to make the secure communication settings Active. A default value of HS.Secure.Demo was entered for the SSL/TLS Configuration setting when you upgraded.

If you previously had an Active configuration in the Configure SSL Access option, you must modify the default value to reflect the SSL/TLS configuration in use on your instance as follows:

1. Navigate to the Installer Wizard.

2. Select the new Configure Secure Communication option.

3. Confirm that your Secure Port is identified and the These Settings are Active checkbox is selected.

4. In the SSL/TLS Configuration field, select the name of the SSL/TLS configuration in use on your instance.

5. Click Save.

Running a post-installation method in the InterSystems Terminal is the final step in upgrading from InterSystems IRIS for Health 2018.1.2. You need to run this method multiple times if you have more than one user-created namespace. To complete the upgrade process:

1. Open the InterSystems Terminal.

2. To change the namespace to HSLIB, enter:

   set $namespace="HSLIB"

3. Enter:

   do ##class(HS.HC.Util.Installer.Upgrade.XFMapping).UpgradeHSXF("<namespace>")

   Where <namespace> is the name of a user-created namespace. You must repeat this command for each user-created namespace.

If you are upgrading from a version prior to 2020.4, the following steps that may be required depending upon on how you have customized your FHIR server. Perform these tasks in the following order:

1. If your FHIR server uses custom subclasses, you must modify your architecture subclasses.

2. If your FHIR endpoint uses custom search parameters, migrate them to a FHIR package and apply them to the endpoint.

Once you have completed these steps you can run re-index the search tables.

Re-index any FHIR search tables that require it:

1. In the Management Portal, navigate to Health > myFHIRnamespace > FHIR Configuration.

2. Select the Server Configuration card.

3. For each existing endpoint, select Reindex Now.

4. When prompted, click Select All, and then select Reindex.

   Note:

   This step may take some time to complete.

If you are using SDA3 or SDA3 transformations, you must import the SDA3 schema. For instructions, see the installation steps.

The HSSYS database stores configuration data, metadata, and system-level information that is vital for the overall functionality of InterSystems IRIS for Health, specifically including a list of tasks to be executed on the backup member of a mirrored system.

You can automatically mirror HSSYS using the HSSYS mirroring terminal utility. The assumption is that mirroring is configured and currently in a good state, with both machines running. The utility validates that HSSYS can be mirrored, confirming that the data is consistent on each of the mirror members. There is are options to validate only or to validate and then complete the mirroring of HSSYS.

Follow these steps to validate and/or automatically mirror HSSYS using the HSSYS mirroring terminal utility:

1. On the backup member, switch to namespace HSCUSTOM.

   NAMESPACE> ZN "HSCUSTOM"
   

2. Execute Run() or RunValidate():

   • RunValidate does not make any system changes; it only validates, reporting whether the HSSYS data is consistent across the primary and backup members.

     HSCUSTOM> Set return = ##class(HS.HC.SYS.Mirror).RunValidate("<ip_or_dn>",<server_port>,"HSCUSTOM","<adm_user>","<adm_pwd>",<verbose>)
     

   • Run performs validation and then, if validation succeeds, performs the actual mirror setup on HSSYS.

     HSCUSTOM> Set return = ##class(HS.HC.SYS.Mirror).Run("<ip_or_dn>",<server_port>,"HSCUSTOM","<adm_user>","<adm_pwd>",<verbose>)
     

   • The following argument descriptions apply to both methods:

     ip_or_dn

     The IP address or fully qualified domain name of the current primary member.

     server_port

     The Super Server port number of the primary member.

     adm_user

     The username of a user with the administrative privileges necessary to set up mirroring.

     adm_pwd

     The privileged user’s password.

     verbose

     Specify 1 for verbose output, or 0 if verbose output is not desired.

3. You can view the output on the terminal screen or by looking at the return variable:

   HSCUSTOM> ZW return
   

4. If validation fails, mirroring setup will also fail. The return value will include helpful messages indicating how to resolve the issues causing setup to fail. Correct the issues and repeat these steps.

If you have a non-Foundation namespace and you want to use IRIS for Health or Health Connect interoperability functionality within that namespace, you  must convert that namespace to a Foundation namespace. You can do so using the Installer Wizard, by picking the name of the namespace to be converted. In a mirrored environment, it is sufficient to convert the namespace on the primary member.