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 asYes/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:
-
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.
-
Test environment — This environment should be mirrored.
-
User acceptance test (UAT) environment — Selected users access this environment and test your changes. This environment should be mirrored.
-
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
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:
-
Copy the < install-dir > / csp / and < install-dir > / hscommunity-content / folders (and their subfolders) from instance A to the shared drive.
-
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 .
-
On both instance A and instance B, delete the < install-dir > / csp / and < install-dir > / hscommunity-content / folders (and their subfolders).
-
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
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.
-
Configure instance A as the first failover member as described in “ Create a Mirror and Configure the First Failover Member .”
-
Configure instance B as the second failover member as described in “ Configure the Second Failover Member .”
-
On instance A, perform the steps in “ Authorize the Second Failover Member .”
-
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.
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.
-
On the primary failover member, log in to the Management Portal with administrator privileges.
-
Select HealthShare to open the HealthShare Management portal.
-
Select the HealthShare > Installer Wizard link in the banner.
-
Select Configure Network Host Name .
-
Enter the VIP or DNS name in the Network Host Name field.
-
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:
- On the primary failover member, log in to the Management Portal with administrator privileges.
- Select System Administration > Configuration > System Configuration > Local Databases .
- In the row of the table for HSSYS , click Add to Mirror <your_Mirror_name>.
- 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.
-
Stop the InterSystems IRIS for Health instances in your mirror:
-
Stop instance B, the backup failover member first, to prevent mirror failover.
-
Stop instance A, the primary failover member.
-
-
Copy the HSSYS database from instance A to instance B:
-
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.
-
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 .
-
-
Restart the InterSystems IRIS for Health instances in your mirror:
-
Start instance A so it comes up as the primary failover member.
-
Next start instance B. It will start as the backup.
-
3.11. Activating and Catching up the HSSYS Databases on the Backup Failover Member
-
Log in to the Management Portal on instance B, the backup failover member, with administrator privileges.
-
Select System Operation > Mirror Monitor .
-
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
Follow the procedure below to refresh the mirror agent on your mirror members by stopping the agent and restarting it:
- Log into the Management Portal on the primary failover member with administrator privileges.
- Select HealthShare to open the HealthShare Management Portal.
- Select the Mirror Agent Monitor link in the banner.
- The agent auto-starts every five minutes, so it may already be running.
- If the agent is running, select Stop Agent , and wait for the Start Agent button to become active.
- Select Start Agent .
- 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:
-
Stop instance A, the primary failover member, to induce failover to the backup.
-
Confirm that instance B is now the primary in the Mirror Monitor ( Home > System Operation > Mirror Monitor ).
-
Restart instance A. It will come up as the backup failover member.
-
On the new primary, Instance B, open the HealthShare Management Portal.
-
Click the Installer Wizard link in the banner.
-
Reactivate the reporting production:
-
Click Activate .
-
In the Activate Configuration dialog, click Start .
-
Wait for activation to complete.
-
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:
-
On the primary member, open Studio.
-
Change to the %SYS namespace.
-
Create a new ObjectScript Routine .
-
Enter the following code, replacing
Configuration Manager
with the REPORTS namespace you created in the Installer WizardZMIRROR 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.
-
Save the routine as ZMIRROR.mac .
-
Compile the routine.
-
Duplicate this routine on the backup failover member.
-
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 :
- Specifying Initial Values for System Default Settings
- Setting Up the Personal Community Web Applications and Starting Personal Community
- Setting Up and Specifying an Authentication Domain
- Creating a Workbench Administrator
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
Note
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.
- the associated reporting database
-
HSAUDIT
(if it exists)
You will not mirror:
-
HSCUSTOM
-
HSLIB
-
HSPILIB
-
MPRLLIB
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:
-
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>
- On instance B, log into the Management Portal with administrator privileges.
- Navigate to Home > System Administration > Configuration > System Configuration > Local Databases .
- Click Create New Database .
-
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.
- Click Next .
- On the details page, accept the defaults.
- Click Next .
- On the resources page, select Create a new resource .
- In the Create a New Resource Name dialog click Save to accept the default values (Do not provide public RW permissions with this resource).
- Click Finish .
- Click Create New Database again.
-
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.
- Click Next .
- On the details page, accept the defaults.
- Click Next .
- On the resources page, select Create a new resource .
- In the Create a New Resource Name dialog click Save to accept the default values (Do not provide public RW permissions with this resource).
- 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
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.
-
Configure instance A as the first failover member as described in “ Create a Mirror and Configure the First Failover Member .”
-
Configure instance B as the second failover member as described in “ Configure the Second Failover Member .”
-
On instance A, perform the steps in “ Authorize the Second Failover Member .”
-
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.
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:
-
On the primary failover member, log in to the Management Portal with administrator privileges.
-
Select HealthShare to open the HealthShare Management portal.
-
Select Stop All .
-
Select OK in the confirmation dialog.
-
Wait for the Done message.
-
Select OK .
4.11. Copying the Content Manager to the Shared Drive
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:
-
Copy the < install-dir > / csp / and < install-dir > / hscommunity-content / folders (and their subfolders) from instance A to the shared drive.
-
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 .
-
On both instance A and instance B, delete the < install-dir > / csp / and < install-dir > / hscommunity-content / folders (and their subfolders).
-
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.
-
On the primary failover member, log in to the Management Portal with administrator privileges.
-
Select HealthShare to open the HealthShare Management portal.
-
Select the HealthShare > Installer Wizard link in the banner.
-
Select Configure Network Host Name .
-
Enter the VIP or DNS name in the Network Host Name field.
-
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
-
Log in to the Management Portal on your Unified Care Record with administrator privileges.
-
Navigate to HealthShare > Registry_name > Registry Management > Service Registry
-
In the Service Type field at the top of the page, select SOAP.
-
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).
-
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.
-
-
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:
-
Select the entry in the table.
-
Update the value in the Host field to the network host name value for the Personal Community mirror.
-
Tab out of the field.
-
Click Save .
-
-
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:
- On instance A, the primary failover member, log in to the Management Portal with administrator privileges.
- Select System Administration > Configuration > System Configuration > Local Databases .
- Click Add to Mirror .
-
Select the following databases from the list:
-
HSSYS
- your Personal Community database
- your Personal Community reporting database
-
HSAUDIT
(if it exists)
-
- Click Add .
-
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.
-
Stop the InterSystems IRIS for Health instances in your mirror:
-
Stop instance B, the backup failover member, first, to prevent mirror failover.
-
Stop instance A.
-
-
Copy the HSSYS database and both your Personal Community database and your Personal Community reporting database from the primary to the backup:
-
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.
-
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 .
-
-
Restart the InterSystems IRIS for Health instances in your mirror:
-
Start instance A, so it comes up as the primary failover member.
-
Next start instance B.
-
4.16. Activating and Catching up the Databases on the Backup Failover Member
-
Log in to the Management Portal on instance B, the backup failover member, with administrator privileges.
-
Select System Operation > Mirror Monitor .
-
In the Select an action dropdown, select Catchup , then select Go . A list of databases will appear.
-
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
Follow the procedure below to refresh the mirror agent on your mirror members by stopping the agent and restarting it:
- Log into the Management Portal on the primary failover member with administrator privileges.
- Select HealthShare to open the HealthShare Management Portal.
- Select the Mirror Agent Monitor link in the banner.
- The agent auto-starts every five minutes, so it may already be running.
- If the agent is running, select Stop Agent , and wait for the Start Agent button to become active.
- Select Start Agent .
- 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.
- Log into the Management Portal on the primary failover member with administrator privileges.
- Click HealthShare to open the HealthShare Management Portal.
- Click the Installer Wizard link in the banner.
- Locate your Personal Community production in the table.
- Click Activate .
- In the Activate Configuration dialog, click Start .
- Wait for activation to complete. When you see the Activation Done message, click Close .
- Locate your Personal Community reporting production in the table.
- Click Activate .
- In the Activate Configuration dialog, click Start .
- 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:
-
Log in to the Management Portal on your primary failover member.
-
Change to your Personal Community namespace.
-
Go to Home > Interoperability > Configure > System Default Settings .
-
Examine the table and locate any rows where the Setting Value references the local instance name.
-
For each row you locate:
-
Click on the row in the table.
-
Click Edit .
-
In the Setting Value field, select the local instance name and replace it with the network host name.
-
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
To update the Workbench Personal Community base URL to refer to the network host name:
-
On your primary failover member, log into the Workbench with administrator privileges.
-
Click Setup .
-
Click Site Configuration .
-
Edit the value in the Personal Community base URL field, replacing the local instance name with the network host name.
-
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.
-
On your primary failover member, log into the Management Portal with administrator privileges.
-
Navigate to System Operation > Task Manager > Task Schedule .
-
Locate the following tasks:
-
Cube Manager Build - <reporting_namespace>
-
Cube Manager Synch - <reporting_namespace>
-
-
For each task:
-
Click the name to view the task details.
-
Click Export .
-
Provide the path and file name for the export.
-
Click Perform Action Now .
-
-
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:
-
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 .
-
-
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 ).
-
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.
-
-
Import the tasks:
-
Now that it is the primary, log into the Management Portal on instance B with administrator privileges.
-
Navigate to System Operation > Task Manager > Import Tasks .
-
Browse for and import the tasks that you exported in an earlier step.
-
-
Create the Web applications:
-
On instance B, open the terminal and run the following code, replacing
PERSONAL_COMMUNITY_namespace
with the name of your Personal Community namespace, andPUBLIC_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)
-
Verify that the return status is success. This creates /public and /public/report , where “public” is the public Web application name.
-
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)
-
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:
-
On the primary member, open Studio.
-
Change to the %SYS namespace.
-
Create a new ObjectScript Routine .
-
Enter the following code, replacing
Configuration Manager
with the REPORTS namespace you created in the Installer WizardZMIRROR 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.
-
Save the routine as ZMIRROR.mac .
-
Compile the routine.
-
Duplicate this routine on the backup failover member.
-
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:
- On the primary failover member, log in to the Management Portal with administrator privileges.
- Click HealthShare to open the HealthShare Management portal.
- Click Start All .
- Click OK in the confirmation dialog.
-
Wait for the
Done
message. - Click OK .