HumaCount 5D Middleware

A middleware application that bridges the HumaCount 5D hematology analyzer with a Laboratory Information Management System (LIMS) using the HL7 MLLP protocol.

Developed by CareCode.

---

Overview

This middleware acts as a TCP server that receives HL7-formatted messages from the HumaCount 5D analyzer, parses the result data, and forwards it to a LIMS via a REST API. It also supports pulling test orders from the LIMS to service sample queries from the analyzer.

HumaCount 5D Analyzer  <--HL7 MLLP (TCP)-->  Middleware  <--HTTP REST-->  LIMS

---

Features

• Listens on a configurable TCP port for HL7 MLLP messages from the analyzer
• Parses HL7 OBR and OBX segments to extract sample IDs and test results
• Pushes results to the LIMS via HTTP POST
• Pulls test orders from the LIMS for sample ID queries
• Sends HL7 ACK / NAK responses back to the analyzer
• Structured logging via Log4j2

---

Prerequisites

• Java 11 or higher
• Apache Maven 3.6+

---

Configuration

The middleware reads its configuration from:

D:\ccmv\settings\HumaCount5D\config.json

The configuration file must conform to the MiddlewareSettings schema from the lims-middleware-libraries library. Key fields:

Field	Description
analyzerDetails.analyzerName	Name of the analyzer (e.g., HumaCount5D)
analyzerDetails.analyzerPort	TCP port the middleware listens on
limsSettings.limsServerBaseUrl	Base URL of the LIMS REST API
limsSettings.username	LIMS authentication username
limsSettings.password	LIMS authentication password

Example config.json:

{
  "analyzerDetails": {
    "analyzerName": "HumaCount5D",
    "analyzerPort": 5000
  },
  "limsSettings": {
    "limsServerBaseUrl": "http://localhost:8080/lims",
    "username": "admin",
    "password": "password"
  }
}

---

Building

mvn clean package

The shaded (fat) JAR will be produced at:

target/HumaCount5D-1.0.jar

---

Running

java -jar target/HumaCount5D-1.0.jar

The middleware will load config.json, then start the TCP server on the configured port and begin listening for HL7 MLLP connections from the analyzer.

---

HL7 MLLP Protocol

Messages are framed using the standard MLLP envelope:

Character	Hex	Role
VT	0x0B	Start of block
FS	0x1C	End of block
CR	0x0D	Message terminator

Supported HL7 message types:

Type	Description
ORU^R01	Unsolicited result message — parsed and pushed to LIMS
ORM^O01	Order query — test orders fetched from LIMS

---

Project Structure

src/main/java/org/carecode/mw/lims/mw/humaCount5D/
├── HumaCount5D.java          # Entry point, server lifecycle
├── HumaCount5DServer.java    # TCP server, HL7 message handling
├── AnalyzerCommunicator.java # Low-level analyzer socket communication
├── LISCommunicator.java      # HTTP REST client for LIMS integration
└── SettingsLoader.java       # Loads and exposes config.json settings

---

Dependencies

Library	Version	Purpose
com.google.code.gson	2.8.9	JSON serialization
org.apache.logging.log4j	2.17.0	Logging
org.json	20240303	JSON parsing
com.github.hmislk:lims-middleware-libraries	1.1.4	Shared LIMS data models

---

License

Copyright © CareCode. All rights reserved.