> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blis.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Instrument setup

> Connect laboratory instruments for automated result import

## Overview

bLIS supports automated result import from laboratory instruments through [bLIS Gateway](/gateway), a middleware service that connects your analyzers to bLIS over the network. This removes the need for manual result entry and ensures fast, accurate data transfer.

## Architecture

```mermaid theme={null}
graph LR
    Instrument[Laboratory<br/>Instrument]
    Gateway[bLIS Gateway]
    bLIS[(bLIS)]

    Instrument -->|TCP / MQTT| Gateway
    Gateway -->|HTTP| bLIS
```

The integration flow:

1. **Instrument** outputs results via a network connection
2. **bLIS Gateway** receives the data, parses the instrument protocol, and normalizes the results
3. **bLIS** imports the results and matches them to test orders

For details on installing and configuring bLIS Gateway, see the [bLIS Gateway documentation](/gateway).

## Instruments

### Instrument configuration

Each instrument registered in bLIS has:

| Field         | Description                              |
| ------------- | ---------------------------------------- |
| Reference     | Unique short identifier (e.g., "BCT-01") |
| Manufacturer  | Instrument manufacturer name             |
| Model         | Specific model number or name            |
| Serial Number | Device serial number                     |

### Create an instrument

1. Navigate to **Administration** > **Instruments**
2. Click **New Instrument**
3. Fill in:
   * **Reference**: Short identifier used by integrations (e.g., "BCT-01", "ABX-HEMA")
   * **Manufacturer**: e.g., "Beckman Coulter", "Abbott", "Roche"
   * **Model**: e.g., "DxH 900", "Architect c8000"
   * **Serial Number**: Found on the instrument label
4. Save the instrument

<Tip>
  The **Reference** field is how bLIS identifies which instrument sent results. Keep it short and consistent.
</Tip>

### Link tests to instruments

Link test specifications to instruments so bLIS knows which tests the instrument can perform:

1. Go to **Administration** > **Test Specifications**
2. Edit the test specification
3. Set **Instrument ID** to the appropriate instrument
4. Save changes

Tests linked to instruments will:

* Appear in test runs for that instrument
* Accept automated result import
* Show the instrument reference in result metadata

## Result import

### How results flow

1. **Instrument sends results** via a network connection to bLIS Gateway
2. **bLIS Gateway parses and forwards** the data to bLIS
3. **bLIS matches results** to test orders by sample barcode and instrument code
4. **Results are entered** into the matching test orders

By default, results are entered at **initial** status and require a technologist to review and finalize them before reporting. A bLIS administrator can configure auto-finalization rules for specific result types, allowing qualifying results to be validated and finalized automatically without manual intervention.

For a detailed walkthrough of the result upload and order download workflows, see the [bLIS Gateway integration guide](/gateway/integration).

<Info>
  Results that cannot be matched to a test order are still stored in bLIS for audit purposes. See [Unmatched results](/gateway/integration#unmatched-results) for details.
</Info>

### Individual results

Each result within a set contains:

| Field           | Description                                             |
| --------------- | ------------------------------------------------------- |
| Test Code       | Instrument's test identifier                            |
| Test Name       | Human-readable test name                                |
| Value           | Result value (numeric or text)                          |
| Units           | Measurement units                                       |
| Reference Range | Normal range from the instrument                        |
| Flags           | Abnormal flags (H, L, A, etc.)                          |
| Result Status   | Status from the instrument (F = Final, P = Preliminary) |

### Matching logic

bLIS matches instrument results to test orders using two keys:

1. **Sample barcode** (primary) — the barcode scanned by the instrument is matched to a sample record in bLIS, which links to an accession. If the barcode does not resolve, bLIS falls back to matching by accession ID.
2. **Instrument code** — each result carries a test code from the instrument. bLIS matches this against the **instrument code** configured on each test result specification.

Both the sample and the instrument code must match for a result to be entered automatically. For a detailed explanation, see [Result matching](/gateway/integration#result-matching).

## Quality control integration

Instrument QC results are tracked separately from patient results:

* **Lot number** — QC material lot
* **QC level** — Control, calibrator, etc.
* **Result** — Measured value
* **Date** — When QC was performed
* **Test spec** — Which test was controlled

Access QC data through **Administration** > **Instruments** > **QC Results**.

## Troubleshooting

### Results not importing

**Check bLIS Gateway:**

* Open the [bLIS Gateway web dashboard](/gateway/configuration#web) to verify instrument connections are active
* Review logs for errors
* Confirm the gateway service is running

**Verify instrument connection:**

* Check physical cable connections (serial or network)
* Verify the instrument IP address and port settings match the [gateway configuration](/gateway/configuration#instruments)
* Test connectivity from the gateway host

**Review unmatched results:**

* Check if accession numbers match between the instrument and bLIS
* Verify test codes are mapped correctly

### Results not matching to test orders

Common causes:

* Accession number doesn't match (check format and leading zeros)
* Test code not mapped to any test specification
* Test not linked to the instrument
* Accession is in the wrong status (must be received or in progress)

To resolve:

1. Check the accession number sent by the instrument against actual accessions in bLIS
2. Review test code mappings
3. Verify the instrument is linked to the correct test specifications

### Duplicate results

Causes:

* Instrument resending the same message
* Accidental manual re-query of results

Prevention:

* Check message IDs for duplicates
* Configure instruments to send results once

## Best practices

### Setup

* Use descriptive instrument references that include the location (e.g., "CHEM-LAB2-AU680")
* Test the integration with QC samples before patient samples
* Start with `logOnly: true` in [bLIS Gateway](/gateway/configuration#instruments) to verify communication before going live

### Monitoring

* Use the [bLIS Gateway web dashboard](/gateway) to monitor instrument connections
* Review unmatched results regularly
* Monitor QC results for trends

### Maintenance

* Keep bLIS Gateway updated using the [upgrade command](/gateway/deployment#update-the-gateway)
* Back up your gateway configuration file
* Document custom test code mappings

### Security

* Restrict network access to necessary ports
* Use dedicated VLANs for instrument networks
* Audit result import logs regularly