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.

┌──────────────┐        ┌─────────────────────┐        ┌──────────────┐
│   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

All middleware endpoints are available under:

https://<HMIS_HOST>/api/limsmw

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.

"limsSettings": {
    "username": "Analyzer",
    "password": "your_password"
}

If authentication fails, the API returns 401 UNAUTHORIZED.

GET /api/limsmw/test

Response: "Hello, the path is correct!" (200 OK)

Use this to verify connectivity between the middleware and HMIS.

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.

{
    "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"
        }
    ]
}

{
    "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"
        }
    ]
}

• 400 BAD_REQUEST - Invalid input data (missing query record)
• 500 INTERNAL_SERVER_ERROR - Patient sample not found or invalid patient data

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.

{
    "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": ""
        }
    ]
}

Images are sent as Base64-encoded strings with a specific prefix format:

^Image^<TYPE>^Base64^<BASE64_DATA>

Supported image types: PNG, JPG, JPEG, JPE, BMP

{
    "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"
        }
    ]
}

• 400 BAD_REQUEST - Invalid or missing data bundle
• 401 UNAUTHORIZED - Invalid credentials
• 500 INTERNAL_SERVER_ERROR - Processing error (unsupported analyzer, etc.)

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

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

{
    "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:

"observationValue": "^Image^PNG^Base64^iVBORw0KGgoAAAANSUhEUg..."

• 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)

Each middleware application uses a config.json file:

{
    "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
    }
}

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

All middleware applications use the shared library: hmislk/lims-middleware-libraries

Add to your middleware pom.xml:

<dependency>
    <groupId>com.github.hmislk</groupId>
    <artifactId>lims-middleware-libraries</artifactId>
    <version>1.1.4</version>
</dependency>

With JitPack repository:

<repository>
    <id>jitpack.io</id>
    <url>https://jitpack.io</url>
</repository>

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

• LIMS Introduction
• LIMS Analyzer Interfacing
• Testing Middleware

Back to Developer Manual