Analyzers & Integration

Connect hematology, chemistry, immunoassay, and urinalysis analyzers to EaseLab for automatic result import. Supported protocols include HL7 v2 ORU^R01, ASTM E1381/E1394, and JSON REST.

Screen: /analyzers
Ingest endpoint: POST /integrations/v1/results

Integration overview

flowchart LR
    A[Analyzer] --> M[Middleware / LIS bridge]
    M -->|HL7 ASTM or JSON| API[EaseLab API]
    API --> P[Parser]
    P --> M2[Catalog mapper]
    M2 --> R[Results inbox]

EaseLab does not replace full middleware for all instrument brands — many sites deploy a small bridge service that forwards normalized messages with the analyzer API key.

Registering a device

1. Open Analyzers in the lab portal.
2. Click Add Analyzer.
3. Configure:

Field	Description
Name	Friendly label (e.g., "Chemistry – Cobas")
Protocol	Hl7, Astm, or JsonRest
Serial / model	Optional asset tracking
Active	Disable during maintenance

4. Save — EaseLab displays a one-time API key (mlk_...).
5. Copy the key into your middleware configuration immediately.

API key shown once

The raw key cannot be retrieved later. If lost, rotate by creating a new device or regenerating per your deployment policy.

Keys are stored as SHA-256 hashes server-side; only a prefix is shown for identification.

Authentication

All ingest requests require:

X-Analyzer-Key: mlk_your_device_key_here

Endpoint	Auth required
POST /integrations/v1/results	Yes
GET /integrations/v1/health	Yes (except unauthenticated health probe in some configs)

Failed auth returns 401. Locked tenants return 403 with TENANT_LOCKED. Plans without analyzer feature return 403.

Protocol details

HL7 v2 ORU^R01

• Content-Type: text/plain
• Payload: raw HL7 message with OBX segments
• Barcode typically in OBR or PID depending on middleware mapping
• OBX-3 carries analyte identifier for catalog mapping

ASTM E1381/E1394

• Content-Type: text/plain
• Record-based framing (STX/ETX) handled by parser
• Result records map to analyte codes and values

JSON REST

• Content-Type: application/json

{
  "barcode": "S-20250611-0042",
  "patientRef": "MRN-1001",
  "results": [
    {
      "analyteCode": "WBC",
      "analyteName": "White Blood Cells",
      "value": "7.2",
      "unit": "10*3/uL",
      "referenceRange": "4.0-11.0",
      "abnormalFlag": "N"
    }
  ]
}

Field	Required
barcode	Yes — must match registered sample
results[]	Yes
analyteCode	Yes — maps to catalog parameter
value	Yes
patientRef	Optional cross-check

End-to-end setup flow

sequenceDiagram
    participant Admin
    participant EaseLab
    participant Bridge
    participant Machine
    Admin->>EaseLab: Register analyzer + copy API key
    Admin->>EaseLab: Register sample with barcode
    Machine->>Bridge: Raw results
    Bridge->>EaseLab: POST /integrations/v1/results
    EaseLab->>EaseLab: Parse + match barcode
    EaseLab-->>Bridge: 200 OK + resultsImported

Response codes

Code	Meaning
200	Success — check resultsImported count
401	Missing or invalid API key
403	Tenant locked or plan restriction
422	Parse OK but business rule failed — see logId
400	Empty payload

Success body example:

{
  "message": "Results imported successfully.",
  "barcode": "S-20250611-0042",
  "resultsImported": 12,
  "logId": "uuid"
}

Catalog mapping

Machine code	EaseLab field
OBX-3 / ASTM code	Parameter code in catalog
Units	Parameter unit
Reference range	May override catalog default

Unmapped codes appear in inbox with import warnings — add parameters or alias tables in middleware.

Plan features

Analyzer integration may be gated by subscription plan (HasAnalyzerIntegrationAsync). Verify entitlement on Subscription before go-live.

Security practices

Practice	Detail
TLS only	Never send API keys over HTTP in production
Key per device	Revoke compromised keys individually
IP allowlist	Optional at reverse proxy
Payload logging	Restrict log access — contains PHI

Health monitoring

Poll GET /integrations/v1/health with API key from middleware:

{
  "status": "ok",
  "device": "Chemistry – Cobas",
  "protocol": "Hl7"
}

Use for uptime dashboards and alert when ingest silence exceeds threshold.

Troubleshooting

Symptom	Check
401	Key header name exact: X-Analyzer-Key
422 unknown barcode	Sample registered before ingest
Partial import	OBX codes not in catalog
Duplicate results	Middleware retry without idempotency
Example testing	Use API docs sample payloads

Related documentation

• Samples
• Results Inbox
• How-To: Connect an Analyzer
• Troubleshooting: Analyzers