QueryResponse Interface Design and Development Guide Based on REST API in HealthConnect

Background:

This guideline provides an overview of how to design and implement a REST API interface for querying patient demographic data from an Electronic Patient Record (EPR) system using HealthConnect. The process involves sending a query request with the patient’s identification number, retrieving the response from the EPR system, extracting the required patient demographic data from the HL7 message, and sending it as a JSON response to the supplier. The high-level process diagram is shown below (Screenshot 1).

🚨 Note: You can modify or add code and other features according to your requirements. This is just a basic guideline I’ve created for quick solutions.

Screenshot 1: A High-Level Message Process Diagram.

High LevelDiagram

🛠️ Usage Instructions

The step-by-step guideline is provided below:

Setup HealthConnect Management Portal (MP) – Production Configuration (PC).
Custom Code
Using Postman

🚀 Step 1: Set Up Web Application

🏥 Step 2: Set Up the REST Service in HealthConnect Management Portal

Navigate to Web Application Setup
Go to: System Administration → Security → Application → Web Application.
Create a New Web Application
- Click “Create New Web Application”
- Enter the Name of the application
- Optionally, provide a Description
- For Namespace, select the appropriate namespace
Enable REST

Click on REST to enable the service
Enter the Dispatch Class
Select “Unauthenticated” (password setup will be explained later)

Save Your Configuration
- Click “Save”
- Refer to Screenshot 2 for an example

📸 Screenshot 2: Web Application and Setting Up REST

Web Application

🛠️ Step 2: Create Required Classes

A. Create Class – `GetRequestDatasets`

Open Cache Studio

Select the appropriate namespace (the one you set up previously).

Create a New Class

Go to File → New → General → Class Definition → OK.

Enter Class Details

Package Name: (your chosen package)
Class Name: GetRequestDatasets

📸 Screenshot 3: Code for GetRequestDatasets

Web Application

B. Create Response Datasets Class – `SetResponseDatasets`

⚠️ Note: You can add or remove properties according to your requirements.

Create a New Class

Class Name: SetResponseDatasets

Add the Code

Write the required code for the class
Compile the class

📸 Screenshot 4: Code for SetResponseDatasets

Web Application

C. Create Business Process – `QueryRequestResponse`

Create a New Business Process

Name: QueryRequestResponse

Add the Code

Write the required code for the business process
Compile it

📸 Screenshot 5: Code for Business Process – QueryRequestResponse

Web Application

⚠️ Note: "404 Not Found" is just a display message; you can configure this differently if needed.

D. Create Business Service – `GetRequest`

Create a New Business Service

Name: GetRequest

Add the Code

Write the required code for the business service
Compile it

📸 Screenshot 6: Code for Business Service – GetRequest

Web Application

E. Create REST Handler – `RestHandler`

Create a New REST Handler

Name: RestHandler

Add the Code

Write the required code for the REST handler
Compile it

📸 Screenshot 7: Code for RestHandler

Web Application

✅ Final Layout in Studio

Once all classes, business processes, services, and REST handlers are created and compiled, your Studio should display the following layout:

📸 Screenshot 8: Studio Layout of RESTful API

REST API

⚙️ Step 3: Set Up Management Portal – Production Configuration

Give the names (services, processes, operations) according to your requirements.

🛠️ Configure Services
- Select the appropriate class: ...RESTfulAPI.SERVICES.GetRequest
🔄 Configure Processes
- Select the appropriate class: ...RESTfulAPI.PROCESS.QueryRequestResponse
⚡ Configure Operations
- Select: EnsLib.HL7.Operation.TCPOperation (for EPR System)

⚠️ Note:

Go to the service’s settings and select the process name from the dropdown list you defined.

📸 Screenshot 9: Management Portal – Production Configuration view

REST API

Finally, we have set up everything. Now, let’s test or evaluate the interface.

🧪 Step 4: Testing and Evaluation

If you don’t already have it, download and install Postman to test the REST interface.

Test Case 1: Request with a Valid Patient MRN

Send a GET Request

URL: https://......restapi/Patient?MRN=510800
Method: GET

Verify the Response

Check that the returned data matches the patient record for MRN 510800.

📸 Screenshot 10: Output of Test Case 1

REST API

Test Case 2: Request with a Valid Patient MRN (Alternative URL)

Send a GET Request

URL: https://......restapi/510800
Method: GET

Verify the Response

Ensure the returned data matches the patient record for MRN 510800.

📸 Screenshot 11: Output of Test Case 2

REST API

Test Case 3: Request with an Invalid Patient MRN

Send a GET Request

URL: https://......restapi/Patient?MRN=INVALID_MRN
Method: GET

Verify the Response

The system should return an error message or indicate that no record was found.

📸 Screenshot 12: Output of Test Case 3

REST API

Test Case 4: Management Portal Services Disabled

Scenario

If the services in the Management Portal are disabled, requests to the REST API will not succeed.

Send a Request

Try sending a GET request to your REST endpoint.

Expected Output

The system will display a message indicating that the services are disabled.

📸 Screenshot 13(a): Disabled Services – Output of Test Case 4

REST API

📸 Screenshot 13(b): Disabled Services – Additional Output of Test Case 4

REST API

Visual Trace of Messages

To better understand the flow of requests and responses, you can view the message visual trace in the Studio.

📸 Screenshot 14: Visual Trace

REST API

📸 Screenshot 15: Source Message

REST API

📸 Screenshot 16: Process Message – Generate Message

REST API

📸 Screenshot 17: Response from the EPR System – ADR^A19

REST API

🔒 Password Setup for REST API

This section provides a basic method to set up a username and password for accessing the REST API configured in HealthConnect.

For testing and demonstration purposes, Postman is used.

1. Initial Unauthorized Access

Send a Request Without Credentials

Attempt to access the REST endpoint using Postman without a username or password.

Expected Result

The system will return an unauthorized error indicating that authentication is required.

📸 Screenshot 1: Unauthorized Access

REST API

👤 Step 1: Create a Limited-Access User Account

Navigate to User Management

Go to: System Administrator → Security → Users.

Create a New User

Click “Create New User”
Enter a Username (e.g., Test)
Fill in other details: Name, Comment, etc.
Set a Password (e.g., restTest764)
Click Save

📸 Screenshot 2: Creating a New User

Assign Roles

Navigate to the Roles section
Select the appropriate %DB_… role
Click Assign

📸 Screenshot 3: Assigning Roles to the User

REST API

📸 Screenshot 3: Assigning Roles to the User

REST API

Step 2: Verify the User Account

Log Out from the Management Portal

End your current session as the admin user.

Log In with the New User

Use the username and password you created (e.g., Test / restTest764).

Verify Access

Ensure the user has limited access as per the assigned roles.
Confirm the user can only access the intended REST services and no other administrative functions.

REST API

📸 Screenshot 4: Limited-Access View for the User

REST API

🔐 Step 3: Convert Username and Password to BASE64

⚠️ Note:

The username and password must match the credentials created in the Management Portal.

Go to a Base64 Encoder

Example: https://base64.guru/converter/encode/text

Enter the Credentials

Format: Username:Password
Example: Test:Test123

Copy the Encoded Value

This BASE64 value will be used for authorization in Postman or other REST clients.

📸 Screenshot 5: BASE64 Encoding of Username and Password

REST API

🔑 Step 4: Set Up the Password in Postman

Open Postman

Launch Postman on your system.

Go to the “Headers” Tab
Enter Authorization Header

Key: Authorization
Value: Basic <your_base64_encoded_value>

📸 Reference Screenshot
- See Screenshot 6 below for guidance.

📸 Screenshot 6: Setting Authorization Header in Postman

REST API

🧪 Step 5: Test the REST API with Authenticated User

Send the Request in Postman

Ensure the Authorization header is set with your BASE64 credentials.
Use the same endpoint you configured in the Management Portal.

Verify the Response

If everything is set up correctly, the REST API will return a valid response.

Example Response

(This is an example response from a successful request using my setup.)

REST API

🏁 Conclusion: Providing Access to End Users

Share the BASE64 Credentials

Provide the Base64-encoded username and password to your end users so they can access the REST API.

Security Note

This is a basic authentication approach and is not the most secure method.
For a more secure authentication approach using JWT / OAuth2.0, refer to this InterSystems Community article: Generate JWT / OAuth2.0 Signature
You can read more about JWT in my other article.

👍 Final Tip
- Ensure users are aware of their credentials and the limited-access permissions you have set in HealthConnect.

I hope this guide helps you set up and test your REST API successfully!

REST-API-QueryResponse Awaiting Review