HealthShare Health Connect Cloud Reference Information
This section describes how to perform various activities that are part of the day-to-day operations of Health Connect Cloud, organized by page. Use the links in the Deployments section of the main menu in the Cloud Services Portal to navigate from page to page.
For a high-level overview of setting up Health Connect Cloud, see Introducing HealthShare Health Connect Cloud.
Some of the functionality described in this section may not be available to all users, depending on their role on the development team. For more information, see Tenants PageOpens in a new tab.
Overview Page
The Overview page contains several sections, which may or may not appear based on your configuration.
Deployment Details
In the Deployment Details section of the Overview page for your deployment, you can view the details of your deployment, including:
-
Deployment size
-
Creation date
-
Deployment ID
-
Cloud provider and region
-
High Availability State
-
Underlying InterSystems IRIS platform
If a deployment has a status where you cannot access the deployment’s Overview page (for example, CREATING or UPDATING), its card on the Deployments page will display the Deployment ID. The Deployment ID uniquely identifies your deployment.
Interoperability Details
The Interoperability Details section of the Overview page displays the File System Interoperability directory name to be used by Interoperability Productions Opens in a new tab that need to store files on the file system. If you have a High Availability configuration, files in this directory are copied automatically from the primary mirror member to the backup mirror member.
This section also displays the CIDR Block for the private network used for this deployment, as well as the Virtual IP Address of the deployment. This CIDR block defines the range of IP addresses used for the internal Health Connect Cloud components. The Virtual IP address is a static address within the CIDR block that you use to communicate with this Health Connect Cloud deployment. If you have a High Availability configuration, this Virtual IP address will continue to work no matter which mirror member is the primary member.
The External IP is displayed only if you have enabled external connections on the Firewall page.
High Availability
If you have a High Availability configuration, the High Availability section of the Overview page displays whether or not your mirror is healthy, shows you the current state of each mirror member, and identifies which mirror member is the primary member and which mirror member is the backup member.
Timezone
The Timezone section of the Overview page displays the current time zone for your deployment and lets you change it according to your preference. The default time zone is UTC.
To change the time zone for this deployment:
-
In the Timezone section of the Overview page, click Change.
-
Under Select New Time Zone, select a location that represents your desired time zone.
-
Click Change Timezone.
-
When asked to confirm the change, type change, and then click Change Time Zone.
You are redirected to the list of deployments while the Health Connect Cloud deployment is updated. This may take a few moments.
-
When the status for your deployment changes from UPDATING back to COMPLETE, click the change is complete.
System Management Page
From the System Management page for your deployment, you can launch the Health Connect Cloud Management Portal, which allows you to create and manage Interoperability Productions Opens in a new tab to connect systems that use different communication protocols and message formats.
Before you can connect to the Management Portal, you need to complete several prerequisite steps:
-
If you are connecting to Health Connect Cloud using a VPN (or Direct Connection), create an InterSystems Network ConnectOpens in a new tab deployment. On the Network Connect Configurations pageOpens in a new tab, attach your Health Connect Cloud deployment and your VPN (or Direct Connection).
-
On the Health Connect Cloud Firewall page, create a firewall rule to allow traffic to flow to the Management Portal.
-
On the Connect Users page, create a username and password you can use to log in to the Management Portal. Then assign to the user any productions you need to access.
Note:You need to assign at least one production to the user in order to access the Management Portal. If no productions exist, create one on the Productions page.
After the prerequisite steps are complete, click Launch Management Portal and log in with the username and password of your connect user.
If you deployed a Message Bank server while deploying Health Connect Cloud, you can also launch its Management Portal using the same username and password.
If you do not see a production you recently created, you might need to add access to that production for your user on the Connect Users page, or you might need to log out of the Management Portal and log back in.
For complete information on using the Management Portal, see the Health Connect documentation setOpens in a new tab. For information on the Message Bank feature, see Message Bank OverviewOpens in a new tab. Note that some Health Connect and Message Bank functionality is not available to Health Connect Cloud users, as these aspects of the service are managed for you by InterSystems.
Connect Users Page
The Connect Users page allows you to manage the users who need to log in to the Health Connect Cloud Management Portal. The Health Connect Cloud Management Portal can be launched from the System Management page.
The Connect Users page shows you a list of all currently defined users and which interoperability productions they are allowed to access.
It also allows you to:
You must create a firewall rule on the Firewall page to open port 443 to allow connect users to access the Health Connect Cloud Management Portal.
Create a User
To create a user :
-
On the Connect Users page for your deployment, click Create User.
-
On the Create User dialog, type a Username and Email, and click Create.
The user now appears in the list of Connect Users. However the user must create a permanent password to be able to log in to the Health Connect Cloud Management Portal, and the user must be granted access to at least one production.
-
Assign at least one production to the user. See Assign Production and Web App Access to a User.
-
Have the user check their email account for a temporary password.
-
Have the user click the Password Management Page link and log in with the username and temporary password.
-
When prompted to change their password, the user should type a permanent password, confirm the password, and click Send.
The user is redirected to the Health Connect Cloud Management Portal.
-
Make sure the user can log in to the Health Connect Cloud Management Portal with their username and permanent password.
If connect users are unable to reach the Management Portal, create a firewall rule on the Firewall page to open port 443 to allow access and make sure they have access to at least one production.
Assign Production and Web App Access to a User
After creating a user, you need to specify which interoperability productions and web applications the user is allowed to access.
You need to assign at least one production to the user in order to access the Management Portal. If no productions exist, create one on the Productions page.
To grant interoperability production and web application access to a user:
-
In Connect Users list, in the row for that user, click Edit Productions in the Actions column.
-
On the Access to Productions dialog:
-
Select the Namespaces (productions) to which the user should have access.
-
Select the Web Apps to which the user should have access.
-
-
Click Apply.
This list of productions and web apps is now displayed in the Productions column in the row for the user.
If you later add a production or web app and want to allow users to access it, return to the Connect Users page and use this same procedure to assign access to the new production or web app.
Reset a User’s Password
If you ever need to reset a user’s password:
-
Click the Password Management Page link.
-
If you see a dialog asking you to sign in with a specific username, click Sign In As a Different User? Otherwise, skip this step.
-
When asked to sign in with a username and password, click Forgot Your Password?
-
Type the user’s username, and click Reset My Password.
A reset code will be sent to the user’s email address.
-
Have the user enter the reset code and select a new password. Then click Change Password.
Delete a User
To remove a user’s Health Connect Cloud Management Portal access, in Connect Users list, click the Delete User icon in the Actions column for that user.
Connect Users and Message Banks
Connect Users can also log in to the Message Bank Management Portal, if you have deployed one. The Message Bank Management Portal can also be launched from the System Management page.
Assign a Connect User permission to use a Message Bank the same way you would assign access to a production.
Productions Page
The Productions page allows you to see all of the interoperability productions you have created and their current Production State (for example, Stopped or Running). In general terms, a production accepts messages from one or more external systems, transforms or processes the messages as required, and then sends them to one or more other external systems.
You can also use the Productions page to:
For general information on productions, see Introduction to Interoperability ProductionsOpens in a new tab. For configuration information specifically relevant to Health Connect Cloud productions, see Configure Health Connect Cloud Productions.
For information on how to grant access for a user to work on a production, see Connect Users page.
Create a Production
When you create an interoperability production, the Cloud Services Portal also creates a namespaceOpens in a new tab for the production, which includes a database for the code and data for that production. After creating a production, you can configure and manageOpens in a new tab it using the Management Portal.
For more information on developing productions, see the Health Connect documentation setOpens in a new tab.
If your Health Connect Cloud deployment was created with the High Availability configuration, the databases for your interoperability productions are automatically mirrored to the backup server.
If your Health Connect Cloud deployment was created with a Message Bank, all of the messages processed by each production, as well as any event log entries, are stored in the Default Message Bank. For details on creating additional Message Banks, see Create a Message Bank.
To create a production:
-
On the Productions page, under Create Interoperability Production, type the desired name of your production.
-
Click Create Production.
After you create a production, it shows up in the Productions list at the top of the page with a Production State of Stopped. When the creation process is finished, the Production State changes to Running. The Production Started column shows the time the production was started, in GMT. You may need to click Refresh to update the status.
To manage the production in the Management Portal, click Manage in the row for that production. You will need to log in as a user that you or a team member has created (and granted production access to) on the Connect Users page.
Delete a Production
To delete an interoperability production:
-
On the Productions page, click the Delete Production icon in the Actions column for that production.
-
In the Delete Production dialog box, type Permanently Delete, and click Delete.
The production is removed from the Productions list at the top of the page.
SSL/TLS Configurations Page
Transport Layer Security (TLS) provides strong protection for communication between pairs of entities. It allows you to perform authentication, data integrity protection, and data encryption. TLS is the successor to the secure sockets layer (SSL).
Health Connect Cloud supports the ability to create and store an SSL/TLS configuration and specify an associated configuration name. When you need an SSL/TLS connection (for example, to connect another system to Health Connect Cloud or to connect Health Connect Cloud to another system), you provide the applicable configuration name, and Health Connect Cloud automatically handles the connection. For information on using SSL/TLS configurations in an production, see Configure a Production to Use SSL.
The SSL/TLS Configurations page allows you to see all of the SSL/TLS Configurations you have created, whether they are enabled or not, and the type of each connection (Client or Server).
You can also use the SSL/TLS Configurations page to:
-
Test an SSL/TLS Configuration (client configurations only)
Create an SSL/TLS Configuration
To create a new SSL/TLS Configuration:
-
On the SSL/TLS Configurations page, under Create SSL/TLS Configuration, type the desired name of your SSL/TLS Configuration.
Only alphanumeric characters are allowed. No spaces or special characters.
-
Type an optional Description.
-
If desired, check Enabled to enable the configuration after creating it.
You can enable or disable it later by editing the configuration.
-
Choose a Type for the configuration.
Client means that this configuration is used when Health Connect Cloud initiates a connection to another system, for example, in an outbound TCP adapter in a production’s business operation.
Server means that this configuration used when another systems initiates a connection to Health Connect Cloud, for example, in an inbound TCP adapter in a production’s business service.
-
Choose the desired Certificate Verification for this configuration.
If this is a Client configuration:
-
None means that the server does not need to provide a certificate and the client performs no verification.
-
Required means that the server must provide a certificate and the client verifies the certificate with the Certificate Authority that issued the certificate.
If this is a Server configuration:
-
None means that the client neither requires or requests a certificate.
-
Request means that the client may or may not provide a certificate and the server verifies the certificate only if provided.
-
Required means that the client must provide a certificate and the server verifies the certificate with the Certificate Authority that issued the certificate.
-
-
Upload the file containing the trusted Certificate Authority certificate(s).
This file contains the X.509 certificate(s) in PEM format of the Certificate Authority (CA) or Certificate Authorities that this configuration trusts. The configuration uses the certificates of the trusted CA(s) to verify peer certificates. Typically, a production system uses certificates from commercial CAs with publicly available certificates.
This field does not appear if certificate verification is not needed for this configuration.
-
Upload the file containing configuration certificate.
This is the configuration’s own X.509 certificate(s) in PEM format, if required.
-
Upload the file containing associated private key.
This is the configuration’s private key file.
If a configuration certificate is provided, a private key is required.
-
Select the Private Key Type.
This is the algorithm used to generate the private key, where valid options are DSA (Digital Signature Algorithm) and RSA (Rivest, Shamir, and Adleman).
-
Type the Private Key Password.
If the private key is password-protected and you do not enter a value here, Health Connect Cloud cannot confirm that the private key and the certificate’s public key match each other.
-
Select the Minimum Protocol Version supported by this configuration.
This is the earliest version of the TLS protocol that this configuration supports.
-
Select the Maximum Protocol Version supported by this configuration.
This is the latest version of the TLS protocol that this configuration supports.
-
If desired, edit the Enabled Cipherlist.
The default set of cipher suites is:
-
ALL — Includes all cipher suites except the eNULL ciphers
-
!aNULL — Excludes ciphers that do not offer authentication
-
!eNULL — Excludes ciphers that do not offer encryption
-
!EXP — Excludes export-approved algorithms (both 40- and 56-bit)
-
!SSLv2 — Excludes SSL v2.0 cipher suites
-
-
For Server configurations only, select the size of Diffie-Hellman key (if using).
-
For Server configurations only, optionally enable and configure OSCP Stapling.
OCSP (Online Certificate Status Protocol) is an internet protocol that checks the validity status of a certificate in real-time.
-
Click Create Configuration.
For more information on the fields on this page, see About ConfigurationsOpens in a new tab.
After you create a configuration, it shows up in the SSL/TLS Configurations list at the top of the page.
Edit an SSL/TLS Configuration
To edit an SSL/TLS Configuration:
-
On the SSL/TLS Configurations page, click the Edit Configuration icon in the Actions column for that SSL/TLS Configuration.
-
In the dialog box, edit any of the fields, and click Submit.
See Create an SSL/TLS Configuration for information on each field.
Delete an SSL/TLS Configuration
To delete an SSL/TLS Configuration:
-
On the SSL/TLS Configurations page, click the Delete Configuration icon in the Actions column for that SSL/TLS Configuration.
-
In the Delete Configuration dialog box, type Permanently Delete, and click Delete.
The configuration is removed from the SSL/TLS Configurations list at the top of the page.
Test an SSL/TLS Configuration
To test an SSL/TLS Configuration (client configurations only):
-
On the SSL/TLS Configurations page, click the Test Connection icon in the Actions column for that SSL/TLS Configuration.
-
In the SSL/TLS Connection Test dialog box, type a Hostname (not its URL) and a Port.
-
Click Test Connection.
The dialog box is updated with information saying whether the connection test succeeded or failed. If the test succeeded, additional details of the connection are provided, such as the protocol and ciphersuite that were used.
SSL Certificate Expiration Alerts
If you want to receive a notification when an SSL certificate is about to expire, you can configure a business service in a production to do this for you. See Configure a Production to Send SSL Certificate Expiration Alerts for more information.
SQL Gateways Page
A SQL Gateway provides access from Health Connect Cloud to external databases via JDBC and ODBC.
Health Connect Cloud maintains a list of SQL Gateway configurations, which are logical names for connections to external databases. Each SQL Gateway configuration consists of a configuration name, information on connecting to the data source, and a username and password to use when establishing the connection.
The SQL Gateways page allows you to see all of the SQL Gateway configurations you have created, the driver used, the server URL, and username used to connect to the external database.
You can also use the SQL Gateways page to:
Create a SQL Gateway Configuration
To create a new SQL Gateway configuration:
-
On the SQL Gateways page, under Create SQL Gateway Configuration, type the Configuration Name of your SQL Gateway configuration.
Only alphanumeric characters are allowed. No spaces or special characters.
-
Choose a Driver to use for the connection.
-
In the Server box, type the URL of the server to use for this connection.
-
In the Port box, type the port number to connect to on the server.
-
In the Database box, type the name of the external database.
-
In the User box, type the username to use to connect to the external database.
-
In the Password box, type the password to use to connect to the external database.
-
Click Create Configuration.
After you create a configuration, it shows up in the SQL Gateway Configurations list at the top of the page.
Create a Snowflake SQL Gateway Configuration
The SQL Gateway configuration to connect to a Snowflake data warehouse is a little bit different.
To connect to a Snowflake Data Warehouse:
-
On the SQL Gateways page, under Create SQL Gateway Configuration, type the Configuration Name of your SQL Gateway configuration.
Only alphanumeric characters are allowed. No spaces or special characters.
-
In the Driver box, select Snowflake.
-
In the URL box, type the URL of the server to use for this connection.
The URL takes the form:
jdbc:snowflake://<account>.snowflakecomputing.com/?warehouse=<warehouse_name>&database=<db_name>
-
In the User box, type the username to use to connect to Snowflake.
-
In the Password box, type the password to use to connect to Snowflake.
-
Click Create Configuration.
After you create a configuration, it shows up in the SQL Gateway Configurations list at the top of the page.
For more information on using a Snowflake SQL gateway, see Configure a Production to Use Snowflake.
Test a SQL Gateway Configuration
To test a SQL Gateway configuration:
On the SQL Gateways page, click the Test Configuration icon in the Actions column for that configuration.
You should see the message “Successfully connected to remote server.”
If you see the message “There was an issue testing configuration. Please double check configuration parameters.” then edit the SQL Gateway configuration and try again.
Edit a SQL Gateway Configuration
To edit a SQL Gateway configuration:
-
On the SQL Gateways page, click the Edit Configuration icon in the Actions column for that configuration.
-
In the dialog box, edit any of the fields, and click Save.
See Create a SQL Gateway Configuration for information on each field.
Delete a SQL Gateway Configuration
To delete a SQL Gateway configuration:
-
On the SQL Gateways page, click the Delete Configuration icon in the Actions column for that configuration.
-
In the Delete Configuration dialog box, type Permanently Delete, and click Delete.
The configuration is removed from the SQL Gateway Configurations list at the top of the page.
Firewall Page
The Firewall page allows you to manage the Health Connect Cloud firewall, allowing traffic from other systems to reach your Health Connect Cloud deployment.
Private rules allow traffic to the deployment over the private network. To connect to Health Connect Cloud over the private network, use InterSystems Network ConnectOpens in a new tab to connect a VPN gateway device (or a Direct Connection) to your deployment.
External rules allow other systems to communicate with your deployment over the internet using a secure connection, for example, a system that uses a Health Connect Cloud SSL/TLS configuration to connect to a production.
The Firewall page lists all of the private rules and external rules you have created. Each rule includes the protocol used to connect to the deployment, the destination port numbers or port ranges to connect to, and the CIDR block that defines the source IP addresses that are allowed to connect. Port 443 provides access for a user to log into the Health Connect Cloud Management Portal, and a port in the range 1025 through 65535 provides access for other connections.
For more information on logging in to the Health Connect Cloud Management Portal, see System Management page.
For information on using firewall rules with productions you have created, see Configuring a Production to Use a Firewall Rule.
Manage Private Firewall Rules
Before creating a private firewall rule, you must create a InterSystems Network ConnectOpens in a new tab deployment to create a VPN hub and then connect a VPN gateway device (or Direct Connection) and your Health Connect Cloud deployment.
To add a private firewall rule to Health Connect Cloud:
-
On the Firewall page, in the Private Rules section, click Create Rule.
-
In the Add Firewall Rule dialog box:
-
In the Type box, select Custom.
-
In the Protocol box, select either TCP or UDP, depending the type of traffic to allow using this rule.
-
In the Port Range box, type the port number(s) or range(s) to use for this rule.
Use port 443 to allow a user to log into the Health Connect Cloud Management Portal or a port in the range 1025 through 65535 for other connections. Use a hyphen to specify a contiguous range of port numbers (for example, 1040-1050). Use commas to separate multiple non-contiguous port numbers (for example, 1040, 1050, 1060). When using commas, do not specify more than 50 port numbers at a time.
-
In the CIDR Block box, type the CIDR block that defines the source IP addresses allowed using this rule.
Public CIDR blocks are not permitted in private firewall rules.
-
In the Description box, type the purpose of this rule.
-
Click Add.
-
You can have a maximum of 240 private firewall rules.
If you have a lot of firewall rules, you can sort them by any column in the table or use the search box to narrow down the list of rules. The search term you enter can match the content of any column in the table.
To delete a private firewall rule, click the Delete Configuration icon in the Actions column for that rule.
Manage External Firewall Rules
Before creating the first external firewall rule, you must enable external connections:
-
On the Firewall page, in the External Rules section, slide the Enable External Connections slider to the right.
You are redirected to the list of deployments while the Health Connect Cloud deployment is updated. This may take a few minutes.
-
When the status for your deployment changes from UPDATING back to COMPLETE, click the card and navigate back to the Firewall page.
To add an external firewall rule to Health Connect Cloud:
-
On the Firewall page, in the External Rules section, click Create Rule.
-
In the Add Firewall Rule dialog box:
-
In the Type box, select Custom.
-
In the Protocol box, select either TCP or UDP, depending the type of traffic to allow using this rule.
-
In the Port Range box, type the port number(s) or range(s) to use for this rule.
Use port 443 to allow a user to log into the Health Connect Cloud Management Portal or a port in the range 1025 through 65535 for other connections. Use a hyphen to specify a contiguous range of port numbers (for example, 1040-1050). Use commas to separate multiple non-contiguous port numbers (for example, 1040, 1050, 1060). When using commas, do not specify more than 50 port numbers at a time.
-
In the CIDR Block box, type the CIDR block that defines the source IP addresses allowed using this rule.
Private CIDR blocks are not permitted in external firewall rules.
-
In the Description box, type the purpose of this rule.
-
Click Add.
-
To quickly add a rule to allow access from your current public IP address to the Management Portal, click Allow Management Portal for My IP. This creates an external firewall rule to open port 443 to your public IP address.
You can have a maximum of 240 external firewall rules.
If you have a lot of firewall rules, you can sort them by any column in the table or use the search box to narrow down the list of rules. The search term you enter can match the content of any column in the table.
To delete an external firewall rule, click the Delete Configuration icon in the Actions column for that rule.
If you are no longer using any external firewall rules, slide the Enable External Connections slider to the left to disable all external connections to the deployment. Any existing external rules are hidden on the Firewall page, but they are not deleted and will be displayed again if you re-enable external connections. Note that the external IP address of the deployment will change when external connections are re-enabled.
DNS Forwarding Page
The DNS Forwarding page lets you set up rules that map one or more domains to one or more DNS servers.
For instance, if you map the domain example.com to a DNS server located at IP address 203.0.113.1, then DNS queries from this deployment for the domain example.com are resolved by the DNS server at that address. This is useful if you are using a split DNS configuration for a VPN connected to this deployment. If the IP address you specify is the IP address of your corporate DNS server, then requests for ftp.example.com, smtp.example.com, and docs.example.com are all forwarded to your corporate DNS server to be resolved. DNS requests for other domains are resolved by the standard domain resolution process.
You can use the DNS Forwarding page to enable the DNS forwarding feature. After that, you can use the page to view any existing mappings, or to add mappings or delete mappings.
Enable the DNS Forwarding Feature
To enable DNS forwarding:
-
On the DNS Forwarding page, move the slider to the right to Enable the feature.
-
Wait 5 minutes to make sure that the feature is fully enabled in the background. You will not see any visual indication that this is complete.
Important:If you don’t wait until the feature is fully enabled, any mappings you attempt to create will fail.
Add a Mapping
To add a mapping:
-
On the DNS Forwarding page, click New.
-
On the Add Mapping dialog, in the DNS Servers box, type the IP addresses of one or more DNS servers.
To add multiple DNS servers, press the Enter key after each IP address.
-
In the Domains box, type one or more domain names.
To add multiple domains, press the Enter key after each domain name.
-
On the Add Mapping dialog, click Save.
Press the Enter key after entering the last domain name to enable the Save button.
-
On the DNS Forwarding page, click New to add additional mappings, if needed.
-
On the DNS Forwarding page, click Save Changes to save all of your new mappings.
Note:If you navigate to another page without saving your new mappings, they will be lost.
-
After saving your changes, wait 5 minutes for the new mappings to be fully processed before making any other changes.
Delete a Mapping
To delete a mapping:
-
On the DNS Forwarding page, in the row for the mapping you want to delete, click the Delete Configuration icon in the Actions column.
-
Delete any other mappings, if needed.
-
Click Save Changes to save all of your deletions.
Note:If you navigate to another page without saving your deletions, they will be lost.
-
After saving your changes, wait 5 minutes for the deletions to be fully processed before making any other changes.
Message Banks Page
The Message Banks page allows you to see all of the Message BanksOpens in a new tab you have created and their current Production State (for example, Stopped or Running). In general terms, a Message Bank is a specialized kind of productionOpens in a new tab that archives messages, event log entries, and search table entries from multiple client productions.
You can also use the Message Banks page to:
The Message Banks link appears in the Deployments section of the main menu in the Cloud Services Portal only if your Health Connect Cloud deployment was created with the Message Bank option
Create a Message Bank
If your Health Connect Cloud deployment was created with the Message Bank option, all messages and other data processed by the connected productions are stored in the default Message Bank. This Message Bank has a namespaceOpens in a new tab of BANK.
To create a new Message Bank:
-
On the Message Banks page, under Create Message Bank, type the desired name of your Message Bank.
-
Click Create Message Bank.
After you create a production, it shows up in the Message Banks list at the top of the page with a Production State of Stopped. When the creation process is finished, the Production State changes to Running. The Production Started column shows the time the production was started, in GMT. You may need to click Refresh to update the status.
To manage the Message Bank in the Management Portal, click Manage in the row for that Message Bank. If you are not already logged in to the Management Portal, you will need to log in with a username and password that you or a team member has created (and assigned message bank access to) on the Connect Users page.
For more details on Message Banks, see Configuring the Enterprise Message BankOpens in a new tab.
Delete a Message Bank
To delete a message bank:
-
On the Message Banks page, click the Delete Message Bank icon in the Actions column for that Message Bank.
-
In the Delete Message Bank dialog box, type Permanently Delete, and click Delete.
The Message Bank is removed from the Message Banks list at the top of the page.
Network Page
The Network page can be used to test connectivity from this deployment to a particular server or to monitor flow logs of the traffic coming in and out of this deployment.
Test Connectivity
The Network Connectivity Test section of the Network page allows you to test connectivity from this deployment to a particular server and port. The server could be an external server or an on-premise server accessed over your company’s VPN.
To perform a connectivity test:
-
In the Network Connectivity Test section of the Network page, in the IP or Hostname box, type the IP address (such as 203.0.113.0) or hostname (such as example.com) of the server to which you want to connect.
-
In the Port box, type the port number to which you want to connect on that server.
You can specify one of the following ports: 21, 22, 53, 443, 465, 587, or a port in the range 1024-65535.
-
Click Test Connection.
You will see either a success or failure message.
Monitor Flow Logs
The VPC Flow Logs section of the Network page allows you to monitor the traffic coming in and out of this deployment. This allows you to confirm that your network configuration is correct, debug network issues, monitor traffic patterns, or identify unauthorized access attempts.
To view flow log entries:
-
In the VPC Flow Logs section of the Network page, optionally filter the log by entering one or more of the following fields:
-
Actions — Choose ACCEPT to see only traffic that was permitted to flow from the source to the destination or REJECT to see only traffic that was blocked from reaching its intended destination.
-
Host IP — Type the IP address of either the source or destination.
-
Host Port — Type the port of either the source or destination.
-
-
Enter the Start Time and End Time of the period of time you want to examine.
The default window is the most recent 10 minutes. The maximum window is 30 minutes in duration.
-
Click Find.
Flow log entries matching the entered criteria are displayed.
-
Optionally, click Load More to load more log entries.
This button only appears if more log entries remain to be loaded.
Files Page
The Files page allows you to transfer files from your desktop to a Health Connect Cloud deployment. For example, you may want to transfer a key file to your deployment so you can use it in an interoperability production.
Transferring a file to your deployment is a two-step process. First, you upload the file from your desktop to an AWS S3 bucket. Then, you sync the file from the bucket to your deployment.
To transfer files to your deployment:
-
On the Files page, click Upload File, and select one or more files to upload.
Files can be of any type, but they must be smaller than 10 MB.
-
Type an optional description to identify the file (or files) you selected.
-
Click Upload.
The list of files on the page is updated with any files you uploaded.
-
Click Sync Files to sync the files to your deployment.
To use a file in an interoperability production, in the row for that file, click the Copy File Location icon in the Actions column. This copies the file path for that file to your clipboard. You can then paste the path where needed when you configure a business host.
If you no longer need a file, delete it by clicking the Delete File icon in the Actions column in the row for that file.
Web Apps Page (Beta)
This feature is in beta and is being made available for customers to test the functionality and suggest further enhancements.
The Web Apps page allows you to add a web application to your Health Connect Cloud deployment and access it through a web gateway. A web application uses a dispatch class to define an endpoint and an accompanying REST API. The dispatch class defines all of the routes in the REST API and associates each with a method in the dispatch class.
To provide security, access to a web application requires:
-
A firewall rule to allow traffic from a source CIDR block to the web application.
-
A Connect User with the proper permissions to access the web application.
-
A bearer token from the built-in Cognito instance to grant the Connect User access to the web application.
-
A rate limit defined in the web application security settings to limit the number of requests that can be sent to the web application in a given period of time.
-
An allow list or deny list defined in the web application security settings to further restrict the traffic that can reach the web application.
-
Optionally, an mTLS (Mutual TLS) configuration to ensure a two-way authentication process before a connection is established.
Web App Prerequisites
Before creating a web application, complete the following prerequisite steps.
-
On the Productions page, create a production and namespace to host the web application.
-
On the Firewall page, create firewall rules for ports 443, 9080, and 9443 to allow IP addresses in a given CIDR block to connect to the web application.
-
On the Connect User page, create a Connect User you can use to connect to the web application, and make sure the user has access to the production and namespace you created.
-
Create a dispatch class to define the routes of the web application API and associate each with a method in the class.
-
If you are using mTLS, make sure you have the required certificates.
Create a Dispatch Class
From the System Management page, log in to the Health Connect Cloud Management Portal.
In the namespace you created to host the web application, create a dispatch class using Microsoft VS Code and GitLab. The dispatch class must extend %CSP.RESTOpens in a new tab.
The following sample class, Sample.RestApp, has three routes that all map to the class method Test().
Class Sample.RestApp Extends %CSP.REST
{
XData UrlMap [ XMLNamespace = "http://www.intersystems.com/urlmap" ]
{
<Routes>
<Route Url="/test" Method="GET" Call="Test" Cors="true"/>
<Route Url="/test/:name" Method="GET" Call="Test" Cors="true"/>
<Route Url="/test/:name/:name2" Method="GET" Call="Test" Cors="true"/>
</Routes>
}
ClassMethod Test(name = "World", name2 = "") As %Status
{
write "Hello ", name_" "_name2, "!<br/>", !
quit 1
}
}
Certificates Needed for mTLS
Before setting up the optional mTLS configuration, make sure you have a Certificate Authority (CA) certificate containing the entire certificate chain and a client certificate signed by the CA.
If you need certificates for testing purposes you can create them with openssl using a procedure like the one below. This example was created on Linux.
First, create a private key (ca.key) for the root CA and a self-signed x.509 certificate (ca.crt) for the CA:
$ openssl genrsa -out ca.key 4096
$ openssl req -x509 -new -key ca.key -sha256 -days 3650 -out ca.crt -subj "/CN=MyTestRoot"
Then, create a private key (client.key) for the client, a certificate signing request (client.csr), and a client certificate (client.crt) that is signed by the root CA:
$ openssl genrsa -out client.key 2048
$ openssl req -new -key client.key -out client.csr -subj "/CN=MyTestClient"
$ openssl x509 -req -in client.csr -CA ca.crt -CAkey ca.key -CAcreateserial \
-out client.crt -days 365 -sha256
Certificate request self-signature ok
subject=CN = MyTestClient
Finally, verify the client certificate to make sure it is properly signed by the CA:
$ openssl verify -CAfile ca.crt client.crt
client.crt: OK
The common names (CN) of the CA certificate and the client certificate must be different or validation will fail.
Upload the CA certificate to Health Connect Cloud on the mTLS Client CAs tab of the Web Apps page:
-
On the mTLS Client CAs tab of the Web Apps page, click Upload CA Cert.
-
In the Upload Client CA Cert for mTLS dialog, in the Hostname Prefix box, type a prefix to distinguish requests that will be handled for the web app with mTLS.
The prefix will be added to the base URL shown on the Web Apps page in the Cloud Services Portal, for example,<hostname_prefix>.api.<deployment_id>.<server_name>.
-
In the Client Certificate Authority Contents textbox, copy and paste the contents of your ca.crt file.
-
Click Save.
Your CA will appear in the list on the mTLS Client CAs tab of the Web Apps page.
After you create the web application, send the client certificate and key along with each request to the web application and Health Connect Cloud will authenticate it against the CA. See Test a Web Application with mTLS for more information.
Create a Web App
After performing the prerequisite steps and creating a dispatch class, you are ready to create your web application, which includes a built-in web gateway to receive requests and direct them to your web app.
-
On the Web Apps page, enable the Web App feature, if it is not already enabled, by moving the Enable slider to the right.
It will take a few seconds for the feature to be enabled.
-
On the Web Apps tab, click Create Web App.
-
On the Create Web App dialog:
-
Type the Web App Name.
This is the path representing the endpoint of your REST API, for example, /hcc/api.
-
Check the Enabled box to enable the web application.
-
Select the Namespace you created to host the web application.
-
Type the name of the Dispatch Class you created, for example, Sample.RestApp.
-
Under Security Settings, type the Rate Limit Count and the Rate Limit Time Window for your web application.
For example, entering 1000 and 10 for these settings, respectively, means that you are limiting the number of API requests allowed through the web gateway to 1,000 in a 10-second window.
-
Select an IP Restrict Mode:
-
None means allow requests from all IP addresses.
-
Allow means allow requests only from the IP addresses and CIDR blocks on the Allow List.
-
Deny means deny requests only from the IP addresses and CIDR blocks on the Deny List.
-
-
If applicable, on the Allow List or Deny List, type single IP addresses or CIDR blocks, one per line.
See the textbox for examples.
-
If you are using mTLS, select the hostname prefix associated with a CA certificate you uploaded earlier.
-
Click Save.
-
The web application now appears in the list at the top of the screen.
Use the icons in the Actions column of the list to edit the settings for a web application or to delete a web application.
Before using the web app, go to the Connect User page and give your Connect User access to the web application.
Test a Web Application
Using a web application can be broken down into two parts, represented by the following HTTP requests.
The first request is sent to the built-in Cognito instance to authenticate the user and obtain a bearer token:
POST / HTTP/2
Host: cognito-idp.<aws_region>.amazonaws.com
x-amz-target: AWSCognitoIdentityProviderService.InitiateAuth
content-type: application/x-amz-json-1.1
Once the bearer token is received, it can be used to make subsequent requests to the web app API:
GET /hcc/api/test/<arg1>/<arg2> HTTP/2
Host: api.<deployment_id>.<server_name>:9443
authorization: Bearer ******
The section below gives an example of how to test your web application from the command line. If you use an API client, such as Postman, you can use it for testing, as well.
Before testing a web application, go to the Connect User page and give your Connect User access to the web app.
Test a Web App from the Command Line
The following example demonstrates how to test a web application from the command line, using curl. It is an annotated version of the one shown on the Help tab of the Web Apps page in the Cloud Services Portal. On the Help tab, select your web app from the dropdown at the top of the page to enable easier copy and paste from the displayed content.
The example uses jq to make the handling of JSON objects easier. If you don’t have jq, you can download it from https://github.com/jqlangOpens in a new tab.
Perform this workflow from a POSIX-compliant shell. The following example was run in Git Bash for Windows, with POSIX mode turned on.
Make sure shell is POSIX compliant:
$ echo "$SHELLOPTS" | grep -o posix
posix
Set a variable to the cognitoClientId shown on the Help tab of the Web Apps page in the Cloud Services Portal.
$ connectClientId=<cognitoClientId>
Set variables to hold the username and password of your Connect User:
$ connectUsername="<username>"
$ connectPassword="<password>"
Set a variable to the web app name you chose when you created your web application:
$ webAppName="/hcc/api"
Use jq to format the body of the request to be sent to Cognito. The arguments in the jq command are passed into the body of the JSON string of the request. The line below is broken for readability.
$ BODY=$(jq -n --arg user "$connectUsername" --arg pwd "$connectPassword" --arg clientId "$connectClientId" \
'{"AuthParameters":{"USERNAME":$user,"PASSWORD":$pwd},"AuthFlow":"USER_PASSWORD_AUTH","ClientId":$clientId}')
Confirm that the JSON string of the body looks good:
$ printf "%s\n" "$BODY"
{
"AuthParameters": {
"USERNAME": "<connectUsername>",
"PASSWORD": "<connectPassword>"
},
"AuthFlow": "USER_PASSWORD_AUTH",
"ClientId": "<connectClientId>"
}
Send the authentication request to Cognito. The <aws_region> in the URL is shown in the example on the Web Apps page in the Cloud Services Portal. The line below is broken for readability.
$ RESPONSE=$(curl -X POST --data "$BODY" -H 'X-Amz-Target: AWSCognitoIdentityProviderService.InitiateAuth' \
-H 'Content-Type: application/x-amz-json-1.1' https://cognito-idp.<aws_region>.amazonaws.com/)
Verify that the response looks good. The following JSON string is formatted for readability.
$ echo $RESPONSE
{
"AuthenticationResult": {
"AccessToken": "******",
"ExpiresIn": 3600,
"IdToken": "******",
"RefreshToken": "******",
"TokenType": "Bearer"
},
"ChallengeParameters": {}
}
Use jq to extract the ID token from the response:
$ ID_TOKEN=$(echo $RESPONSE | jq -r ".AuthenticationResult.IdToken")
Send a request to the web application. This example uses the dispatch class above . The <base_url> is the webAppBaseURL shown on the Web Apps page in the Cloud Services Portal and takes the form https://api.<deployment_id>.<server_name>. The variable $webAppName is the one set near the start of this example.
$ curl -H "Authorization: Bearer $ID_TOKEN" -vv <base_url>:9443${webAppName}/test/world
The verbose option (-vv) allows you to see the entire handshake, which can be useful for debugging your configuration.
The response to the request, minus the handshake, is as follows:
Hello world!
Test a Web Application with mTLS
Sending a request to a web application that uses mTLS is the same as for regular web apps, with the following differences:
-
The hostname prefix is added to the base URL, so requests are sent to <hostname_prefix>.api.<deployment_id>.<server_name>, instead of api.<deployment_id>.<server_name>, where <hostname_prefix> is the prefix you specified when you uploaded the CA certificate associated with this web application.
-
The client certificate (--cert client.crt, in the example below) and client private key (--key client.key) are sent with the request.
-
Since authentication goes both ways in mTLS, the client must have the server’s CA certificate in its certificate store. For testing purposes, this cert can be downloaded and then included with the request (--cacert <server_ca>, in the example below).
If the web application in the example above were created with mTLS, a request to the web app might look something like:
$ curl -H "Authorization: Bearer $ID_TOKEN" -vv --cert client.crt --key client.key --cacert <server_ca> \
https://<hostname_prefix>.api.<deployment_id>.<server_name>:9443${webAppName}/test/world
Again, the verbose option (-vv) allows you to see the entire handshake, which can be useful for debugging your configuration.
Interoperability Metrics Web App
Health Connect Cloud comes with a built-in web application that returns interoperability metrics on a deployment. This web app can also be used for testing purposes and is available from any namespace.
To use the interoperability web app, create a web app, giving it a web app name of your choosing (for example, /hcc/monitor) and using the built-in dispatch class ISCCD.RestMetrics.
The route for this web app is /metrics, so if you created the web app with the web app name /hcc/monitor, you would test the web app by sending requests the URL below. The <base_url> is the webAppBaseURL shown on the Web Apps page in the Cloud Services Portal and takes the form https://api.<deployment_id>.<server_name>.
<base_url>:9443/hcc/monitor/metrics
To filter metrics by namespace, use:
<base_url>:9443/hcc/monitor/metrics/<namespace>
The <namespace> is not case sensitive.
The dispatch class ISCCD.RestMetrics is provided in deployed modeOpens in a new tab, meaning you cannot view its source code.
Web App Logs and Metrics
The Logs and Metrics tab of the Web Apps page lets you view metrics and access logs for a particular web app over a given time period. The Metrics section shows you the number of total requests received by the web app during that time period and gives a breakdown of the total by HTTP status code. The Logs section shows you a list of the requests received by the web app during the time period. For each request, the log shows the:
-
timestamp (in UTC)
-
IP Address of the client making the request
-
HTTP status code (for example, 200 for success or 401 for unauthorized)
-
method (for example, GET or PUT)
-
URI, including any query parameters (for example, /hcc/api/test/hello/world)
An entry is only shown in the access log if the web app received the request. If a valid endpoint is used, but the web app does not accept the connection, no log entry is displayed (for example, if you configure the web app to use mTLS, and the mTLS connection does not succeed).
To request metrics and logs for a web app:
-
On the Web Apps page, click the Logs and Metrics tab.
-
In the Search section of the page:
-
In the WebApp dropdown, select a web application.
-
Specify a Start Time and End Time of the time period for which you want to view metrics and logs (in UTC).
-
Optionally, filter the search by Status Code, Client IP, and/or URI Prefix.
-
Click Search.
-
The search results appear in the Metrics and Web App Logs sections of the page.
CI/CD Pipeline Menu Option
The CI/CD Pipeline menu option provides an easy way for you to log in to GitLab, the Health Connect Cloud source control management tool.
Before using GitLab with this deployment for the first time, contact us using iService to get your deployment linked to your GitLab account. (For more information, see Getting HelpOpens in a new tab.)
To log in to GitLab:
-
In the Deployments section of the main menu in the Cloud Services Portal, click CI/CD Pipeline.
-
On the Health Connect Cloud Source Control Management screen, log in with your Cloud Services Portal username and password.
This takes you to your Projects page in GitLab.
See the following resources for information on recommended source control best practices.
Managing Interfaces with GitLab for InterSystems Cloud ServicesOpens in a new tab (documentation)
Building Health Connect Cloud Interfaces with Source ControlOpens in a new tab (online learning)
Documentation
If you have any questions on how to use Health Connect Cloud, on the main menu, click Documentation.
For documentation on all of the InterSystems cloud services, click your name at the top right of the Cloud Services Portal, and then click Documentation.
If you would like to submit any feedback to help InterSystems improve any of the InterSystems cloud services, click your name at the top right of the Cloud Services Portal, and then click Submit Feedback. While we cannot respond to all feedback we receive, we welcome your opinion and will take it into consideration when determining future directions and enhancements.
Common Cloud Services Portal Functionality
For information on common Cloud Services Portal functionality that is not specific to HealthShare Health Connect Cloud, see Cloud Services Portal Reference InformationOpens in a new tab. This document includes material describing the following features in the Cloud Services Portal: