Skip to main content

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 as Yes/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

  1. To ensure a smooth and efficient upgrade, make sure you have performed the pre-upgrade tasks before starting the upgrade
  2. Stop all productions:
    1. In the Management Portal, select  HealthShare  from the main menu. This displays the  HealthShare Management Portal
    2. In the  HealthShare Management Portal , select the  Stop All  button at the top of the page. At the confirmation dialog, select  OK .
  3. 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.
  4. Activate your new license key.

    To activate a license key:

    1. Log in to the Management Portal as a user with the  %Manager  role.

    2. Go to the   License Key  page ( System Administration  >  Licensing  >  License Key ).

    3. On that page, select  Activate New Key . This displays the  Activate a New License Key  dialog.

    4. On the  Activate  dialog, specify the license key to activate.

    5. Select  Activate .

    For more details about this process, see further instructions in the System Administration guide .

  5. 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

  1. 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"). 
  2. To prevent unwanted failover during upgrading, set  No Failover  on server B.
    1. In the Management Portal, select  Home  System Operation  Mirror Monitor .
    2. On the Mirror Monitor page, select  Set No Failover .
  3. 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.

  4. 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:
    1. Stop the ISCAgent service:

      # systemctl stop ISCAgent.service
      
    2. Disable the ISCAgent service:

      # sudo systemctl disable ISCAgent.service
      
    3. Check the status of the ISCAgent service and make sure it shows that the service is inactive:

      # systemctl status ISCAgent
      
  5. 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.

  6. On Linux systems, start and then enable the updated version of the ISCAgent service from the command line:
    1. Start the ISCAgent service:

      # systemctl start ISCAgent.service
      
    2. Enable the ISCAgent service:

      # sudo systemctl enable ISCAgent.service
      
    3. Check the status of the ISCAgent service and make sure it shows that the service is active:

      # systemctl status ISCAgent
      
  7. To prepare for mirror failover, make sure that the correct server is the backup failover member:

    1. In the Management Portal, select   Home   > System Operation   >   Mirror Monitor.

    2. 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 .

  8. Clear   No Failover   to enable mirror failover:

    1. In the Management Portal, select   Home   >   System Operation   >   Mirror Monitor .

    2. Select   Clear No Failover .

      Note

      If you plan to deploy a system outage message but have not yet done so, deploy it now.

  9. Stop all productions on server A:

    1. In the Management Portal, select   HealthShare   from the main menu. This displays the   HealthShare Management Portal .

    2. In the   HealthShare Management Portal , select the   Stop All   button at the top of the page. At the confirmation dialog, select   OK .

  10. 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.

  11. Verify that server B is the primary failover member:

    1. In the Management Portal, select   Home   >   System Operation   >   Mirror Monitor .

    2. On the Mirror Monitor page, verify that server B appears with the status of   Primary .

  12. 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.
    
  13. Activate all Personal Community namespaces on server B:

    1. Go to the HealthShare  Installer Wizard   ( Management Portal   >   HealthShare   >   Installer Wizard   at the top of the page).

    2. Activate each namespace (listed in the   Name   column). To do this, for each namespace that has an   Activated   value of 0:

      1. Select   Activate , which displays the   Activate Configuration   page for that namespace.

      2. On the   Activate Configuration   page, select   Start .

  14. 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.
  15. Start all productions associated with Personal Community on server B:

    1. From the   Installer Wizard   page, select   HealthShare Management   at the top of the page. This displays the   HealthShare Management Portal .

    2. 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 ).

  16. 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.

  17. On Linux systems, stop and disable the ISCAgent on server A:
    1. Stop the ISCAgent service:

      # systemctl stop ISCAgent.service
      
    2. Disable the ISCAgent service:

      # sudo systemctl disable ISCAgent.service
      
    3. Check the status of the ISCAgent service and make sure it shows that the service is inactive:

      # systemctl status ISCAgent
      
  18. 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.

  19. On Linux systems, start and then enable the updated version of the ISCAgent service from the command line:
    1. Start the ISCAgent service:

      # systemctl start ISCAgent.service
      
    2. Enable the ISCAgent service:

      # sudo systemctl enable ISCAgent.service
      
    3. Check the status of the ISCAgent service and make sure it shows that the service is active:

      # systemctl status ISCAgent
      
  20. Verify that server A is the backup failover member:

    1. In the Management Portal, select   Home   > System Operation   >   Mirror Monitor .

    2. On the Mirror Monitor page, verify that server A appears with the status of   Backup .

  21. On server B, clear   No Failover   to enable mirror failover:

    1. In the Management Portal, select   Home   > System Operation   >   Mirror Monitor .

    2. Select   Clear No Failover .

  22. Stop all productions that are associated with Personal Community on server B:

    1. In the Management Portal, select   HealthShare   from the main menu. This displays the   HealthShare Management Portal .

    2. In the   HealthShare Management Portal , select the   Stop All   button at the top of the page. At the confirmation dialog, select   OK .

  23. 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.

  24. Verify that server A is the primary failover member:

    1. In the Management Portal, select   Home   >   System Operation   >   Mirror Monitor .

    2. On the Mirror Monitor page, verify that server A appears with the status of   Primary .

  25. 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.
    
  26. 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.

  27. Start all productions associated with Personal Community on server A:

    1. From the   Installer Wizard   page, select   HealthShare Management   at the top of the page. This displays the   HealthShare Management Portal .

    2. 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 ).

  28. 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:

  1. Go to the HealthShare  Installer Wizard  (Management Portal > HealthShare  Installer Wizard  at the top of the page).
  2. Activate each namespace (listed in the  Name column). To do this, for each namespace that as an Activated  value of 0:
    1. Select  Activate , which displays the  Activate Configuration  page for that namespace.
    2. 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.

  3. Once all namespaces are reactivated, start all the productions that are associated with Personal Community. To do this:

    1. From the   Installer Wizard   page, select   HealthShare Management   at the top of the page. This displays the   HealthShare Management Portal .

    2. In the   HealthShare Management Portal , select   Start All .

  4. 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:

  1. Verify the upgrade:

    1. Navigate to the URL for the Personal Community home page:   http:// <hostname> / <public-web-application> /index.html .

    2. 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 .

  2. 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.