Creating a Healthcare Interoperability (Foundation) Namespace and Production Using the Installer Wizard
The Installer Wizard allows you to create a Foundation namespace and production that contains all of the mappings and libraries needed for health care interoperability. If you need to modify a Foundation namespace, for example to modify the routine database, you can use the Namespaces page (System Administration > Configuration > System Configuration > Namespaces) after you have created and activated your Foundation namespace in the Installer Wizard.
In order to create a secure and portable configuration for your InterSystems IRIS for Health Foundation namespace and production, use the Installer Wizard to:
Once you have done so, import the SDA3 schema if you are using SDA3 or SDA3 transformations.
When you select the Start All button on pages accessed through the Health menu, only Foundation productions are started. If you open a different production in a Foundation namespace, that production will not be started.
The business host Ens.Activity.Operation.Local that is automatically added to a Foundation production is used for activity monitoring, and can be removed if you do not need this functionality.
Accessing the Installer Wizard
-
Log in to the Management Portal for your instance as a user with the %HS_Administrator role.
-
Click Health in the menu on the left.
-
Click the Installer Wizard link in the banner at the top of the page.
Setting the Network Host Name the Installer Wizard
InterSystems IRIS for Health uses the Network_Host_Name during configuration to generate URLs that address the various system components on a particular instance. The Network_Host_Name defaults to the machine’s host name if you do not explicitly set it in the Network Host Name page in the Installer Wizard.
Always set the Network_Host_Name before you begin configuring InterSystems IRIS for Health.
Because the URLs based on the Network_Host_Name become embedded in your productions, InterSystems strongly recommends that you use a hostname that is resolved by your DNS as the value for Network_Host_Name rather than a machine IP address or a fully-qualified domain name that might be longer than the maximum of 50 characters. Using a DNS hostname provides the flexibility to redirect resources at the network level, making it much easier to later clone a system for testing, move a system to a new server, or restore a backup on another machine.
In a mirrored InterSystems IRIS for Health installation, the Network_Host_Name should be set to the mirror VIP (or DNS entry for the mirror VIP).
To set the Network_Host_Name:
-
Follow the instructions to access the Installer Wizard.
-
Click Configure Network Host Name.
-
In the Network Host Name field, replace the machine’s host name with a host name resolved by your DNS that refers to the machine. For a mirrored system, use the DNS entry of the mirror VIP. The maximum length for this string is 50 characters.
-
Click Save.
Setting Up Secure Communication for a Foundation Production
Live InterSystems IRIS for Health systems should always use secure communication.
If you set up secure communication before you create a Foundation namespace and production, then your Foundation production will automatically use the secure communication settings when you activate it.
Follow the instructions below to securely configure your Foundation namespace and production:
-
If you have not already done so, set the Network Host Name.
-
Configure your web server(s) to enable SSL/TLS. See the documentation for the web server you are using. Make a note of each SSL/TLS hostname and port.
-
Create an InterSystems IRIS SSL/TLS Configuration for your InterSystems IRIS for Health instance:
Follow the instructions in “Create or Edit a TLS Configuration” in the TLS Guide to create an SSL/TLS Configuration. Note the Configuration Name.
When you create or edit endpoints in the service registry, you can specify which SSL/TLS configuration to use. You can also specify the SSL/TLS Configuration directly in each production web client in the SSLConfig property.
-
Configure secure communication in the Installer Wizard:
-
Follow the instructions to access the Installer Wizard.
-
Click Configure Secure Communication.
-
The Server HostName field displays the value you entered in the Configure Network Host Name dialog. This is typically a “short name” that is resolved by your DNS rather than a fully-qualified domain name.
-
In the Secure Port field, enter the SSL port number for your secure web server.
-
Optionally enter a Web Server Prefix. If you are configuring a single web server to serve multiple HealthShare instances, enter the instance name to which you want to connect in the Web Server Prefix field, just as you would enter it in the CSP Server Instance field if you were defining a remote server connection.
-
Confirm that the value in the Secure Root Endpoint field is correct.
-
Select the These Settings are Active checkbox.
Important:If you do not select These Settings are Active, then your secure communication settings will not be used when you create your Foundation namespace and production in the Installer Wizard.
-
Select an SSL/TLS Configuration from the dropdown. Selecting an SSL/TLS Configuration allows the Installer Wizard to correctly construct your service registry entries to use secure communication. Do not use the default value of HS.Secure.Demo in a production system.
-
Click Save.
-
Creating a Foundation Namespace and Production in the Installer Wizard
Before you create a Foundation namespace and production for a live system, set up secure communication, so that your Foundation production automatically uses secure communication settings. Failure to do so may result in security vulnerabilities.
To install and activate a Foundation production using the Installer Wizard:
-
Follow the instructions to access the Installer Wizard.
-
Click Configure Foundation.
-
For Local Name, enter the name that will identify the Foundation production. This name will become the namespace that contains the class definitions for the production. The maximum length for this string is 50 characters. The local name is referred to below as <LOCAL_NAME>.
-
The Network Name is the network-wide, unique name for the Foundation production. It defaults to Network_Host_Name:<LOCAL_NAME>.
Note:Network_Host_Name defaults to the machine’s host name if you do not explicitly set it in the Configure Network Host Name option in the Installer Wizard. Network_Host_Name should always be set in the Installer Wizard before you begin configuring your instance.
A DNS entry is a better choice of Network_Host_Name, as it provides more flexibility. In a mirror, it is important that Network_Host_Name be set to the VIP (or DNS entry) of your mirror before you use the Installer Wizard to configure your productions.
-
For Description, enter an optional short description.
-
If the system is a mirror member and you want to mirror the database, select Mirror Database. For additional information about mirroring with InterSystems IRIS for Health, see the considerations for health care products described in Managing Mirroring.
Note:On versions prior to 2022.1, in order to mirror a foundation namespace, request an ad hoc patch for HSHC-3009 from the WRC, and follow the ad hoc instructions provided.
-
For Production, enter the package and class name that you will use for this production in the form Package.Class. The default is <LOCAL_NAME>PKG.FoundationProduction. For example, “HSFOUNDATIONPKG.FoundationProduction”. Adding PKG to <LOCAL_NAME> makes it easy to differentiate between namespace and code package names, and prevents naming collisions.
-
For Template, choose Generic Production.
-
The default location for the production database, IRIS.DAT, is installDir/mgr/localName. To specify a location for the database other than the default, enter the alternate location in the Alternate Database Location field. If you specify an absolute location, then that location will be created if it does not exist. Your database will be in alternateDatabaseLocation/localName. If you specify a relative location then the database will be created in installDir/mgr/hslib/alternateDatabaseLocation/localName.
-
Click Save. This production is now displayed in the list of configurations.
-
In the row for the production you just created, click Activate. A window pops up, asking if you want to proceed. It is at this step that your Foundation production is created.
-
Click Start to start the activation process.
Note:If you close the dialog box before it displays a message that indicates completion, you will not see any error messages that may occur in the creation of your production.
The result of the activation process is a new namespace that contains a Foundation production and other related classes. If you used the default values, the namespace for this production will be <LOCAL_NAME>, and the production name will be <LOCAL_NAME>PKG.FoundationProduction. So, for example, if you enter HSFOUNDATION in the Local Name field, you will create an HSFOUNDATION namespace that contains a FoundationProduction in the HSFOUNDATIONPKG package.
Import the SDA3 Schema
If you are using SDA3 or SDA3 transformations, you must import the SDA3 schema. To do so:
-
Open the Management Portal.
-
Navigate to Health > myFoundationNamespace > Schema Documentation, where myFoundationNamespace is the name of your Foundation namespace.
-
Click the Import SDA3 Schema button.