LIMS Analyser Middleware - hmislk/hmis GitHub Wiki
Analyzer Middleware
The analyzer middleware is a standalone software application that runs on a local server or PC in the laboratory. It acts as a bridge between the physical analyzer instruments and the HMIS LIMS — translating the analyzer's native HL7 or ASTM messages into LIMS API calls, and vice versa. This article provides a setup overview for administrators.
Architecture
Analyzer (Sysmex, Dimension, etc.)
↕ HL7 OUL_R22 / ASTM (TCP/IP or serial)
Middleware (local PC/server in the lab)
↕ REST API (HTTP/HTTPS)
HMIS LIMS (application server)
The middleware handles the protocol translation layer. Lab staff do not interact with the middleware directly — once configured, it runs silently in the background.
What the Middleware Does
| Function | Description |
|---|---|
| Receives results from analyzers | Accepts HL7 or ASTM messages from the analyzer over TCP/IP or serial connection |
| Queries pending test orders | Asks the LIMS which tests are pending for a given sample barcode |
| Sends results to LIMS | Posts the analyzer results to the LIMS via REST API |
| Sends ACK messages | Acknowledges receipt of HL7 messages back to the analyzer |
| Logs all messages | Stores all HL7/ASTM messages in the LIMS database for audit and troubleshooting |
Middleware Software
The HMIS middleware is an open-source application maintained by the HMIS team. It is available from the official repository. Contact the system administrator or the HMIS support team for the installer and configuration guide.
Middleware Configuration
The middleware requires a configuration file that specifies:
| Setting | Description |
|---|---|
| LIMS base URL | The URL of the HMIS application server (e.g., https://your-hospital.lk/hmis) |
| API credentials | The API key or username/password used to authenticate with the LIMS REST endpoint |
| Analyzer IP and port | The network address and port of each connected analyzer |
| Analyzer type | The protocol and message format expected from each analyzer (maps to the Analyzer enum in the LIMS) |
| Listening port | The port on which the middleware listens for incoming analyzer connections |
Supported LIMS API Endpoints
The middleware communicates with the LIMS using the following REST endpoints:
| Endpoint | Method | Purpose |
|---|---|---|
/limsmw/test |
GET | Health check — confirm the LIMS API is reachable |
/middleware/test_orders_for_sample_requests |
POST | Query pending test orders for a sample barcode |
/limsmw/limsProcessAnalyzerMessage |
POST | Submit a Base64-encoded HL7 message for processing |
/limsmw/observation |
POST | Submit an individual result observation |
/middleware/test_results |
POST | Submit results from an analyzer |
For full API documentation including request/response formats, see Middleware REST API.
Installation Steps (Overview)
- Install the middleware application on a Windows or Linux server with network access to both the analyzers and the HMIS application server.
- Edit the configuration file to set the LIMS URL, API credentials, and each analyzer's IP address, port, and type.
- Start the middleware service.
- Test the connection using the health check endpoint (
/limsmw/test). - Run a known sample on the analyzer and verify that results appear in the LIMS.
For detailed step-by-step installation instructions, refer to the middleware installation guide provided by the HMIS support team. See also Testing Middleware.
Troubleshooting
| Symptom | Likely cause | Action |
|---|---|---|
| Results not arriving in LIMS | Middleware not running | Check that the middleware service is started |
| Results not arriving in LIMS | Wrong LIMS URL or API key | Verify configuration file settings |
| Analyzer not connecting | Wrong IP or port in config | Check analyzer network settings and config file |
| Wrong results going to wrong patient | Test code mismatch | Verify test code mapping in LIMS investigation items |
| HL7 parse errors in log | Unsupported message type | Check analyzer firmware version; contact HMIS support |
For analyzer-specific guidance, see: