Clinical Staff Master Data Management with RESTful APIs and Dynamic Mapping on InterSystems IRIS for Health

Project Overview:

The Clinical Staff Master Data Management (CSMDM) system is a full-stack healthcare integration application built on InterSystems IRIS for Health. It centralizes and standardizes clinical staff metadata into a single authoritative repository, exposed through RESTful CRUD APIs and reusable backend methods.

The platform eliminates fragmented lookup tables and hardcoded mappings that commonly cause errors in HL7 and FHIR integration workflows, ensuring data consistency and interface reliability.

Application to Other Domains:

This approach can be applied to other domains such as Financial Services, Insurance, and similar industries by extending existing data models or creating new domain-specific classes based on their data mapping needs. It centralizes master data, standardizes schemas, and uses reusable services to ensure consistent and reliable integrations.

Problem Statement:

In healthcare integration environments, particularly in HL7 and FHIR workflows, clinical staff data often faces the following challenges:

• Scattered across multiple systems
• Multiple redundant lookup tables
• Inconsistent codes leading to invalid messages
• Increased maintenance due to duplicate mapping tables

Each clinical interface frequently requires multiple identifiers such as: Consultant Code or attending doctor code, Provider ID, GMC Number, Occupation Code, Specialty Code, Department, etc during the HL7 or FHIR based interface design. These issues create operational inefficiency, risk of interface failure, and increased maintenance overhead if not managed properly.

Proposed Solution:

The CSMDM system provides a centralized Clinical Staff Master Table and a RESTful API layer, which:

• Stores all clinical staff metadata in a single persistent table
• Provides full CRUD operations via REST
• Supports real-time lookups for integration engines
• Serves HL7, FHIR, JSON, XML, and file-based interfaces
• Eliminates redundant lookup tables
• Offers dynamic methods for clinical data mapping to streamline interface design

REST API Layer

Implemented using %CSP.REST, the API exposes the following endpoints:

Reusable backend methods are implemented in classes that can be directly called during interface development for data mapping. Usage instructions are provided in the README file.

Architecture Flow:

• Frontend: HTML, CSS, Bootstrap, jQuery AJAX
• REST API Calls
• IRIS for Health REST Service (%CSP.REST)
• Business Logic Layer: ObjectScript, JavaScript
• Persistent Clinical Staff Master Table
• Dynamic methods for clinical data mapping
• • Example methods and usage are provided in SMDM.CustomDataLookup.Classes.ClinicalStaffMapping
• • Can be directly called during interface development (Code or DTL)

Key Benefits:

• Single source of clinical staff information
• Real-time access for integration engines
• Eliminates duplicate mapping tables
• Reduces operational maintenance
• Full CRUD capability via REST APIs
  -Dynamic mapping for interface design
• Supports integration intelligence for HL7, FHIR, and multi-format workflows

Usage Instructions:

The data managed through this interface can be seamlessly utilized in HealthConnect rules or data transformations, eliminating the need for constant manual monitoring and management of the lookup tables and thereby saving significant time.

Step 1: Setup Web Application for REST Handler

Follow the steps below to create a new web application for the REST handler.

1. Go to System Administrator → Security → Application → Web Application and click Create New Web Application.
2. You will see a screen like the one below:

3. Enter the following details:
   Name: /csp/custom-data-lookup/api
   Dispatch Class: CSMDM.CustomDataLookup.RESTService.Configuration.RestHandler
   Namespace: Select your namespace

Note: Make sure to select the correct namespace for your environment.

4. Click the Save

Step 2: Setup Web Application

1. Go to System Administrator → Security → Application → Web Application and click Create New Web Application.
2. You will see a screen like the one below:
   
3. Enter the following details:
   Name: /csp/custom-data-lookup/webapp
   Namespace: Select your namespace

Note: Make sure to select the correct namespace for your environment.

4. Click the Save

⚠️ Note: After this, your application should look like the screenshot below.

✅ If you see the same two configuration names with your own namespace instead of SANJIBPANDEY, the configuration is complete.

ℹ️ Additional Information:

If you want to set up a password or configure the REST API, please refer to my article: QueryResponse Interface Design and Development Guide Based on REST API.
Information:

Step 3: Import and Compile the Package in InterSystems Cache via Visual Studio

📂 Download the Package
-Download the required packages from the CodePackages folder

1. CSMDM.xml

🖥️ Open Studio and Set Namespace
-Launch Studio.
-Change to the appropriate namespace (must match your web app).

⚙️ Import the File and Compile
-Go to Tools → Import → Local
-Select the file CSMDM.xml.
-After importing, compile the package to ensure all classes are ready for use.

✅ Verify Imported Classes
Confirm that the following classes are present after import and compilation:
-CSMDM.CustomDataLookup.Classes.ClinicalStaffMapping
-CSMDM.CustomDataLookup.RESTService.Configuration.RestHandler
🖼️ See Screenshot

2. csp_custom-data-lookup_webapp_js_clinicalStaffManager.xml

This is a JavaScript file.

• Import it into your namespace.
• Compile it after import.

3. csp_custom-data-lookup_webapp_ClinicalStaffsRecord

This is a Web Application CSP page.

• Import it into your namespace.
• Compile it after import.

✅ Note: After importing and compiling, your files should appear like the screenshot below.

⚠️ Note:
If for some reason you are not able to import the JavaScript and Web App files, .txt versions of those files are also provided (including a README file).

You can directly copy and paste the downloaded CSP and JS .txt files into the physical path shown in the Web Application setup (this path may be different if you defined your own).

⚠️ Make sure to remove the .txt extension before using the files.

After placing the files in the correct location, open them from Studio and compile them.

Alternative Method:
You can create a new CSP page in Studio, paste the provided code into it, and then compile both files.

🎉 All Done!

The configuration and setup are now complete.

🚀 Test the Application

If everything is configured correctly, the application should load successfully.
⚠️ If you encounter any issues, verify:

• Web Application configuration
• Namespace selection
• Files are properly imported and compiled

📸 Screenshot 1: Web App Landing Page

Below is the landing page of the Web Application after successful configuration and launch.

📸 Screenshot 2: Add Staff Record

📸 Screenshot 3: Update Record

📸 Screenshot 3: Delete Record

🔎 Search Functionality
You can search for records using the search bar. Simply enter any of the following based on your requirement:Consultant name, code, GMC number or other relevant keywords.

Clinical Staff Data Mapping

Three methods are implemented in the class:
CSMDM.CustomDataLookup.Classes.ClinicalStaffMapping

1️⃣ MapStaffConsult

ClassMethod MapStaffConsult(StaffID As %Integer) As %String

This is a static method.

It maps staff consultation data based on the provided StaffID.

📸 Screenshot:

2️⃣ GetMappingValue

-Method Name : ClassMethod GetMappingValue(getKeyColumn As %String, CValue As %Integer, outputValue As %String) As %String

etrieves a single mapping value based on your requirement.

-Allows you to specify:

-getKeyColumn – Key column name

-CValue – Column value

📸 Screenshot:

3️⃣ GetMappingValues

-Method Name : ClassMethod GetMappingValues(getKeyColumn As %String, CValue As %Integer, mapValues As %String) As %String

-A more dynamic and robust method.

-Allows you to retrieve multiple column values.

-Output is returned in JSON format.

-You can pass multiple column names as output parameters.

📸 Screenshot:

✅ These methods provide flexible mapping capabilities that can be integrated into HL7, FHIR, JSON, or other interface implementations.

📩 Support
-If you need any assistance or support, please feel free to contact me. I’ll be happy to help.

Conclusion

CSMDM centralizes clinical staff data and provides a robust REST API with full CRUD capabilities—Create, Read, Update, and Delete. This ensures consistent, accurate data across HL7 and FHIR integrations, streamlines interface development, reduces errors, and minimizes operational overhead.

Thank you.