Skip to main content

HealthShare Personal Community Mirroring Setup Guide





1. Introduction

This guide is intended to be a resource for understanding the TrakCare 

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 of Mirroring Personal Community

Personal Community supports mirroring of databases, which provides fast, reliable, high-availability through automatic failover.

The steps for setting up a Personal Community mirror are described in the next two chapters.

Please read the entire chapter before you begin to configure your system.

Note

InterSystems requires that in a particular HealthShare instance, if any database is mirrored, then all databases that can be mirrored are also mirrored.

InterSystems also strongly suggests that in a multiple instance deployment of HealthShare products, if any instance is mirrored, that all other instances that can be mirrored are also mirrored, in order to achieve the high-availability solution that mirroring represents.

IMPORTANT

As with all HealthShare implementations, configure and test your system thoroughly in a staging environment before moving to a live environment. With mirroring, this is especially important. When you are ready to mirror your production environment, you should already be very familiar with the procedures involved.

2.1. Managing and Deploying Changes

When a complex enterprise system requires changes (such as a software upgrade, a recompilation of classes, or configuration changes), the best practice is to make and test changes on a system other than the live system. Specifically, the best practice is to set up a series of environments as follows:

  1. Development environment   — Use this environment to develop and test code and all other changes. This environment should not be mirrored, even if the production environment is mirrored.

  2. Test environment   — This environment should be mirrored.

  3. User acceptance test (UAT) environment   — Selected users access this environment and test your changes. This environment should be mirrored.

  4. Production/live environment   — This is the environment that has end users. This environment should be mirrored.

InterSystems recommends that you set up such environments and that you follow a process in which you first make changes and test changes in the development environment and then promote the changes to the next environment and test them there. If you find a problem with a change, return to the development environment and make adjustments there as needed. Or, if the changes pass all testing in the test environment, promote them to the UAT environment, and so on.

InterSystems also recommends using source control software to manage the changes, wherever possible.

3. Mirroring a New Instance of Personal Community

Personal Community supports mirroring of databases, which provides fast, reliable, high-availability through automatic failover.

This chapter details the steps needed to configure mirroring in a new installation of Personal Community. If you have already configured your Personal Community, see the next chapter.

IMPORTANT

B efore you begin, InterSystems strongly recommends that you read and understand the   Mirroring   chapter of the   High Availability Guide . It contains important information about network and deployment considerations that you must plan for before you install and configure a mirrored Personal Community. When reading the chapter, keep in mind that you will be configuring a mirror that:

  • has two failover members

  • uses a VIP (Virtual IP Address)

  • uses an arbiter and an ISCAgent

  • uses SSL/TLS (strongly recommended)

Note

B efore you begin, plan for the following:

  • A second machine on the same subnet as your existing Personal Community to host the second failover mirror member.

  • A machine to host the arbiter.

  • X.509 certificates for SSL/TLS encryption of mirrored communication.

  • A Virtual IP Address for the mirror.

  • A shared drive to host your Content Manager customization files.

  • A RAID or backup strategy to keep the shared drive content highly available.

To install and configure a mirrored Personal Community as new installation, follow the steps outlined below.

3.1. Installing Your Personal Community Instances

Install   two   instances of  Personal Community on separate machines, following the steps outlined in the Personal Community Installation Setup Guide :

Keep in mind the following during your installation:

  • The machines hosting the instances must be on the same subnet.

  • Use the same Superserver port and Web server port. Record these values as you will need them in a later step.

  • Designate one instance as instance A and the other as instance B. As you follow the instructions in this document, these designations will make the instructions easier to follow.


Note

Record the instance name, superserver port, and Web server port of each instance, as you will need them in a later step.


Instance A and instance B will be your two failover members.

IMPORTANT

When you finish installing the kit,   do not  continue and follow the instructions in the installation chapter,  Running the Installer Wizard . You will do this in a later step. Instead, come back to this document and go to step 2 below.

3.2. Setting up and Configuring an Arbiter

InterSystems strongly recommends the use of an arbiter in a mirrored Personal Community. An arbiter ensures fast, reliable failovers. Follow the instructions in the section “ Installing the Arbiter ” in the   High Availability Guide .

Note

Record the hostname and IP address of your arbiter as well as the port used by its ISCAgent process (2188 by default). You will need this information in a later step.


3.3. Copying the Content Manager to a Shared Folder

Mirroring in Personal Community applies to databases but not to file systems. Customizations that you create in the Personal Community Content Manager are file-based, and therefore are not mirrored. In order to keep customizations synchronized between your failover members, set up a shared drive for this file-based content that both mirror members can access before you configure Personal Community.

The shared drive will hold the contents of the following folders:

  • < install-dir > / csp   which includes:

    • < install-dir > / csp/hscommlib / < local-namespace >   — A supporting directory used when the user interface is built.

    • < install-dir > / csp / < public_app_name >   — The compiled Public Application folder. The name will be chosen when you initialize the Public Application.

    • < install-di r> / csp / < workbench_app_name >   — The workbench Web application folder. The name will be chosen when you initialize the workbench Web application.

  • < install-dir > /hscommunity-content   which includes:

    • <install-dir> / hscommunity-content / < local-namespace >   — The Content Manager folder.

IMPORTANT

To maintain high-availability, you should have a RAID or backup strategy for the shared drive.

To move the content to the shared drive:

  1. Copy the   < install-dir > / csp /   and   < install-dir > / hscommunity-content /   folders (and their subfolders) from instance A to the shared drive.

  2. If you are on a UNIX® system, set permissions on the folders on the shared drive as described for a dataset directory in the “ UNIX® Users, Groups and Permissions ” section of the “Using InterSystems IRIS on UNIX®, Linux, and Mac OS X” chapter of the   System Administration Guide .

  3. On both instance A and instance B, delete the   < install-dir > / csp /   and   < install-dir > / hscommunity-content /   folders (and their subfolders).

  4. Create a symbolic link or reference for the   < install-dir > / csp /   and   < install-dir > / hscommunity-content /   folders on both instance A and instance B to the folders on the shared drive.

    For example, if you are on UNIX® and the shared drive is named   mydrive , to create the symbolic link, run the following commands on each of your instances:

    ln –s /mydrive/csp csp
    
    ln –s /mydrive/hscommunity-content hscommunity-content
    
    
    
    
    
    

3.4. Creating a Virtual IP and DNS Name

A virtual IP address (VIP) allows external applications to interact with the mirror using a single address, ensuring continuous access on failover.  

Follow the instructions in the section " Configuring a Mirror Virtual IP (VIP) " of the  High Availability Guide to configure your VIP.

Once you create your VIP, assign a DNS name for it on your DNS server to make it easier to refer to the VIP in your productions.

The table below shows how this might be set up:


IP Address

DNS Name

Instance A

10.1.1.10

HS-Community-nodeA. my-company .com

Instance B

10.1.1.11

HS-Community-nodeB. my-company .com

Mirror

10.1.1.100

HS-Community-mirror. my-company .com

The VIP will serve as the  network host name when you configure Personal Community.

Note

Record the IP address, DNS name, CIDR mask, and network interface as you will need these values in a later step.

3.5. Creating TLS Configurations for the Mirror

Follow the instructions in “ Create or Edit a TLS Configuration ” to create SSL/TLS configurations for your mirror. You must perform the procedure both on instance A and on instance B. As part of this procedure, you will enable mirroring on both instances.

Note

While SSL/TLS is not strictly required for mirror communications, InterSystems strongly recommends its use for systems that deal with confidential health data.

3.6. Configuring the ISCAgents

Follow the instructions in the “ Configuring the ISCAgent ” section of the   High Availability Guide   to configure the ISCAgent on instance A and instance B. It is crucial that the ISCAgent is configured to start automatically when the operating system starts on both instance A and instance B.

Note

Record the ISCAgent port number if you use a value other than the default, as you will need it in a later step.

3.7. Creating and Configuring the Mirror

Review the instructions in the “ Configuring Mirroring ” section of the   High Availability Guide . In the steps described under the section “ Creating a Mirror .”

Note

You have already performed the following procedures:

  • Installing the arbiter

  • Starting the ISCAgent

  • Securing the mirror with SSL/TLS

Refer to the table below for the settings to use as you continue to configure the mirror:

Setting Value Value on Your System
First Failover Member Instance A’s InterSystems IRIS for Health™ instance name you noted in an earlier step.
Second Failover Member Instance B’s InterSystems IRIS for Health instance name you noted in an earlier step.
Mirror Name Select a name using 1 to 15 alphanumeric characters.
Require SSL/TLS Yes . You should have configured this in an earlier step.
Use Arbiter Yes . Provide the hostname, IP and port you noted in an earlier step.
Use Virtual IP Yes . Provide the VIP or DNS name, CIDR mask, and network interface value you noted in an earlier step.
Mirror Member Name For example, “MyCommunity_Mirror_A” and “Community_Mirror_B”.
Superserver Address Accept the default.
ISCAgent Port Enter the ISCAgent port number on this instance that you noted in an earlier step. The default is 2188.
Quality of Service Timeout Accept the default. You can adjust this later if issues arise.
Mirror Private Address Accept the default.
Compression Mode for Failover Accept the default,   System Selected
Compression Mode for Async Accept the default,   System Selected
Mirrored Databases HSSYS only. (After you create the Personal Community productions in a later step, two additional databases will be automatically added to the mirror.)

Perform the following steps to complete the configuration of your mirror:

Note

Some of the instructions in the referenced sections below exclude the submenu  Mirror Settings . If you do not see the menu option that is referenced, click  Mirror Settings  and you will see the option.

  1. Configure instance A as the first failover member as described in “ Create a Mirror and Configure the First Failover Member .”

  2. Configure instance B as the second failover member as described in “ Configure the Second Failover Member .”

  3. On instance A, perform the steps in “ Authorize the Second Failover Member .”

  4. Confirm that your mirror is configured correctly and is running as described in “ Review Failover Member Status in the Mirror Monitor ” (use   Home   >   System Operation   >   Mirror Monitor ).

CAUTION

Do not add any databases to the mirror yet.

Now your mirror contains two failover members:

  • Instance A is the primary failover member.

  • Instance B is the backup failover member.

Confirm that the  Mirror Database checkbox is selected in the Personal Community configuration in the Installer Wizard on  instance A . If it is not selected, select it, save the configuration, and reactivate your Personal Community namespace on instance A.

Note

Going forward, this document will refer to “primary failover member” and “backup failover member” at times, rather than “instance A” and “instance B”.

3.8. Setting the HealthShare Network Host Name to the Mirror VIP

The network host name forms part of each URL that is created when you configure your productions in Personal Community. Since this is a mirrored system, it is important that this value reflect the mirror VIP rather than the network name of each individual instance.
  1. On the primary failover member, log in to the Management Portal with administrator privileges.

  2. Select   HealthShare   to open the HealthShare Management portal.

  3. Select the   HealthShare  >  Installer Wizard   link in the banner.

  4. Select   Configure Network Host Name .

  5. Enter the VIP or DNS name in the   Network Host Name   field.

  6. Select   Save .

3.9. Adding HSSYS to the Mirror

Now that you have create the mirror, you can mirror the databases.  For a new installation, you only have to mirror one database,  HSSYS .  When you configure Personal Community using the Installer Wizard, all of the databases that are created in that process will then be automatically mirrored.

Review the instructions in the " Add an Existing Database to the Mirror "   section of the  High Availability Guide.

To add the  HSSYS  database to the mirror:

  1. On the primary failover member, log in to the Management Portal with administrator privileges.
  2. Select  System Administration > Configuration > System Configuration > Local Databases .
  3. In the row of the table for  HSSYS , click  Add to Mirror <your_Mirror_name>.
  4. Click  Add to confirm the procedure.

3.10. Copying HSSYS to the Backup Failover Member

The simplest way to create a copy of the   HSSYS   database on the backup failover member is to use the copy command as described in the procedure below.

Note

Alternatively, you can use a backup/restore procedure to create a backup on the primary member and restore it on the backup member. Refer to the “ Add an Existing Database to the Mirror ” section of the  High Availability Guide  for backup/restore considerations and links to information about backup/restore strategies. Also see the “ Run Database Backups ” section of the  HealthShare Monitoring and Operations Guide  for Healthshare-specific guidance on backup and restore strategies. If you do use an alternate method, remember to stop your instances as described below before proceeding.

  1. Stop the InterSystems IRIS for Health instances in your mirror:

    1. Stop instance B, the backup failover member first, to prevent mirror failover.

    2. Stop instance A, the primary failover member.

  2. Copy the   HSSYS   database from instance A to instance B:

    1. Copy the   <installdir> /mgr/hssys/IRIS.DAT   file from the primary member to the same directory on the backup member, overwriting the existing   IRIS.DAT   file.

    2. If you are on a UNIX® system: on the backup member, set UNIX® permissions on the   IRIS.DAT   file as described in the “ UNIX® Users, Groups and Permissions ” section of the “Using InterSystems IRIS on UNIX®, Linux, and Mac OS X” chapter of the   System Administration Guide .

  3. Restart the InterSystems IRIS for Health instances in your mirror:

    1. Start instance A so it comes up as the primary failover member.

    2. Next start instance B. It will start as the backup.

3.11. Activating and Catching up the HSSYS Databases on the Backup Failover Member

Now that the   HSSYS   database is copied over, activate and catch up the database on the backup failover member:
  1. Log in to the Management Portal on instance B, the backup failover member, with administrator privileges.

  2. Select   System Operation   >   Mirror Monitor .

  3. In the mirrored database list, select   Catchup   for   HSSYS   from the list of available databases. The catchup operation will also activate if necessary.

For more information on this page (including information on the possible statuses of the mirror members), see “ Monitoring Mirrors ” in the chapter “Mirroring” in the   High Availability Guide .

3.12. Refreshing the Mirror Agent

Mirroring in HealthShare products uses a mirror agent (in addition to the ISCAgent you configured earlier) to keep the instance GUIDs of the two mirror members synchronized.

Follow the procedure below to refresh the mirror agent on your mirror members by stopping the agent and restarting it:

  1. Log into the Management Portal on the primary failover member with administrator privileges.
  2. Select HealthShare to open the HealthShare Management Portal.
  3. Select the Mirror Agent Monitor link in the banner.
  4. The agent auto-starts every five minutes, so it may already be running.
  5. If the agent is running, select Stop Agent , and wait for the Start Agent button to become active.
  6. Select Start Agent .
  7. Repeat this procedure on the backup failover member.

3.13. Creating the Personal Community Productions

Follow the instructions in the “ Running the Installer Wizard ” section of the Personal Community Installation Setup Guide   to set up and configure the Personal Community productions on the primary failover member. Since your system is mirrored, the configuration will also occur automatically on the backup failover member.

Note

Keep in mind the following:

  • When you run the Installer Wizard, accept the default value in the   Network Name   field. This value should default to   <Network Host Name> : <Local Name> . Since you set the network host name to the mirror VIP or DNS name in an earlier step, the Installer Wizard will create your Personal Community production correctly for mirroring only if you use the default value.

  • Record the value you entered for   Local Name   as you will need it in a later step. If, for example, you entered   HSCommunity   as your   Local Name , the Installer Wizard creates two namespaces:

    • HSCommunity

    • HSCommunityREPORTS   (This value will be entered into your ^ZMIRROR routine in a later step.)

  • Select the   Mirror Database   checkbox in the   Installer Wizard   when you create your Personal Community production.


3.14. Failing Over and Activating the Reporting Production in Instance B

Activating your reporting production created tasks on the primary. Tasks are not mirrored. To create the tasks on the backup, you must fail over to the backup and then reactivate the Personal Community reporting production on the (former) backup failover member:

  1. Stop instance A, the primary failover member, to induce failover to the backup.

  2. Confirm that instance B is now the primary in the Mirror Monitor (   Home   >   System Operation   >   Mirror Monitor   ).

  3. Restart instance A. It will come up as the backup failover member.

  4. On the new primary, Instance B, open the HealthShare Management Portal.

  5. Click the   Installer Wizard   link in the banner.

  6. Reactivate the reporting production:

    1. Click   Activate .

    2. In the   Activate Configuration   dialog, click   Start .

    3. Wait for activation to complete.

    4. When you see the   Activation Done   message, click   Close .

3.15. Creating the ^ZMIRROR Routine

The ^ZMIRROR routine implements configuration-specific logic and mechanisms for specific mirroring events, such as a failover member becoming primary. The ^ZMIRROR has four entry points. The routine below uses the   NotifyBecomePrimary   entry point to start the Personal Community productions on failover, and to reset the Analytics agents in your reporting namespace.

Create a ^ZMIRROR routine on   both   mirror members as follows:

  1. On the primary member, open Studio.

  2. Change to the   %SYS   namespace.

  3. Create a new   ObjectScript Routine .

  4. Enter the following code, replacing Configuration Manager   with the REPORTS namespace you created in the Installer Wizard

    ZMIRROR
        quit
     
    NotifyBecomePrimary() public {
    
        // Start productions after failover
        New $namespace
        set $namespace="HSLIB"
    
        // Comment out the following line if you are using production auto-start
        do ##class(HS.Director).StartAll()
    
        // Reset DeepSee agents in reporting namespace
        set $namespace="MY_PERSONAL_COMMUNITY_REPORTING_NAMESPACE"
        do ##class(%DeepSee.Utils).%Reset(0)
    
    }
    

    Refer to the “ Using the ^ZMIRROR Routine ” section of the “Mirroring” chapter of the   High Availability Guide   for more details on the ^ZMIRROR routine.

  5. Save the routine as   ZMIRROR.mac   .

  6. Compile the routine.

  7. Duplicate this routine on the backup failover member.

  8. Save and compile it.


Note

While HealthShare provides the  HS.Director.StartAll() method to start productions in the correct order, you should use production auto-start instead of calling  HS.Director.StartAll() in your ^ZMIRROR routine.



3.16. Completing the Personal Community Installation

You can now complete the steps in the following sections of the Personal Community Installation Setup Guide :


Note

Please read the mirroring considerations in the section below before you begin configuring Personal Community.

3.16.1. Considerations for Mirrored Systems

As you configure Personal Community, you may perform certain actions on the primary failover member that must be manually replicated on the backup failover member. Examples include configuration that involves:

  • Custom database resources.

  • Non-standard mappings.

  • Creating tasks.

  • Information in files and file system locations (with the exception of files in the   csp   and   hscommunity-content   folders, as these were put on a shared drive in an earlier step).

  • Custom code that you write in HSCUSTOM , including SDA extensions, as code databases are not mirrored.

  • Any configuration you perform in   %SYS.

  • IRIS roles (as opposed to federated HealthShare roles).

  • System-level settings.

4. Mirroring an Existing Instance of Personal Community

Personal Community supports mirroring of databases, which provides fast, reliable, high-availability through automatic failover.

This chapter details the steps needed to configure mirroring in an existing Personal Community. If you have not yet installed and configured your Personal Community, see the prior chapter.

Note

M irroring an existing Personal Community will require a planned outage for the final stages of configuration, beginning at the step where you stop your productions.

Before you mirror your production system, practice the procedures in a staging environment so you are familiar with them. To help minimize the system downtime in your production environment you can employ the following strategies:

  • Use the API methods in the   SYS.Mirror   class to create the mirror, add the backup failover member, add databases, activate and catchup databases.

  • Automate the copy or backup and restore procedure that you use to copy the mirrored databases to the backup failover member.

IMPORTANT

B efore you begin, InterSystems strongly recommends that you read and understand the   Mirroring   chapter of the   High Availability Guide . It contains important information about network and deployment considerations that you must plan for before you install and configure a mirrored Personal Community. When reading the chapter, keep in mind that you will be configuring a mirror that:

  • has two failover members

  • uses a VIP (Virtual IP Address)

  • uses an arbiter and an ISCAgent

  • uses SSL/TLS (strongly recommended)

Note

B efore you begin, plan for the following:

  • A second machine on the same subnet as your existing Personal Community to host the second failover mirror member.

  • A machine to host the arbiter.

  • X.509 certificates for SSL/TLS encryption of mirrored communication.

  • A Virtual IP Address for the mirror.

  • A shared drive to host your Content Manager customization files.

  • A RAID or backup strategy to keep the shared drive content highly available.

To configure an existing Personal Community installation for mirroring, follow the steps outlined below.

4.1. Installing a Second Instance of Personal Community

Install a second instance of Personal Community, following the steps outlined in the first two sections of the Personal Community Installation Setup Guide :

Keep in mind the following during your installation:

  • The new instance must be the same version as your existing Personal Community instance.

  • The new instance must be installed on a separate machine from your existing Personal Community.

  • Both machines must be on the same subnet.

  • Use the same Superserver port and Web server port in the new instance as in your existing Personal Community.

  • Designate the new instance as instance B. Your existing Personal Community will be instance A. As you follow the instructions in this document, these designations will make the instructions easier to follow.


Note

Record the instance name, superserver port, and Web server port of your new instance, as you will need them in a later step.

Instance A and instance B will be the two failover members in your mirror, with Instance A initially serving as the primary failover member.

IMPORTANT

When you finish installing the kit,  do not  continue and follow the instructions in the third section of the installation chapter,  Running the Installer Wizard . You will do this in a later step. Instead, come back to this document and go to step 2 below.

4.2. Creating the Personal Community Databases on Instance B

In order to set up your mirror, the same databases must exist on both failover members. Instance A is a fully configured Personal Community, and instance B is not, so you must create databases on instance B to match instance A.

Only databases containing data are mirrored. Databases containing code are not mirrored.

You will mirror:

  • HSSYS  – This database already exists on both failover members
  • your Personal Community database
  • the associated reporting database
  • HSAUDIT (if it exists)

You will not mirror:

  • HSCUSTOM  
  • HSLIB  
  • HSCOMMLIB

The table below will help you organize your process.

Databases on this Instance Name of Database on Your System Location of Database on the File System
HSSYS HSSYS <install-dir> /mgr/HSSYS  
Personal Community database

Personal Community reporting database

HSAUDIT (if it exists)

To create the new databases on instance B to match instance A:

  1. On instance A, collect the following information:
    • The name of your Personal Community database. Usually the database name is the same as the namespace name.
    • The name of your Personal Community reporting database. Typically this is  <Personal_Community_database> REPORTS
    • The directories on your file system where your databases are stored, typically <install-dir> / mgr/ <database_name>
  2. On instance B, log into the Management Portal with administrator privileges.
  3. Navigate to  Home  System Administration Configuration System Configuration Local Databases .
  4. Click  Create New Database .
  5. In the  Database Wizard  fields:
    • Enter the name of your database – Enter the name of your Personal Community database on instance A. (Database names in HealthShare are all in capital letters.)
    • Database directory – Match the relative pathname of the database location on instance A.
  6. Click  Next .
  7. On the details page, accept the defaults.
  8. Click  Next .
  9. On the resources page, select  Create a new resource .
  10. In the  Create a New Resource Name   dialog click  Save to accept the default values (Do  not provide public RW permissions with this resource).
  11. Click  Finish .
  12. Click  Create New Database again.
  13. In the  Database Wizard dialog box, enter the following:
    • Enter the name of your database – Enter the name of your Personal Community  reporting database on instance A. (Database names in Personal Community are all in capital letters.)
    • Database directory – Match the relative pathname of the reporting database location on instance A.
  14. Click  Next .
  15. On the details page, accept the defaults.
  16. Click  Next .
  17. On the resources page, select  Create a new resource .
  18. In the  Create a New Resource Name   dialog click  Save to accept the default values (Do  not provide public RW permissions with this resource).
  19. Click  Finish .

This process creates an empty IRIS.DAT file for each database.

Note

Record the names of the databases that you create, as you will need them in a later step.


4.3. Recreating Customizations on Instance B

While most of the configuration in Personal Community occurs in the databases that will be mirrored, when you configured Personal Community, you may have performed certain actions outside of those databases. You must replicate on instance B any of the following configuration tasks that you performed on instance A:

  • Custom database resources.

  • Non-standard mappings.

  • Creating tasks.

  • Information in files and file system locations (with the exception of files in the   csp   and   hscommunity-content   folders, as these will be put on a shared drive in a later step).

  • Custom code that you wrote in any local databases such as   HSCUSTOM , including SDA extensions, as code databases are not mirrored.

  • Any configuration you performed in   %SYS .

  • IRIS roles (as opposed to federated HealthShare roles).

  • System-level settings.

4.4. Setting up a Shared Drive

Mirroring in Personal Community applies to databases but not to file systems.  Customizations that you create in the Personal Community Content Manager are file-based, and therefore are not mirrored.  In order to keep customizations synchronized between your failover members, set up a shared drive to host this file-based content.  In a later step, you will copy the files to the shared drive and a set up links from your Personal Community instances to the content on the shared drive.

IMPORTANT

To maintain high-availability, you should have a RAID or backup strategy for the shared drive.


4.5. Creating a Virtual IP and DNS Name

A virtual IP address (VIP) allows external applications to interact with the mirror using a single address, ensuring continuous access on failover.  

Follow the instructions in the section " Configuring a Mirror Virtual IP (VIP) " of the  High Availability Guide to configure your VIP.

Once you create your VIP, assign a DNS name for it on your DNS server to make it easier to refer to the VIP in your productions.

The table below shows how this might be set up:


IP Address

DNS Name

Instance A

10.1.1.10

HS-Community-nodeA. my-company .com

Instance B

10.1.1.11

HS-Community-nodeB. my-company .com

Mirror

10.1.1.100

HS-Community-mirror. my-company .com

The VIP will serve as the  network host name when you configure Personal Community.

Note

Record the IP address, DNS name, CIDR mask, and network interface as you will need these values in a later step.

4.6. Setting up and Configuring an Arbiter

InterSystems strongly recommends the use of an arbiter in a mirrored Personal Community. An arbiter ensures fast, reliable failovers. Follow the instructions in the section “ Installing the Arbiter ” in the   High Availability Guide .

Note

Record the hostname and IP address of your arbiter as well as the port used by its ISCAgent process (2188 by default). You will need this information in a later step.


4.7. Configuring the ISCAgents

Follow the instructions in the “ Configuring the ISCAgent ” section of the   High Availability Guide   to configure the ISCAgent on instance A and instance B. It is crucial that the ISCAgent is configured to start automatically when the operating system starts on both instance A and instance B.

Note

Record the ISCAgent port number if you use a value other than the default, as you will need it in a later step.

4.8. Creating TLS Configurations for the Mirror

Follow the instructions in “ Create or Edit a TLS Configuration ” to create SSL/TLS configurations for your mirror. You must perform the procedure both on instance A and on instance B. As part of this procedure, you will enable mirroring on both instances.

Note

While SSL/TLS is not strictly required for mirror communications, InterSystems strongly recommends its use for systems that deal with confidential health data.

4.9. Creating and Configuring the Mirror

Review the instructions in the “ Configuring Mirroring ” section of the   High Availability Guide . In the steps described under the section “ Creating a Mirror .”

Note

You have already performed the following procedures:

  • Installing the arbiter

  • Starting the ISCAgent

  • Securing the mirror with SSL/TLS

Refer to the table below for the settings to use as you continue to configure the mirror:

Setting Value Value on Your System
First Failover Member Instance A’s InterSystems IRIS for Health™ instance name you noted in an earlier step.
Second Failover Member Instance B’s InterSystems IRIS for Health instance name you noted in an earlier step.
Mirror Name Select a name using 1 to 15 alphanumeric characters.
Require SSL/TLS Yes . You should have configured this in an earlier step.
Use Arbiter Yes . Provide the hostname, IP and port you noted in an earlier step.
Use Virtual IP Yes . Provide the VIP or DNS name, CIDR mask, and network interface value you noted in an earlier step.
Mirror Member Name For example, “MyCommunity_Mirror_A” and “Community_Mirror_B”.
Superserver Address Accept the default.
ISCAgent Port Enter the ISCAgent port number on this instance that you noted in an earlier step. The default is 2188.
Quality of Service Timeout Accept the default. You can adjust this later if issues arise.
Mirror Private Address Accept the default.
Compression Mode for Failover Accept the default,   System Selected
Compression Mode for Async Accept the default,   System Selected
Mirrored Databases HSSYS only. (After you create the Personal Community productions in a later step, two additional databases will be automatically added to the mirror.)

Perform the following steps to complete the configuration of your mirror:

Note

Some of the instructions in the referenced sections below exclude the submenu  Mirror Settings . If you do not see the menu option that is referenced, click  Mirror Settings  and you will see the option.

  1. Configure instance A as the first failover member as described in “ Create a Mirror and Configure the First Failover Member .”

  2. Configure instance B as the second failover member as described in “ Configure the Second Failover Member .”

  3. On instance A, perform the steps in “ Authorize the Second Failover Member .”

  4. Confirm that your mirror is configured correctly and is running as described in “ Review Failover Member Status in the Mirror Monitor ” (use   Home   >   System Operation   >   Mirror Monitor ).

CAUTION

Do not add any databases to the mirror yet.

Now your mirror contains two failover members:

  • Instance A is the primary failover member.

  • Instance B is the backup failover member.

Confirm that the  Mirror Database checkbox is selected in the Personal Community configuration in the Installer Wizard on  instance A . If it is not selected, select it, save the configuration, and reactivate your Personal Community namespace on instance A.

Note

Going forward, this document will refer to “primary failover member” and “backup failover member” at times, rather than “instance A” and “instance B”.

4.10. Stopping Your Productions

Stop your Personal Community productions:

  1. On the primary failover member, log in to the Management Portal with administrator privileges.

  2. Select   HealthShare   to open the HealthShare Management portal.

  3. Select   Stop All .

  4. Select OK   in the confirmation dialog.

  5. Wait for the   Done   message.

  6. Select OK .

4.11. Copying the Content Manager to the Shared Drive

Mirroring in Personal Community applies to databases but not to file systems. Customizations that you create in the Personal Community Content Manager are file-based, and therefore are not mirrored. In order to keep customizations synchronized between your failover members, set up a shared drive for this file-based content that both mirror members can access before you configure Personal Community.

The shared drive will hold the contents of the following folders:

  • < install-dir > / csp   which includes:

    • < install-dir > / csp/hscommlib / < local-namespace >   — A supporting directory used when the user interface is built.

    • < install-dir > / csp / < public_app_name >   — The compiled Public Application folder. The name will be chosen when you initialize the Public Application.

    • < install-di r> / csp / < workbench_app_name >   — The workbench Web application folder. The name will be chosen when you initialize the workbench Web application.

  • < install-dir > /hscommunity-content   which includes:

    • <install-dir> / hscommunity-content / < local-namespace >   — The Content Manager folder.

IMPORTANT

To maintain high-availability, you should have a RAID or backup strategy for the shared drive.

To move the content to the shared drive:

  1. Copy the   < install-dir > / csp /   and   < install-dir > / hscommunity-content /   folders (and their subfolders) from instance A to the shared drive.

  2. If you are on a UNIX® system, set permissions on the folders on the shared drive as described for a dataset directory in the “ UNIX® Users, Groups and Permissions ” section of the “Using InterSystems IRIS on UNIX®, Linux, and Mac OS X” chapter of the   System Administration Guide .

  3. On both instance A and instance B, delete the   < install-dir > / csp /   and   < install-dir > / hscommunity-content /   folders (and their subfolders).

  4. Create a symbolic link or reference for the   < install-dir > / csp /   and   < install-dir > / hscommunity-content /   folders on both instance A and instance B to the folders on the shared drive.

    For example, if you are on UNIX® and the shared drive is named   mydrive , to create the symbolic link, run the following commands on each of your instances:

    ln –s /mydrive/csp csp
    
    ln –s /mydrive/hscommunity-content hscommunity-content
    
    
    
    
    
    

4.12. Setting the HealthShare Network Host Name to the Mirror VIP

The network host name forms part of each URL that is created when you configure your productions in Personal Community. Since this is a mirrored system, it is important that this value reflect the mirror VIP rather than the network name of each individual instance.
  1. On the primary failover member, log in to the Management Portal with administrator privileges.

  2. Select   HealthShare   to open the HealthShare Management portal.

  3. Select the   HealthShare  >  Installer Wizard   link in the banner.

  4. Select   Configure Network Host Name .

  5. Enter the VIP or DNS name in the   Network Host Name   field.

  6. Select   Save .

Note

Changing the Network Host Name may not be reflected in the  Network Name  field in the Installer Wizard configuration for your current Personal Community namespaces. However, when you activate the configurations in a later step, the  Network Host Name  that you just set will in fact be used.

Note

Record the following information as you will need it in a later step:

  • Former host name value (this is often the machine name or ID)

  • Instance name

  • Superserver port

  • Web server port

  • Personal Community namespace

  • Personal Community reporting namespace, typically  <Personal-Community-namespace> REPORTS

4.13. Modifying the Service Registry Entries in the Unified Care Record

In an earlier step, you modified the   network host name   on instance A to the VIP or DNS name. Now, in the Unified Care Record that is associated with your Personal Community, you must modify the   host   value in any service registry entries to match the new   network host name   value for the Personal Community mirror.
  1. Log in to the Management Portal on your Unified Care Record with administrator privileges.

  2. Navigate to   HealthShare   >   Registry_name   >   Registry Management   >   Service Registry

  3. In the   Service Type   field at the top of the page, select SOAP.

  4. In the   Search   field at the top of the page, enter the old host value for Personal Community (the machine name or identifier you used for Personal Community before you modified the network host name to use the VIP).

  5. Tab out of the   Search   field. Now you have a list of all of the Service Registry entries that you must modify, as they point use the old host name rather than the new network host name. Keep in mind that there may be several pages of entries.

    Entries for Personal Community typically include:

    • PIX entries for Personal Community.

    • Sync entries for Personal Community.

  6. For each entry located by the search, modify the   Host   setting to match the new network host name for the VIP that you created in an earlier step:

    1. Select the entry in the table.

    2. Update the value in the   Host   field to the network host name value for the Personal Community mirror.

    3. Tab out of the field.

    4. Click   Save .

  7. When you have finished editing all of the entries found, the text   No results   should appear in the list of   Services currently defined   when your old host name is in the   Search   field.

4.14. Adding the Databases to the Mirror

Review the instructions in the " Add an Existing Database to the Mirror " section of the  High Availability Guide .

To add your Personal Community database to the mirror:

  1. On instance A, the primary failover member, log in to the Management Portal with administrator privileges.
  2. Select  System Administration  Configuration System Configuration Local Databases .
  3. Click  Add to Mirror .
  4. Select the following databases from the list:
    • HSSYS  
    • your Personal Community database
    • your Personal Community  reporting database
    • HSAUDIT (if it exists)
  5. Click  Add .
  6. Wait several minutes to allow  InterSystems IRIS for Health TM  to switch these databases to mirror journaling.

4.15. Copying the Databases to Instance B

The simplest way to create a copy of your databases on the backup failover member is to use the copy command as described in the procedure below.

Note

Alternatively, you can use a backup/restore procedure to create a backup on the primary member and restore it on the backup member. Refer to the “ Add an Existing Database to the Mirror ” section of the  High Availability Guide  for backup/restore considerations and links to information about backup/restore strategies. Also see the “ Run Database Backups ” section of the  HealthShare Monitoring and Operations Guide  for Healthshare-specific guidance on backup and restore strategies. If you do use an alternate method, remember to stop your instances as described below before proceeding.

  1. Stop the InterSystems IRIS for Health instances in your mirror:

    1. Stop instance B, the backup failover member, first, to prevent mirror failover.

    2. Stop instance A.

  2. Copy the   HSSYS   database and   both   your Personal Community database and your Personal Community   reporting   database from the primary to the backup:

    1. For each database, copy the   <installdir> /mgr/ < DATABASE_name> /IRIS.DAT   file from the primary member to the same directory on the backup member, overwriting the existing   IRIS.DAT   file.

    2. If you are on a UNIX® system: on the backup member, set UNIX® permissions on the   IRIS.DAT   file as described in the “ UNIX® Users, Groups and Permissions ” section of the “Using InterSystems IRIS on UNIX®, Linux, and Mac OS X” chapter of the   System Administration Guide .

  3. Restart the InterSystems IRIS for Health instances in your mirror:

    1. Start instance A, so it comes up as the primary failover member.

    2. Next start instance B.

4.16. Activating and Catching up the Databases on the Backup Failover Member

Now that   HSSYS   and the Personal Community databases are copied over, activate and catch up the databases on the backup failover member:
  1. Log in to the Management Portal on instance B, the backup failover member, with administrator privileges.

  2. Select   System Operation  >  Mirror Monitor .

  3. In the   Select an action   dropdown, select   Catchup , then select   Go . A list of databases will appear.

  4. From the list of databases, select:

    • HSSYS

    • Your Personal Community database, which typically is named after the Personal Community namespace

    • Your Personal Community reporting database, which typically is named after the Personal Community reporting namespace

    • Your audit database

    Each of these databases will have catchup or catchup and activation applied as needed.

For more information on this page (including information on the possible statuses of the mirror members), see “ Monitoring Mirrors ” in the "Mirroring" chapter in the   High Availability Guide .

4.17. Refreshing the Mirror Agent

Mirroring in HealthShare products uses a mirror agent (in addition to the ISCAgent you configured earlier) to keep the instance GUIDs of the two mirror members synchronized.

Follow the procedure below to refresh the mirror agent on your mirror members by stopping the agent and restarting it:

  1. Log into the Management Portal on the primary failover member with administrator privileges.
  2. Select HealthShare to open the HealthShare Management Portal.
  3. Select the Mirror Agent Monitor link in the banner.
  4. The agent auto-starts every five minutes, so it may already be running.
  5. If the agent is running, select Stop Agent , and wait for the Start Agent button to become active.
  6. Select Start Agent .
  7. Repeat this procedure on the backup failover member.

4.18. Reactivating the Personal Community Productions

Now that you have created the mirror and added the databases to it, reactivate your productions on the primary failover member.  This will perform the Personal Community configuration on both the primary and the backup failover members, as they are now mirrored.

  1. Log into the Management Portal on the primary failover member with administrator privileges.
  2. Click  HealthShare to open the HealthShare Management Portal.
  3. Click the  Installer Wizard  link in the banner.
  4. Locate your Personal Community production in the table.
  5. Click  Activate .
  6. In the  Activate Configuration dialog, click  Start .
  7. Wait for activation to complete.  When you see the  Activation Done message, click  Close .
  8. Locate your Personal Community reporting production in the table.
  9. Click  Activate .
  10. In the  Activate Configuration  dialog, click  Start .
  11. Wait for activation complete.  When you see the  Activation Done message, click  Close .

HealthShare creates namespace-specific log files for activations in the  <install-dir>\mgr directory.  When your activation completes, you can check the highest incremented log file for the relevant namespace to confirm that everything worked correctly or to detect any errors.  This file will be named  HS.Util.Installer.<namespace>-<#>.log When inspecting the log files, pay particular attention to entries with [WARNING] or [ERROR]  - [WARNING] indicates that an action should be taken, while [ERROR] indicates that an error occurred during activation.


4.19. Modifying the System Defaults in your Personal Community Production

When you initially installed and configured Personal Community, a set of system defaults was created in your production. Some of these entries refer to the local instance name rather than the new network host name for the mirror.

To update entries on the system defaults page to refer to the network host name:

  1. Log in to the Management Portal on your primary failover member.

  2. Change to your Personal Community namespace.

  3. Go to   Home   >   Interoperability   >   Configure   >   System Default Settings .

  4. Examine the table and locate any rows where the   Setting Value   references the local instance name.

  5. For each row you locate:

    1. Click on the row in the table.

    2. Click   Edit .

    3. In the   Setting Value   field, select the local instance name and replace it with the network host name.

    4. Click   Save .

Refer to the section   Specifying Initial Values for System Default Settings   in the Personal Community Installation Setup Guide   for details on the settings.

4.20. Modifying the Base URL in the Workbench

The Personal Community Workbench maintains a site URL. This must be updated to use the network host name instead of the local instance name.

To update the Workbench   Personal Community base URL   to refer to the network host name:

  1. On your primary failover member, log into the Workbench with administrator privileges.

  2. Click   Setup .

  3. Click   Site Configuration .

  4. Edit the value in the   Personal Community base URL   field, replacing the local instance name with the network host name.

  5. Click   Apply .

4.21. Exporting the Reporting Tasks

Export the reporting tasks from instance A in preparation for failing over and duplicating them on instance B.
  1. On your primary failover member, log into the Management Portal with administrator privileges.

  2. Navigate to   System Operation  >  Task Manager  >  Task Schedule .

  3. Locate the following tasks:

    • Cube Manager Build -   <reporting_namespace>

    • Cube Manager Synch -   <reporting_namespace>

  4. For each task:

    1. Click the name to view the task details.

    2. Click   Export .

    3. Provide the path and file name for the export.

    4. Click   Perform Action Now .

  5. Move the export files to a location accessible to the backup failover member.

4.22. Failing Over and Setting up the Tasks and Web Applications

Fail over to the backup member, import your tasks, and create your Web applications to complete your configuration of instance B:

  1. Stop instance A, the primary failover member, to induce failover to the backup.

    • On a UNIX® system, issue the command iris stop <instance-name> .

    • On a Windows system, from the   <install-dir> \bin   directory, issue the command iris stop <instance-name> , or stop the instance from the HealthShare cube.

    For details on the   iris   command see “ Controlling an InterSystems IRIS Instance ” in the   System Administration Guide .

    For details on failing over, see “ Mirror Outage Procedures ” in the   High Availability Guide .

  2. Log into the Management Portal with administrator privileges on instance B and confirm that it is now the primary by opening the Mirror Monitor (   Home   >   System Operation   >   Mirror Monitor   ).

  3. Restart instance A. It will come up as the backup failover member:

    • On a UNIX® system, issue the command iris start <instance-name> .

    • On a Windows system, from the   <install-dir> \bin   directory, issue the command iris start <instance-name> , or start the instance from the HealthShare cube.

  4. Import the tasks:

    1. Now that it is the primary, log into the Management Portal on instance B with administrator privileges.

    2. Navigate to   System Operation   >   Task Manager   >   Import Tasks .

    3. Browse for and import the tasks that you exported in an earlier step.

  5. Create the Web applications:

    1. On instance B, open the terminal and run the following code, replacing PERSONAL_COMMUNITY_namespace  with the name of your Personal Community namespace, and PUBLIC_WEB_APPLICATION_name  with the name of your public Web application (preceded by a forward-slash as shown in the example):

       zn "PERSONAL_COMMUNITY_namespace"
       set pCSPApplication = "/PUBLIC_WEB_APPLICATION_name"
       set status = ##class(HSPortal.Utils).%CreatePublicCSPApplication(pCSPApplication)
      
    2. Verify that the return status is success. This creates   /public   and   /public/report , where “public” is the public Web application name.

    3. In the same terminal, now run the following code, replacing WORKBENCH _WEB_APPLICATION_name   with the name of your workbench Web application (preceded by a forward-slash as shown in the example): 

       set pCSPApplication = "/WORKBENCH_WEB_APPLICATION_name"
       set status = ##class(HSPortal.Utils).%CreateWorkbenchCSPApplication(pCSPApplication)
      
    4. Verify that the return status is success. This creates   /workbench   and   /workbench/report , where “workbench” is the workbench Web application name.

4.23. Creating the ^ZMIRROR Routine

The ^ZMIRROR routine implements configuration-specific logic and mechanisms for specific mirroring events, such as a failover member becoming primary. The ^ZMIRROR has four entry points. The routine below uses the   NotifyBecomePrimary   entry point to start the Personal Community productions on failover, and to reset the Analytics agents in your reporting namespace.

Create a ^ZMIRROR routine on   both   mirror members as follows:

  1. On the primary member, open Studio.

  2. Change to the   %SYS   namespace.

  3. Create a new   ObjectScript Routine .

  4. Enter the following code, replacing Configuration Manager   with the REPORTS namespace you created in the Installer Wizard

    ZMIRROR
        quit
     
    NotifyBecomePrimary() public {
    
        // Start productions after failover
        New $namespace
        set $namespace="HSLIB"
    
        // Comment out the following line if you are using production auto-start
        do ##class(HS.Director).StartAll()
    
        // Reset DeepSee agents in reporting namespace
        set $namespace="MY_PERSONAL_COMMUNITY_REPORTING_NAMESPACE"
        do ##class(%DeepSee.Utils).%Reset(0)
    
    }
    

    Refer to the “ Using the ^ZMIRROR Routine ” section of the “Mirroring” chapter of the   High Availability Guide   for more details on the ^ZMIRROR routine.

  5. Save the routine as   ZMIRROR.mac   .

  6. Compile the routine.

  7. Duplicate this routine on the backup failover member.

  8. Save and compile it.


Note

While HealthShare provides the  HS.Director.StartAll() method to start productions in the correct order, you should use production auto-start instead of calling  HS.Director.StartAll() in your ^ZMIRROR routine.



4.24. Starting Your Productions

Start your Personal Community productions:

  1. On the primary failover member, log in to the Management Portal with administrator privileges.
  2. Click  HealthShare to open the HealthShare Management portal.
  3. Click  Start All .
  4. Click  OK in the confirmation dialog.
  5. Wait for the Done message.
  6. Click  OK .