HealthShare Personal Community Upgrade Guide
1. Introduction
Within this document:
- Links, buttons and all captions are shown in bold
-
Field values display in
monospace
(e.g. standard type values such asYes/No
) - Important information is underlined .
2. Overview
This guide describes required tasks for upgrading Personal Community. It is for upgrading from version 2021.2 and later.
Prior to beginning the upgrade process, review "Preparing for Your Upgrade."
IMPORTANT
Upgrading from Personal Community version 2021.2 involves incompatible changes. A new UI is used across the entire application, and so your UI customizations from version 2021.2 or earlier will no longer function. The upgrade process is irreversible.
3. Upgrade Paths
Legacy Upgrades
Legacy upgrades are ONLY supported from the last legacy version (2021.2). Sites running an earlier version of Personal Community must first upgrade to 2021.2 before proceeding.
The following table describes supported upgrade paths for a given target version of Personal Community.
Target Version | Supported Source Versions |
---|---|
2024.x | 2021.2, 2022.x, 2023.x, 2024.x |
4. Preparing for Your Upgrade
IMPORTANT
Your Unified Care Record instance must be compatible with the version of Personal Community you are upgrading to.
Perform these tasks before upgrading to the latest version of Personal Community:
- Review all of the documentation in this section.
- Upgrade a test system before you upgrade your production system.
-
Confirm that you have installed a license key appropriate to your software version. Certain features of Personal Community will not operate properly unless you have an updated license key. It is crucial that you have the correct license key before you reactivate your Personal Community production. Consult with your InterSystems representative to determine if you have an appropriate license key.
-
Run a system integrity check on existing directories to ensure there is no corruption in any of the databases. See Introduction to Data Integrity for more information.
-
Perform a full back up of the production system. As a best practice, InterSystems recommends that you restore this backup to another system and run a system integrity check to make sure that it is good.
-
Save any custom code, classes, user-interface customizations outside of the installation tree, so that these are easily available after upgrade.
CAUTION
Under no circumstances should Personal Community or HealthShare code (that is, code in the HSPortal or HS package) be recompiled.
-
Check your messages.log file to see if you have configured one of these memory settings. When you restart your instance during upgrading, you will need to make sure the instance is allocating memory in accordance with your configuration. (If the instance cannot allocate memory using this configuration, a server reboot is required to prevent an error condition from occurring.)
Linux example:
Allocated 1342MB shared memory using Huge Pages: 1024MB global buffers, 35MB routine buffers
Windows example:
Allocated 8920MB shared memory (large pages): 8192MB global buffers, 256MB routine buffers
-
If you are on a Windows system, open Windows Services and find the service controller for instname . Right-click the service, click Properties , and then click the Log On tab. If the tab specifies the Local System account or an account of the form domainname\username , no action is necessary. If the account is of the form username@domainname , make a note of this account and make sure that you know the password associated with the account. You will need to reenter this information after the installation finishes.
-
For upgrades run on Linux, make sure the user who is performing the upgrade has sudo privileges, as some commands must be run with root access.
-
Your system must have free disk space of at least 200 MB plus the size of the file /<installdir>/mgr/iris.dat prior to upgrading. The installation script or installer will not attempt the upgrade if it detects that insufficient disk space is available.
-
Before production upgrade, alert your members in advance that the system will be unavailable at the time for which the upgrade is scheduled.
- Backup your i18n files as these will be overwritten during upgrade.
-
Configure your external Web server to redirect users to appropriate pages for Workbench and Personal Community while your productions are down.
Note
When you bring your productions down on an unmirrored system, the outage takes effect immediately. However, the outage for an upgrade of a mirrored system takes place only after the upgrade of the backup failover member.
5. Installing the New Kit on an Unmirrored System
- To ensure a smooth and efficient upgrade, make sure you have performed the pre-upgrade tasks before starting the upgrade
-
Stop all productions:
- In the Management Portal, select HealthShare from the main menu. This displays the HealthShare Management Portal
- In the HealthShare Management Portal , select the Stop All button at the top of the page. At the confirmation dialog, select OK .
-
Shut down the Personal Community instance:
- On Windows, stop the instance by selecting Stop HealthShare from the launcher in the Windows tool bar.
-
On Linux, enter
iris stop <instance-name>
in a shell terminal session.
-
Activate your new license key.
To activate a license key:
-
Log in to the Management Portal as a user with the %Manager role.
-
Go to the License Key page ( System Administration > Licensing > License Key ).
-
On that page, select Activate New Key . This displays the Activate a New License Key dialog.
-
On the Activate dialog, specify the license key to activate.
-
Select Activate .
For more details about this process, see further instructions in the System Administration guide .
-
-
Run the installation program according to the instructions for your operating system. When you are prompted to enter an instance name, enter the name of the instance you are upgrading. (If you are upgrading an instance on a host with multiple instances, such as in a test environment, make sure you select the correct instance before proceeding.)
Note
The installation program automatically restarts the underlying InterSystems IRIS for Health instance, so you do not need to do this manually.
6. Installing the New Kit on a Mirrored System
- To ensure a smooth and efficient upgrade, make sure you have performed the pre-upgrade tasks before starting the upgrade. Verify which instance is the primary failover member (referred to in this section hereafter as "server A") and the backup failover member (referred to in this section hereafter as "server B").
-
To prevent unwanted failover during upgrading, set
No Failover
on server B.
- In the Management Portal, select Home > System Operation > Mirror Monitor .
- On the Mirror Monitor page, select Set No Failover .
-
Shut down server B:
-
On Windows, stop the instance by selecting Stop HealthShare from the launcher in the Windows tool bar.
-
On Linux, enter
iris stop <instance-name>
in a shell terminal session.
-
-
On Linux systems, the location of the ISCAgent service has changed. Before running the installation program, stop and disable the old version of the service from the command line:
-
Stop the ISCAgent service:
# systemctl stop ISCAgent.service
-
Disable the ISCAgent service:
# sudo systemctl disable ISCAgent.service
-
Check the status of the ISCAgent service and make sure it shows that the service is inactive:
# systemctl status ISCAgent
-
-
On server B, run the installation program according to the instructions for your operating system. When you are prompted to enter an instance name, enter the instance name of server B.
Note
The installation program automatically restarts the underlying InterSystems IRIS for Health instance, so you do not need to do this manually.
-
On Linux systems,
start and then enable the updated version of the ISCAgent service from the command line:
-
Start the ISCAgent service:
# systemctl start ISCAgent.service
-
Enable the ISCAgent service:
# sudo systemctl enable ISCAgent.service
-
Check the status of the ISCAgent service and make sure it shows that the service is active:
# systemctl status ISCAgent
-
-
To prepare for mirror failover, make sure that the correct server is the backup failover member:
-
In the Management Portal, select Home > System Operation > Mirror Monitor.
-
On the Mirror Monitor page, verify that server B appears with the status of Backup .
Note
Check this from the Mirror Monitor page on the backup failover member. If the primary and the backup are on different versions of ISCAgent, the Mirror Monitor page on the primary failover member will show the backup failover member as having a Status of Down .
-
-
Clear No Failover to enable mirror failover:
-
In the Management Portal, select Home > System Operation > Mirror Monitor .
-
Select Clear No Failover .
Note
If you plan to deploy a system outage message but have not yet done so, deploy it now.
-
-
Stop all productions on server A:
-
In the Management Portal, select HealthShare from the main menu. This displays the HealthShare Management Portal .
-
In the HealthShare Management Portal , select the Stop All button at the top of the page. At the confirmation dialog, select OK .
-
-
Shut down server A:
-
On Windows, stop the instance by selecting Stop HealthShare from the launcher in the Windows tool bar.
-
On Linux, enter
iris stop <instance-name>
in a shell terminal session.Note
After the instance shutdown has completed, you can verify that the instance stopped cleanly by examining <install-dir> /mgr/messages.log.
-
-
Verify that server B is the primary failover member:
-
In the Management Portal, select Home > System Operation > Mirror Monitor .
-
On the Mirror Monitor page, verify that server B appears with the status of Primary .
-
-
In an InterSystems IRIS for Health terminal session on server B, compile and upgrade the HSCUSTOM namespace:
zn "HSCUSTOM" do $system.OBJ.Upgrade() do $system.OBJ.CompileAll("u") do ##class(%Routine).CompileAll()
Note
You can verify that the namespace compiled cleanly by examining <install-dir> /mgr/messages.log and <install-dir> /mgr/ensinstall_x.log .
The following error can be ignored:
[SYSTEM MONITOR]ISCAgent Alert: ISCAgent reported ERROR #2162: Failed to identify the ISCAgent application server port.
-
Activate all Personal Community namespaces on server B:
-
Go to the HealthShare Installer Wizard ( Management Portal > HealthShare > Installer Wizard at the top of the page).
-
Activate each namespace (listed in the Name column). To do this, for each namespace that has an Activated value of 0:
-
Select Activate , which displays the Activate Configuration page for that namespace.
-
On the Activate Configuration page, select Start .
-
-
- If any elements of your Personal Community reports or dashboards rely on custom cubes, you must recompile the classes associated with those cubes after upgrade.
-
Start all productions associated with Personal Community on server B:
-
From the Installer Wizard page, select HealthShare Management at the top of the page. This displays the HealthShare Management Portal .
-
In the HealthShare Management Portal , select Start All .
Clear the Web Gateway cache from the Management Portal ( Home > System Administration > Configuration > Web Gateway Management > System Status ).
-
-
Once all productions are up and running on InterSystems IRIS for Health on server B, validate the updated instance according to your company’s best practices before running the installer on server A.
-
On Linux systems, stop and disable the ISCAgent on server A:
-
Stop the ISCAgent service:
# systemctl stop ISCAgent.service
-
Disable the ISCAgent service:
# sudo systemctl disable ISCAgent.service
-
Check the status of the ISCAgent service and make sure it shows that the service is inactive:
# systemctl status ISCAgent
-
-
On server A, run the installation program according to the instructions for your operating system. When you are prompted to enter an instance name, enter the instance name of server A.
Note
The installation program automatically restarts the underlying InterSystems IRIS for Health instance, so you do not need to do this manually.
-
On Linux systems,
start and then enable the updated version of the ISCAgent service from the command line:
-
Start the ISCAgent service:
# systemctl start ISCAgent.service
-
Enable the ISCAgent service:
# sudo systemctl enable ISCAgent.service
-
Check the status of the ISCAgent service and make sure it shows that the service is active:
# systemctl status ISCAgent
-
-
Verify that server A is the backup failover member:
-
In the Management Portal, select Home > System Operation > Mirror Monitor .
-
On the Mirror Monitor page, verify that server A appears with the status of Backup .
-
-
On server B, clear No Failover to enable mirror failover:
-
In the Management Portal, select Home > System Operation > Mirror Monitor .
-
Select Clear No Failover .
-
-
Stop all productions that are associated with Personal Community on server B:
-
In the Management Portal, select HealthShare from the main menu. This displays the HealthShare Management Portal .
-
In the HealthShare Management Portal , select the Stop All button at the top of the page. At the confirmation dialog, select OK .
-
-
Shut down server B:
-
On Windows, stop the instance by selecting Stop HealthShare from the launcher in the Windows tool bar.
-
On Linux, enter
iris stop <instance-name>
in a shell terminal session.Note
After the instance shutdown has completed, you can verify that the instance stopped cleanly by examining <install-dir> /mgr/messages.log.
-
-
Verify that server A is the primary failover member:
-
In the Management Portal, select Home > System Operation > Mirror Monitor .
-
On the Mirror Monitor page, verify that server A appears with the status of Primary .
-
-
In an InterSystems IRIS for Health terminal session on server A, compile and upgrade the HSCUSTOM namespace:
zn "HSCUSTOM" do $system.OBJ.Upgrade() do $system.OBJ.CompileAll("u") do ##class(%Routine).CompileAll()
Note
You can verify that the namespace compiled cleanly by examining <install-dir> /mgr/messages.log and <install-dir> /mgr/ensinstall_x.log .
The following error can be ignored:
[SYSTEM MONITOR]ISCAgent Alert: ISCAgent reported ERROR #2162: Failed to identify the ISCAgent application server port.
-
On server A, go to the HealthShare Installer Wizard ( HealthShare > Installer Wizard at the top of the page) and verify that Personal Community namespaces are activated.
-
Start all productions associated with Personal Community on server A:
-
From the Installer Wizard page, select HealthShare Management at the top of the page. This displays the HealthShare Management Portal .
-
In the HealthShare Management Portal , select Start All .
Clear the Web Gateway cache from the Management Portal ( Home > System Administration > Configuration > Web Gateway Management > System Status ).
-
- Restart server B, and verify that it is the backup failover member.
7. Reactivating Namespaces
A Personal Community upgrade requires namespace reactivation. To do this:
- Go to the HealthShare Installer Wizard (Management Portal > HealthShare > Installer Wizard at the top of the page).
-
Activate each namespace (listed in the
Name
column). To do this, for each namespace that as an
Activated
value of 0:
- Select Activate , which displays the Activate Configuration page for that namespace.
-
On the Activate Configuration page, select Start .
Note
Activation of your reporting namespace (“HSPCREPORTS”, for example) may increase downtime. To reduce downtime, you can complete your remaining post-upgrade steps and allow users back on the system while activation of your reporting namespace is taking place.
-
Once all namespaces are reactivated, start all the productions that are associated with Personal Community. To do this:
-
From the Installer Wizard page, select HealthShare Management at the top of the page. This displays the HealthShare Management Portal .
-
In the HealthShare Management Portal , select Start All .
-
-
For the underlying instance of InterSystems IRIS for Health™, clear the Web Gateway cache from the Management Portal ( System Administration > Configuration > Web Gateway Management > System Status ).
8. Converting Customizations After an Upgrade
As of Personal Community version 2022.3, a new UI is used across the entire application. Your customizations from version 2021.2 or earlier will no longer function, and the upgrade process is irreversible.
8.1. Recompiling Cubes
If any elements of your Personal Community reports or dashboards rely on custom cubes, you must recompile the classes associated with those cubes after upgrade.
8.2. Changed Entries in i18n Files
Compare the set of i18n files contained in <install-dir>/csp/public/assets/i18n to your set of backed up i18n files, and add any new entries.
9. Additional Post Upgrade Configuration
Upgrading from certain versions to the latest version of Personal Community may require additional configuration.
9.1. Additional Configuration
9.1.1. Upgrading from a version prior to 2023.3
2023.3 introduced new feature control for the Cancel Appointment workflow. On upgrades, this workflow will be defaulted to off. Site using the View Appointment functionality in previous versions may re-enable this feature by using the Configuration Application.
9.1.2. Upgrading from a version prior to 2023.5
Personal Community 2023.5 added support for additional OAuth 2.0 Access Token types. Sites using the external credentials feature will need to update their registered external identity provider to provide one of the supported access token types.
To update your external identity provider registration, call the CreateOrUpdateEnrollmentConfiguration() method in your enrollment configuration class with the following values for parameters:
-
pApplicationName — the name of the OAuth 2.0 client server you created.
-
pAssigningAuthorityName — the name of the assigning authority, as defined in the Unified Care Record.
-
pUse — the identifier type, as defined in the Unified Care Record.
- pOAuth2AccessTokenType — the access token type selected in your enrollment configuration class. For existing implementations, this will be IdToken .
9.1.3. Upgrading from a version prior to 2023.7
Personal Community 2023.7 added support for optionally specifying an OAuth 2.0 Audience.
After upgrade, call the CreateOrUpdateEnrollmentConfiguration() method in your enrollment configuration class with the following values for parameters:
-
pApplicationName — the name of the OAuth 2.0 client server you created.
-
pAssigningAuthorityName — the name of the assigning authority, as defined in the Unified Care Record.
-
pUse — the identifier type, as defined in the Unified Care Record.
- pOAuth2Audience – Optional. The OAuth2 Audience. OAuth2 Audience (aud) verifies if the access token is intended for a specific recipient or audience, ensuring that the token is used by the right party or application.
- pOAuth2AccessTokenType — the access token type selected in your enrollment configuration class. For existing implementations, this will be IdToken .
10. Verifying Your Upgrade
After you complete all of the installation, configuration, and customization steps for your upgrade:
-
Verify the upgrade:
-
Navigate to the URL for the Personal Community home page: http:// <hostname> / <public-web-application> /index.html .
-
Verify that the version number at the bottom left of the page footer begins with the proper version. For example, after upgrading to Personal Community version 2023.4, your version number may look like: v2023.5.0–0.0.1 .
-
-
If you have configured your external Web server to redirect users to system outage pages, reconfigure it to point them back to the home pages for Personal Community and Workbench.