Machine Flags

Machine Flags are additional indicators sent by lab devices along with parameter results when a sample is processed. These flags help lab staff identify abnormal conditions, quality issues, critical findings, or device-generated warnings before report approval.

The flags originate directly from the lab device and are transmitted through the Interfacing application into the LIMS platform.

Related Concepts

• Device Interfacing
• Device Parser
• HL7 / ASTM Parsing
• Parameter Mapping

What are Machine Flags?

When a lab device processes a patient sample, it does not only generate parameter values like:

• Hemoglobin
• Hematocrit
• RBC
• WBC
• Platelets

It may also generate additional diagnostic or operational indicators such as:

These flags are collectively referred to as Machine Flags.

High Level Workflow

Patient Billing
      ↓
Sample Collection
      ↓
Sample Processed in Device
      ↓
Device Generates Raw Result String
      ↓
Interfacing Application Receives Raw Data
      ↓
Device-Specific Parser Extracts Results + Flags
      ↓
Structured Payload Sent to LIMS API
      ↓
LIMS Stores Results & Flags
      ↓
Flags Displayed on Report UI

Core Architecture

The Machine Flags flow involves three major systems:

Test and Parameter Mapping

Before a device can send results into the system, mapping must exist between:

• Test ↔ Device
• Test Parameter ↔ Device

Example:

This mapping ensures that incoming parsed values can be correctly associated with the corresponding LIMS parameters.

Real World Example

Suppose a patient is billed for:

• CBC Test

The patient's blood sample is processed in:

• Alinity Device

The device evaluates all mapped CBC parameters and generates a raw output string.

Raw Device Response

Devices usually send results in proprietary formats such as:

• HL7
• ASTM
• Custom protocols

Example raw payload:

<VT>MSH|^~&|H560|Erba|||20240330152429||ORU^R01|20240330_150354_204|P|2.3.1
OBX|25|NM|718-7^HGB^LN||11.3|g/dL|11.5-17.5|L~A|||F
OBX|26|NM|4544-3^HCT^LN||34.4|%|35.0-50.0|L~A|||F
OBX|32|NM|777-3^PLT^LN||280|10*3/uL|125-350|~N|||F

The LIMS application cannot directly understand this raw device format.

Interfacing Layer

To solve this problem, an intermediate application called the Interfacing Application is used.

Responsibilities of Interfacing

• Receive raw device strings
• Identify the correct parser
• Parse the raw payload
• Generate structured JSON
• Push data into LIMS APIs

Device Parsers

Each lab device has its own parser.

A parser is generally a JavaScript file responsible for:

• Reading raw device data
• Extracting parameter values
• Extracting flags
• Converting output into a standard structure

Parser Input

parse(rawDeviceString)

Parser Output

{
  "labId": 1,
  "sampleId": "000213826",
  "test_flags": ["Hemolyzed"],
  "data": {
    "values": [
      {
        "testName": "hmg",
        "value": 11.3,
        "param_flags": ["L", "A"]
      }
    ]
  }
}

Types of Machine Flags

Machine Flags are divided into two major categories.

1. Test Level Flags

These flags apply to the entire sample or test.

Examples:

• Hemolyzed
• Review Needed
• Clotted Sample
• Recollect Sample

Example:

{
  "test_flags": [
    "Hemolyzed",
    "Review Needed"
  ]
}

2. Parameter Level Flags

These flags apply to specific parameters only.

Examples:

Example:

{
  "testName": "hmg",
  "value": 11.3,
  "param_flags": ["L", "A"]
}

Important Behaviour

A device may send:

Not every parameter is guaranteed to contain flags.

Standard LIMS Payload

After parsing, the interfacing application sends structured data to the Data Partial API.

Example payload:

{
  "labId": 9,
  "sampleId": "000213826",
  "deviceAuth": "a3c730d7-ba96-449d-89e7-a9dd14a3b03f",
  "test_flags": [
    "DUMMY TEST FLAG1",
    "FLAG2"
  ],
  "data": {
    "values": [
      {
        "testName": "hmg",
        "value": 110.12,
        "param_flags": [
          "P1",
          "H~N"
        ]
      },
      {
        "testName": "plats",
        "value": 220000,
        "param_flags": [
          "A++"
        ]
      }
    ]
  }
}

Flag Storage in LIMS

After API consumption:

• Test-level flags are stored against the sample/test
• Parameter-level flags are stored against individual parameter results

These flags become part of the permanent report metadata.

UI Representation

Machine Flags are displayed visually in the report approval screen.

Sample-Level Flag Display

Displayed near the test header.

Examples:

• Hemolyzed
• Review Needed

Parameter-Level Flag Display

Displayed directly below the affected parameter.

Examples:

• H
• L
• A++
• Warning

Why Machine Flags Matter

Machine Flags are critical for:

Common Examples

Design Considerations

Device Flexibility

Different devices send flags in completely different formats.

The parser layer standardizes all of them into a common structure.

Backward Compatibility

Some old devices:

• Do not send flags
• Send flags in unusual delimiters
• Send combined values like L~A

Parsers must normalize such variations safely.

Non-Blocking Behaviour

Flags should never block result ingestion.

Even if flags are malformed:

• Parameter values should still be processed
• Parser should gracefully fallback

[!NOTE] Machine Flags are treated as supplementary metadata and should not prevent successful result import unless explicitly configured.

Summary

Machine Flags are device-generated indicators received alongside parameter results during sample processing.

The complete lifecycle involves:

1. Device processing
2. Raw payload generation
3. Parser extraction
4. API payload transformation
5. LIMS storage
6. UI visualization

They play a critical role in ensuring report quality, patient safety, and efficient lab operations.