# LIMS Middleware API The LIMS Middleware API enables laboratory analyzers to communicate with the HMIS system. Analyzer middleware applications query for pending test orders and submit results (including images such as chromatograms) back to the HMIS. ## Architecture Overview ``` ┌──────────────┐ ┌─────────────────────┐ ┌──────────────┐ │ Analyzer │◄──────►│ Middleware (Java) │◄──────►│ HMIS Server │ │ (Hardware) │ │ (per-analyzer JAR) │ │ (REST API) │ └──────────────┘ └─────────────────────┘ └──────────────┘ ``` Each analyzer has its own middleware application (a standalone Java JAR) that: 1. Polls the analyzer for new results 2. Queries HMIS for pending test orders 3. Submits results back to HMIS ## Base URL All middleware endpoints are available under: ``` https:///api/limsmw ``` ## Authentication All POST endpoints require authentication via username and password fields in the request body (inside `middlewareSettings.limsSettings`). The HMIS validates credentials against the `WebUser` table using password hashing. ```json "limsSettings": { "username": "Analyzer", "password": "your_password" } ``` If authentication fails, the API returns **401 UNAUTHORIZED**. ## Supported Analyzers | Analyzer Name | Enum Value | Protocol | |---|---|---| | Bio-Rad D10 | `BioRadD10` | HTTP/REST (Web scraping) | | Swelab Lumi | `SwelabLumi` | Serial/ASTM | | Maglumi X3 HL7 | `MaglumiX3HL7` | HL7 | | Mindray BC 5150 | `MindrayBC5150` | HL7 | | Indiko Plus | `IndikoPlus` | Serial/ASTM | | SmartLyte Plus | `SmartLytePlus` | Serial | | HumaCount 5D | `HumaCount5D` | Serial | | HumaLyte | `HumaLyte` | Serial | | HumaStar 600 | `HumaStar600` | Serial/ASTM | | XL 200 | `XL_200` | Serial | | AIA 360 | `AIA_360` | Serial | | Sysmex XS Series | `Sysmex_XS_Series` | HL7/ASTM | | Dimension Clinical Chemistry | `Dimension_Clinical_Chemistry_System` | Serial/ASTM | | Gallery Indiko | `Gallery_Indiko` | Serial | | Celltac MEK | `Celltac_MEK` | Serial | | BA 400 | `BA400` | Serial | ## Endpoints ### Health Check ``` GET /api/limsmw/test ``` **Response:** `"Hello, the path is correct!"` (200 OK) Use this to verify connectivity between the middleware and HMIS. --- ### Query Test Orders for a Sample ``` POST /api/limsmw/test_orders_for_sample_requests ``` The middleware calls this endpoint to find out which tests are pending for a given sample ID. This allows the middleware to know what results to expect from the analyzer. #### Request Body ```json { "middlewareSettings": { "analyzerDetails": { "analyzerName": "BioRadD10", "serialNumber": "d10", "analyzerId": "1492", "departmentAnalyzerId": "653135", "analyzerBaseURL": "http://192.168.1.100/Dia/DiaWeb.cgi/", "departmentId": "484" }, "limsSettings": { "limsServerBaseUrl": "https://your-hmis-host/api/limsmw", "username": "Analyzer", "password": "your_password" } }, "queryRecords": [ { "sampleId": "13876561" } ] } ``` #### Response (200 OK) ```json { "patientRecord": { "id": 0, "billNumber": "12345", "sampleId": "13876561", "patientName": "Mr. John Doe", "dob": "", "sex": "Male", "phone": "0771234567", "address": "123 Main Street, Colombo", "referringDoctor": "Dr. Smith" }, "orderRecords": [ { "id": 0, "sampleId": "13876561", "testNames": ["4548-4", "D10-CHROMATOGRAM"], "status": "S", "date": "2026-05-17T10:30:00", "remarks": "testInformation" } ] } ``` #### Error Responses - **400 BAD_REQUEST** - Invalid input data (missing query record) - **500 INTERNAL_SERVER_ERROR** - Patient sample not found or invalid patient data --- ### Submit Test Results ``` POST /api/limsmw/test_results ``` This is the **primary endpoint** for submitting analyzer results. All modern middleware applications should use this endpoint. It accepts both numeric values and images (e.g., chromatograms) in a single request. #### Request Body ```json { "middlewareSettings": { "analyzerDetails": { "analyzerName": "BioRadD10", "analyzerId": "1492", "departmentAnalyzerId": "653135", "departmentId": "484" }, "limsSettings": { "limsServerBaseUrl": "https://your-hmis-host/api/limsmw", "username": "Analyzer", "password": "your_password" } }, "resultsRecords": [ { "sampleId": "13876561", "testCode": "4548-4", "resultValueString": "6.6", "resultUnits": "%" }, { "sampleId": "13876561", "testCode": "D10-CHROMATOGRAM", "resultValueString": "^Image^PNG^Base64^iVBORw0KGgoAAAANSUhEUg...", "resultUnits": "" } ] } ``` #### Image Format Images are sent as Base64-encoded strings with a specific prefix format: ``` ^Image^^Base64^ ``` Supported image types: **PNG**, **JPG**, **JPEG**, **JPE**, **BMP** #### Response (200 OK) ```json { "status": "Results Plus processed with details.", "details": [ { "sampleId": "13876561", "testCode": "4548-4", "resultValueString": "6.6", "resultUnits": "%", "status": "Success" }, { "sampleId": "13876561", "testCode": "D10-CHROMATOGRAM", "resultValueString": "^Image^PNG^Base64^...", "resultUnits": "", "status": "Success" } ] } ``` #### Error Responses - **400 BAD_REQUEST** - Invalid or missing data bundle - **401 UNAUTHORIZED** - Invalid credentials - **500 INTERNAL_SERVER_ERROR** - Processing error (unsupported analyzer, etc.) #### How Result Matching Works The HMIS matches incoming results to the correct report item using: 1. **Sample ID** - Finds the `PatientSample` record 2. **Test Code** - Matched against `InvestigationItem.resultCode` or `InvestigationItem.test.code` (case-insensitive) 3. **Item Type** - Determines whether to store as a numeric value or image: - `InvestigationItemType.Value` - Stores `doubleValue` and `strValue` - `InvestigationItemType.ReportImage` - Stores `baImage` (byte array), `fileType`, and `fileName` --- ### Submit Observation (Legacy) ``` POST /api/limsmw/observation ``` > **Note:** This endpoint is maintained for backward compatibility. New middleware implementations should use `/test_results` instead. This endpoint accepts a single observation per request and uses a different matching mechanism (valueCodeSystem/valueCode instead of testCode). #### Request Body ```json { "sampleId": "13876561", "analyzerName": "BioRadD10", "analyzerId": "1492", "departmentId": "484", "departmentAnalyzerId": "653135", "observationValueCodingSystem": "http://loinc.org", "observationValueCode": "4548-4", "observationUnitCodingSystem": "http://unitsofmeasure.org", "observationUnitCode": "%", "observationValue": "6.6", "issuedDate": "2026-05-17", "username": "Analyzer", "password": "your_password" } ``` For images, set `observationValue` to the Base64-prefixed string: ```json "observationValue": "^Image^PNG^Base64^iVBORw0KGgoAAAANSUhEUg..." ``` #### Response - **201 CREATED** - "Results Added Successfully for Sample ID : 13876561" - **400 BAD_REQUEST** - Invalid sample ID or malformed image payload - **401 UNAUTHORIZED** - Invalid credentials - **404 NOT_FOUND** - Sample, department, or machine not found - **417 EXPECTATION_FAILED** - Results could not be added (no matching report item) --- ## Middleware Configuration Each middleware application uses a `config.json` file: ```json { "middlewareSettings": { "analyzerDetails": { "analyzerName": "BioRadD10", "serialNumber": "YOUR_SERIAL", "analyzerId": "YOUR_ANALYZER_ID", "departmentAnalyzerId": "YOUR_DEPT_ANALYZER_ID", "analyzerBaseURL": "http://ANALYZER_IP/Dia/DiaWeb.cgi/", "departmentId": "YOUR_DEPT_ID" }, "limsSettings": { "limsServerBaseUrl": "https://YOUR_HMIS_HOST/api/limsmw", "username": "YOUR_USERNAME", "password": "YOUR_PASSWORD" }, "communication": { "queryFrequencyInMinutes": 1, "queryForYesterdayResults": true }, "chromatogramDirectory": "D:\\D10\\chromatograms", "chromatogramTestCode": "D10-CHROMATOGRAM", "disableSslVerification": false } } ``` ### Configuration Fields | Field | Description | |---|---| | `analyzerName` | Must match the HMIS Analyzer enum exactly (e.g., `BioRadD10`, `SwelabLumi`) | | `analyzerId` | The `category.id` (Machine entity) in the HMIS database | | `departmentAnalyzerId` | The `DepartmentMachine.id` in the HMIS database | | `departmentId` | The `department.id` in the HMIS database | | `limsServerBaseUrl` | Full URL to the HMIS middleware API base path | | `queryFrequencyInMinutes` | How often to poll the analyzer for new results | | `disableSslVerification` | Set `true` for self-signed certificates | ## Setting Up a New Analyzer 1. **In HMIS Administration:** - Add the Machine (analyzer) entity with the correct name - Create a DepartmentMachine linking the machine to the lab department - Configure Investigation Items with correct `resultCode` or `test.code` values - For image-type items, set `ixItemType` to `ReportImage` 2. **In the Middleware:** - Set `analyzerName` in config to match the HMIS `Analyzer` enum name exactly - Set `analyzerId`, `departmentAnalyzerId`, and `departmentId` from the database - Configure LIMS credentials (a WebUser with appropriate access) - Test connectivity using the health check endpoint 3. **Verify:** - Send a test result via curl or the middleware - Check that the PatientReport is created with correct values - For images, verify `baImage` is populated and renders in the report viewer ## Middleware Repositories | Analyzer | Repository | |---|---| | Bio-Rad D10 | [hmislk/ccmw-biorad-d10](https://github.com/hmislk/ccmw-biorad-d10) | | Swelab Lumi | [hmislk/SwelabLumi](https://github.com/hmislk/SwelabLumi) | | Maglumi X3 | [hmislk/ccmw-maglumi-x3](https://github.com/hmislk/ccmw-maglumi-x3) | | Mindray BC 5150 | [hmislk/ccmw-mindray-bc5150](https://github.com/hmislk/ccmw-mindray-bc5150) | All middleware applications use the shared library: [hmislk/lims-middleware-libraries](https://github.com/hmislk/lims-middleware-libraries) ## Shared Library (lims-middleware-libraries) Add to your middleware `pom.xml`: ```xml com.github.hmislk lims-middleware-libraries 1.1.4 ``` With JitPack repository: ```xml jitpack.io https://jitpack.io ``` Key classes provided: - `DataBundle` - Top-level request wrapper - `MiddlewareSettings` - Analyzer and LIMS connection details - `ResultsRecord` - Individual test result (value or image) - `QueryRecord` - Sample query request - `PatientDataBundle` - Response with patient info and test orders - `OrderRecord` - Pending test order details - `PatientRecord` - Patient demographics ## Troubleshooting | Symptom | Cause | Fix | |---|---|---| | 401 UNAUTHORIZED | Wrong username/password | Check WebUser credentials in HMIS | | Results not matched | Test code mismatch | Verify `resultCode` on InvestigationItem matches middleware `testCode` | | Image shows as broken icon | `baImage` is NULL | Ensure image format is `^Image^PNG^Base64^` | | SSL errors | Self-signed certificate | Set `disableSslVerification: true` in config | | Analyzer not routed | Wrong `analyzerName` | Must match Analyzer enum exactly (e.g., `BioRadD10` not `Bio-Rad D10`) | | Results stored in wrong report | Multiple reports exist | System picks the latest unapproved report for the investigation | ## See Also - [LIMS Introduction](https://github.com/hmislk/hmis/wiki/LIMS-Introduction) - [LIMS Analyzer Interfacing](https://github.com/hmislk/hmis/wiki/LIMS-Analyzer-Interfacing) - [Testing Middleware](https://github.com/hmislk/hmis/wiki/Testing-Middleware) [Back to Developer Manual](https://github.com/hmislk/hmis/wiki/Developer-Manual)