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.

🛠️ Usage Instructions

The step-by-step guideline is provided below:

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

🚀 Step 1: Set Up Web Application

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

1. Navigate to Web Application Setup
   Go to: System Administration → Security → Application → Web Application.

2. 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

3. Enable REST

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

4. Save Your Configuration
   • Click “Save”
   • Refer to Screenshot 2 for an example

📸 Screenshot 2: Web Application and Setting Up REST

🛠️ Step 2: Create Required Classes

A. Create Class – GetRequestDatasets

1. Open Cache Studio

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

2. Create a New Class

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

3. Enter Class Details

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

📸 Screenshot 3: Code for GetRequestDatasets

B. Create Response Datasets Class – SetResponseDatasets

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

1. Create a New Class

• Class Name: SetResponseDatasets

2. Add the Code

• Write the required code for the class
• Compile the class

📸 Screenshot 4: Code for SetResponseDatasets

C. Create Business Process – QueryRequestResponse

1. Create a New Business Process

• Name: QueryRequestResponse

2. Add the Code

• Write the required code for the business process
• Compile it

📸 Screenshot 5: Code for Business Process – QueryRequestResponse

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

D. Create Business Service – GetRequest

1. Create a New Business Service

• Name: GetRequest

2. Add the Code

• Write the required code for the business service
• Compile it

📸 Screenshot 6: Code for Business Service – GetRequest

E. Create REST Handler – RestHandler

1. Create a New REST Handler

• Name: RestHandler

2. Add the Code

• Write the required code for the REST handler
• Compile it

📸 Screenshot 7: Code for RestHandler

✅ 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

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

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

1. 🛠️ Configure Services

   • Select the appropriate class: ...RESTfulAPI.SERVICES.GetRequest

2. 🔄 Configure Processes

   • Select the appropriate class: ...RESTfulAPI.PROCESS.QueryRequestResponse

3. ⚡ 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

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

1. Send a GET Request

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

2. Verify the Response

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

📸 Screenshot 10: Output of Test Case 1

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

1. Send a GET Request

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

2. Verify the Response

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

📸 Screenshot 11: Output of Test Case 2

Test Case 3: Request with an Invalid Patient MRN

1. Send a GET Request

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

2. Verify the Response

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

📸 Screenshot 12: Output of Test Case 3

Test Case 4: Management Portal Services Disabled

1. Scenario

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

2. Send a Request

• Try sending a GET request to your REST endpoint.

3. Expected Output

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

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

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

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

📸 Screenshot 15: Source Message

📸 Screenshot 16: Process Message – Generate Message

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

🔒 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

1. Send a Request Without Credentials

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

2. Expected Result

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

📸 Screenshot 1: Unauthorized Access

👤 Step 1: Create a Limited-Access User Account

1. Navigate to User Management

• Go to: System Administrator → Security → Users.

2. 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

3. Assign Roles

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

📸 Screenshot 3: Assigning Roles to the User

📸 Screenshot 3: Assigning Roles to the User

Step 2: Verify the User Account

1. Log Out from the Management Portal

• End your current session as the admin user.

2. Log In with the New User

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

3. 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.

📸 Screenshot 4: Limited-Access View for the User

🔐 Step 3: Convert Username and Password to BASE64

⚠️ Note:

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

1. Go to a Base64 Encoder

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

2. Enter the Credentials

• Format: Username:Password
• Example: Test:Test123

3. 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

🔑 Step 4: Set Up the Password in Postman

1. Open Postman

• Launch Postman on your system.

2. Go to the “Headers” Tab

3. Enter Authorization Header

• Key: Authorization
• Value: Basic <your_base64_encoded_value>

4. 📸 Reference Screenshot
   • See Screenshot 6 below for guidance.

📸 Screenshot 6: Setting Authorization Header in Postman

🧪 Step 5: Test the REST API with Authenticated User

1. 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.

2. Verify the Response

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

3. Example Response

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

🏁 Conclusion: Providing Access to End Users

1. Share the BASE64 Credentials

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

2. 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.

3. 👍 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!