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:

HTTP Method	Endpoint	Function
`POST`	`/ClinicalStaff`	Add a clinical staff record
`GET`	`/ClinicalStaff`	Retrieve all clinical staff records
`PUT`	`/ClinicalStaff/:id`	Update a clinical staff record
`DELETE`	`/ClinicalStaff/:id`	Delete a clinical staff record

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.

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

Configuration Web Application for REST Handler

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.

Click the Save

Step 2: Setup Web Application

Go to System Administrator → Security → Application → Web Application and click Create New Web Application.
You will see a screen like the one below:
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.

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.

Configuration Web Application for REST Handler

ℹ️ 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
Configuration Web Application for REST Handler

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.

Screenshot

⚠️ 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.
Web App Landing Page

📸 Screenshot 2: Add Staff Record

Add Recprd

Add Recprd

📸 Screenshot 3: Update Record

Update Record

Update Record

📸 Screenshot 3: Delete Record

Delete Recprd

Delete Recprd

🔎 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:

MapStaffConsult

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:
GetMappingValue

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:
GetMappingValue
✅ 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 ask or contact me via the web comment page. 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.

CSMDM-Dynamic-Data-Mapping Awaiting Review