Deploy the Client Application to Test Synchronous Healthcare Action Engine Services within Unified Care Record

Prepare Your Demo Environment

To deploy and use the HAE client application, you must configure a your environment as follows:

1. Set up a demo UCR instance and a demo HAE instance as described in Deploy a Demo Environment. Alternatively, you can use any HealthShare federation and HAE instance which meet the following criteria:

   • All instances must be configured to use TLS.

   • All necessary productions for the instances must be installed and running.

   • A UCR instance must feature an Operational Data Store (ODS) namespace with an operational FHIR endpoint.

   • A UCR instance must feature an operational OAuth 2.0 server.

   • The HAE instance should feature at least one active rule which is associated with the patient-view trigger.

   • The UCR federation should feature demo patient data which can be used to evaluate HAE rules.

2. Configure the UCR and HAE instances to use an external web server to communicate with TLS over the standard HTTPS port, 443. All endpoints—including the endpoints for the FHIR server and the OAuth 2.0 server—must be available at URLs which adhere to the following format:

   https://<domainURL>/<instancePrefix>/<appPath>
   

   See Accessing CSP on Multiple InterSystems Servers for more information.

   Note:

   If you deployed the demo environment as recommended in the preceding step, you can use the self-signed certificates which the TLS demo utility generates to configure TLS on your web server.

3. Fulfil the security requirements to enable the UCR Navigation Application. (If TLS is configured correctly, then you only need to enable Federated SSO.)

4. On the machine where you would like to deploy the HAE client application, install Docker (https://docs.docker.com/get-docker/Opens in a new tab) and Docker Compose (https://docs.docker.com/compose/install/Opens in a new tab).

5. Create a directory for files which will be associated with the HAE client application (for example: /users/testuser/haeclientapp/).

6. Generate or acquire a private TLS key file and a TLS certificate file which can be used by the HAE client application. Place these files together in a directory (for example: /users/testuser/haeclientapp/demo-tls-certs/).

Load the HAE Client App Container Image

InterSystems distributes the HAE client application as a container image. To use it, perform the following steps:

1. Download the HAE client application container image tarball which is included as part of the InterSystems Healthcare Action Engine Demo Walkthrough repository: https://github.com/intersystems/Healthcare-Action-Engine-Demo-WalkthroughOpens in a new tab. If you downloaded or cloned the repository to follow along with the demo walkthrough exercises, you should already have the container image.

2. From the command line, issue the following command to load the container image (replace [haeClientAppImage] with the name of the file that you downloaded from the repository):

   docker image load < [haeClientAppImage].tar.gz
   

   

Once Docker has loaded the image, you can find the name and tag for the image by examining the output of the docker image ls command.

Create the Environment File and the Docker Compose File

To run the HAE client application, you must define a set of environment variables and provide them to the application container at startup. For ease of organization, InterSystems recommends that you do so by creating two files within your HAE client application directory:

• An environment file (such as clientapp.env) which defines the necessary environment variables, one variable definition per line.

• A Docker Compose file (docker-compose.yml), which configures the container and provides the location of the environment file.

The following sections provide annotated examples of what each file might contain.

# The external port at which the application's internal container port will be exposed.
PORT_REDIRECT=443

# The location of the TLS files within the container's filesystem.
SSL_CERT_PATH=/tls-certs
# The filename of the private key.
SSL_KEY_FILENAME=demoTLSkey.pem
# The filename of the TLS certificate. 
SSL_CERT_FILENAME=demoTLScert.pem

# The hostname for your HAE instance
BASE_SERVER_HAE=https://haehost.hsdomain.com
# The hostname for the UCR instance which hosts the Navigation Application you will use
BASE_SERVER_UCR=https://ucrhost.iscinternal.com
# The hostname for the UCR instance which hosts your OAuth server
BASE_SERVER_OAUTH=https://ucrhost.hsdomain.com
# The hostname for the UCR instance which hosts your FHIR server
BASE_SERVER_FHIR=https://ucrhost.hsdomain.com

# The instance name for the HAE instance, to be used as the instance prefix when constructing URLs
INSTANCE_HAE=demoHAE
# The instance name for the Navigation Application UCR instance, to be used as the instance prefix when constructing URLs
INSTANCE_UCR=demoUCR
# The instance name for the OAuth server UCR instance, to be used as the instance prefix when constructing URLs
INSTANCE_OAUTH=demoUCR
# The instance name for the FHIR server UCR instance, to be used as the instance prefix when constructing URLs
INSTANCE_FHIR=demoUCR

# The namespace name for your HAE instance's HAE namespace, to be used when constructing URLs for CDS Hooks requests.
NAMESPACE_HAE=qdsmokesa
# The namespace name for your FHIR server UCR instance's ODS namespace, to be used when constructing URLs for FHIR requests.
NAMESPACE_FHIR=hsods

# The FHIR version used by the FHIR server, to be used when constructing URLs for FHIR requests
FHIR_VERSION=r4

version: '3'
services:
  cds-client:

    # The repository name and tag for the HAE client application image on your system may be different from the one below.
    # Check the image information using the output from the following command: docker image ls
    image: cds_client:1.0

    # The HAE client application communicates using the internal container port 8082.
    # The external port mapped onto this port must match the value of the PORT_REDIRECT environment variable.
    ports:
      - "443:8082"

    # The volume's location within the container must match the value of the SSL_CERT_PATH environment variable.
    volumes:
      - /home/testuser/haeclientapp/demo-tls-certs:/tls-certs

    # The path to the environment file you have created.
    env_file:
      - clientapp.env

Configure HAE Allow Lists

If you have not already done so, configure the Healthcare Action Engine Allow Lists for your demo environment:

• Add the OAuth 2.0 server’s JWKS endpoint to the jku URIs list

• Add the OAuth 2.0 server’s issuer endpoint to the iss URIs list

• If necessary, add the host domain for the HAE client application to the Cross-Origin Allow List.

Start the HAE Client Application Container

Within the directory which contains the environment and Docker Compose files, issue the following command to start the HAE client application:

docker compose up

During startup, the client application uses the TLS files that you provided to register confidential and public client configurations with the OAuth 2.0 server. The confidential client is used to authorize the CDS Hooks interaction between the client application and HAE; the public client is used to authorize the interaction between the UCR Navigation Application and the client application.

The application outputs information about its progress, for troubleshooting purposes. If startup is successful, the application outputs the base URL where the application is available, as in the following example:

CDS Client running in Production Mode at https://haeclienthost.hsdomain.com.

The UCR navigation will invoke the HAE client application at this domain’s /hae-client path. Using the example above, the URL for the application’s endpoint would be the following:

https://haeclienthost.hsdomain.com/hae-client

Embed the Client within the UCR Navigation Application

1. Navigate to the management page for your HealthShare Registry namespace by selecting the Management Portal’s HealthShare tab and then selecting the name of your Registry namespace.

2. From the Registry namespace Management page, select Security Management > Configure Navigation Application.

3. Within the Navigation Application Configuration Utility, select the Applications tab and add an external application with the following specifications:

   • For Product and Item, provide unique product and item codes (for example: haeCDSclient)

   • For Caption, provide the text for the caption which will represent the application in the Navigation Application’s application menu.

   • For Icon, you can specify ExtendedDecisionSupport.svg or any other HTML-compatible image you place within the installation directory’s/csp/healthshare/hssys/hsnavigation/ui/assets/images directory.

   • For Default URL, provide a URL with the following form, replacing <HAEclientBaseURL> with the URL supplied by the HAE client application output:

     <HAEclientBaseURL>/hae-client
     

4. Add an Application Context for the HAE client application with the following specifications:

   • For Product, provide the same product code that you specified for the application in the preceding step.

   • For ContextID, provide a unique identifier for this application context.

   • For URL Pattern, specify /csp/healthshare/$namespace$/app/hae-client

5. Open a Terminal session for the UCR instance and switch to the HSSYS namespace.

6. Configure the HAE client application to be patient context-aware by issuing the commands which follow. (Replace <productCode>, <itemCode> and <contextID> with the values you provided for the Application Product code, Application Item code, and Application Context ContextID.)

    set inst = ##class(HS.UI.Navigation.Service.API).GetInstance()
    do inst.SetAppPatientAware("<productCode>", "<itemCode>", 1)
    do inst.AddPatientContextMatchingPattern("<productCode>", "<contextID>", "*")

   

Invoke HAE Services Using the Client Application

Once the Healthcare Action Engine client application is operational and you have embedded it within the Unified Care Record Navigation Application, you can invoke synchronous HAE notification services from a Navigation Application session in one of the following ways: