> ## 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.

# Integration workflow

> How order download and result upload work between instruments, bLIS Gateway, and bLIS.

bLIS Gateway enables two primary workflows between laboratory instruments and bLIS: **order download** and **result upload**. This page describes both workflows in detail, including how results are matched, when auto-validation applies, and what happens when matching fails.

For an overview of what the gateway is and how to set it up, see [What is bLIS Gateway?](/gateway) and [Configuration](/gateway/configuration).

## Order download

When a sample is loaded onto an instrument, the instrument reads the barcode and queries bLIS for pending test orders. The gateway translates this query and relays the response.

```mermaid theme={null}
sequenceDiagram
    participant I as Instrument
    participant G as Gateway
    participant B as bLIS

    I->>G: Query (sample barcode)
    G->>B: Standardized query
    B->>B: Look up sample & pending orders
    B->>G: Order list (instrument codes)
    G->>I: Translated response
```

<Steps>
  <Step title="Sample loaded">
    A technologist places the sample on the instrument. The instrument reads the barcode.
  </Step>

  <Step title="Instrument sends query">
    The instrument sends a query in its native protocol asking what tests should be run for this sample.
  </Step>

  <Step title="Gateway translates and forwards">
    The gateway converts the query into a standardized format and sends it to bLIS over the secure network connection.
  </Step>

  <Step title="bLIS resolves the sample">
    bLIS looks up the sample by barcode and checks:

    * The sample exists and is linked to an accession
    * The accession has been **received**
    * There are **pending test orders** assigned to this instrument with no existing results
  </Step>

  <Step title="bLIS returns the order list">
    bLIS responds with the list of tests to run, identified by each test's **instrument code** — the identifier the instrument recognizes for that assay.
  </Step>

  <Step title="Gateway translates the response">
    The gateway converts the order list back into the instrument's native format and sends it to the instrument.
  </Step>

  <Step title="Instrument queues tests">
    The instrument receives the orders and queues the appropriate assays for the sample.
  </Step>
</Steps>

### Query outcomes

| Scenario                         | Result                                               |
| -------------------------------- | ---------------------------------------------------- |
| Sample found with pending orders | Test orders are downloaded to the instrument         |
| Sample not found in bLIS         | No orders downloaded                                 |
| Accession not yet received       | No orders downloaded                                 |
| All tests already have results   | No orders downloaded                                 |
| Network or gateway issue         | No orders downloaded (instrument may show a timeout) |

<Note>
  The accession **must be marked as received** in bLIS before orders will download to the instrument. If a technologist reports that orders are not downloading, this is the first thing to verify.
</Note>

## Result upload

After an instrument completes testing, it sends results back through the gateway to bLIS. Results are matched to the correct accession and test order, then entered automatically.

```mermaid theme={null}
sequenceDiagram
    participant I as Instrument
    participant G as Gateway
    participant B as bLIS

    I->>G: Results (native protocol)
    G->>G: Parse & normalize
    G->>B: Standard payload
    B->>B: Match & enter results
    B->>G: Acknowledgment
```

<Steps>
  <Step title="Instrument completes analysis">
    The instrument finishes running the assay and produces results.
  </Step>

  <Step title="Instrument sends results">
    Results are transmitted to the gateway in the instrument's native protocol, including test codes, values, units, flags, and status indicators.
  </Step>

  <Step title="Gateway parses and normalizes">
    The gateway's instrument driver extracts the clinically relevant data and converts it into the standard payload format. Different instruments may send results differently — for example, some transmit multiple data points per test. The driver determines which values are meaningful and should be forwarded.
  </Step>

  <Step title="Gateway forwards to bLIS">
    The standardized payload is sent to bLIS over the secure connection. If the request fails, the gateway retries according to its [configured retry settings](/gateway/configuration#lis).
  </Step>

  <Step title="bLIS matches results">
    bLIS matches each incoming result to an existing test order using the sample barcode and instrument code (see [Result matching](#result-matching) below).
  </Step>

  <Step title="Results are entered">
    Matched results are entered into bLIS at **initial** status. bLIS then evaluates each result against the [auto-validation](#auto-validation) rules. Results that meet the criteria are validated and finalized automatically. Otherwise, they remain at initial status for manual review.
  </Step>
</Steps>

### Result outcomes

| Scenario                             | Result                                                                 |
| ------------------------------------ | ---------------------------------------------------------------------- |
| Sample and test code matched         | Result entered into the matching test order                            |
| Sample matched, test code not mapped | Result stored in archive but not entered into a test order             |
| Sample not found in bLIS             | Result stored in archive with no accession link                        |
| Test order already has a result      | Result skipped (duplicate prevention)                                  |
| Auto-validation criteria met         | Result entered, validated, and finalized automatically                 |
| Auto-validation criteria not met     | Result entered at **initial** status for manual review                 |
| Network or gateway issue             | Gateway retries per configured settings; instrument may show a timeout |

### Result matching

For each result the instrument sends, bLIS performs two levels of matching:

**1. Sample resolution** — The sample barcode from the instrument message is matched to a sample record in bLIS, which links to an accession.

| Identifier     | Source                            | Resolution                                        |
| -------------- | --------------------------------- | ------------------------------------------------- |
| Sample barcode | Scanned by instrument             | Matched to `Sample ID` in bLIS → linked accession |
| Accession ID   | Extracted from message (fallback) | Matched directly to an accession                  |

<Info>
  The sample barcode is the primary matching key. Accession ID is used as a fallback if the barcode cannot be resolved. Both the barcode on the tube and the Sample ID in bLIS must match exactly.
</Info>

**2. Test code resolution** — Each individual result carries a test code from the instrument. bLIS matches this to a test order by comparing the code against the **instrument code** configured on each test result specification.

The instrument code is configured when [setting up test specifications](/admin/test-specifications) in bLIS. Every test result field that should accept instrument results must have its instrument code set to the value the instrument uses for that assay.

### Unmatched results

When a result cannot be matched to a test order, it is still **stored in bLIS** for audit purposes. The result is preserved in the instrument result archive but is not entered into a test order.

Common reasons for unmatched results:

* The sample barcode does not match any sample in bLIS
* The instrument's test code does not match any instrument code configured in bLIS
* The test order already has a result entered (duplicate prevention)
* The result type from the instrument does not match the expected type on the test specification

Unmatched results can be reviewed by administrators in bLIS.

### Auto-validation

When bLIS receives a result from an instrument, it evaluates whether the result can be **automatically validated and finalized** — or whether it should be held at **initial** status for manual review by a technologist.

This decision is based on the result value, the test configuration, and whether the result is part of repeat (reflex) testing. The following rules are evaluated in order:

| # | Condition                                                                     | Outcome                                                   |
| - | ----------------------------------------------------------------------------- | --------------------------------------------------------- |
| 1 | Result has a **failed delta check**                                           | Held for manual review                                    |
| 2 | Result **triggers reflex testing**                                            | Auto-validated so the reflex testing pipeline can proceed |
| 3 | Result is **outside the reference range**                                     | Held for manual review                                    |
| 4 | Result is **within the reference range**                                      | Auto-validated and finalized                              |
| 5 | None of the above apply (e.g., no reference range is configured for the test) | Auto-validated and finalized                              |

<Tip>
  If a result is held for manual review, a technologist must open the accession in bLIS and validate/finalize the result before it can appear on a report.
</Tip>

#### Reflex testing and repeat results

Some tests are configured with **reflex testing** — when the initial result is reactive (e.g., positive), bLIS automatically creates repeat test orders to confirm the finding.

When the instrument sends repeat results for these reflex tests:

* **Within range repeats** (e.g., a negative duplicate) are auto-validated if they match the configured reference value or fall within the reference range
* **Out of range repeats** (e.g., a positive duplicate) are always held for manual review, so a technologist can confirm the result of the repeat testing

This ensures that routine non-reactive results flow through quickly, while reactive or abnormal results always receive human review before finalization.

## End-to-end examples

<Tabs>
  <Tab title="Nonreactive screening">
    **Scenario:** Anti-HCV test with a nonreactive result

    1. An order is entered in bLIS for a subject — test: **Anti-HCV**
    2. The sample is collected, labeled with a barcode, and received in bLIS
    3. A technologist loads the sample on the instrument
    4. The instrument scans the barcode and queries bLIS → orders are downloaded
    5. The instrument runs the Anti-HCV assay → result: **Nonreactive**
    6. The instrument sends the result through the gateway to bLIS
    7. bLIS matches the result and enters it: Anti-HCV = **NR**
    8. NR does not trigger reflex testing, is not out of range, and has no delta check conflict → **auto-validated and finalized**
    9. The result is available on the subject report
  </Tab>

  <Tab title="Reactive with reflex testing">
    **Scenario:** Anti-HCV test with a reactive result that triggers duplicate repeat testing

    1. An order is entered in bLIS for a subject — test: **Anti-HCV** (configured with duplicate reflex testing for reactive results)
    2. The sample is collected, labeled, and received
    3. The instrument runs the assay → result: **Reactive**
    4. bLIS matches the result and enters it: Anti-HCV = **R**
    5. The reactive result triggers reflex testing → bLIS **auto-validates** the initial result and creates two duplicate repeat test orders
    6. The instrument receives the repeat orders on the next query and runs them
    7. Both repeat results come back **Reactive**
    8. bLIS enters each repeat result but holds them at **initial** status — reactive repeats require manual review
    9. A technologist reviews the repeat results in bLIS and validates/finalizes them
    10. The reflex algorithm evaluates all results (initial + repeats), determines the final result by majority, and finalizes the original test order
  </Tab>

  <Tab title="Sample not found">
    **Scenario:** A sample barcode is not registered in bLIS

    1. A sample is loaded on the instrument
    2. The instrument scans the barcode and queries bLIS
    3. bLIS cannot find a matching sample
    4. No orders are downloaded — the instrument shows no tests for this sample
    5. The technologist verifies the barcode and accession status in bLIS
  </Tab>
</Tabs>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Instrument is not downloading orders">
    | Check                   | Action                                                              |
    | ----------------------- | ------------------------------------------------------------------- |
    | Accession not received  | Open the accession in bLIS and verify it has been received          |
    | Sample barcode mismatch | Compare the barcode on the tube with the Sample ID in bLIS          |
    | No tests assigned       | Verify the test specifications are linked to this instrument        |
    | Gateway not running     | Check the [web dashboard](/gateway/configuration#web) or contact IT |
  </Accordion>

  <Accordion title="Results are not appearing in bLIS">
    | Check                      | Action                                                                                |
    | -------------------------- | ------------------------------------------------------------------------------------- |
    | Gateway not running        | Verify the gateway service is active and connected                                    |
    | Instrument code not mapped | Check that each test result spec has the correct instrument code                      |
    | Authentication failure     | Verify the API key in the [gateway configuration](/gateway/configuration#instruments) |
    | Network issue              | Confirm the gateway can reach bLIS over the VPN                                       |
  </Accordion>

  <Accordion title="Result was entered but not finalized">
    This is expected behavior for results that do not meet the auto-validation criteria — for example, results outside the reference range or reactive repeat results from reflex testing. These results are entered at **initial** status and require a technologist to review and finalize them in bLIS. See [Auto-validation](#auto-validation) for the full list of rules.
  </Accordion>

  <Accordion title="Some tests downloaded but others are missing">
    * Verify all expected tests have the instrument assigned in **Administration** > **Test Specifications**
    * Check that each test result spec has an **instrument code** configured
    * Confirm the missing tests do not already have results entered
  </Accordion>

  <Accordion title="Results are stored but not matched to test orders">
    * Compare the instrument's test code with the instrument code on the test result specification in bLIS
    * Verify the sample barcode resolves to the correct accession
    * Check that the result type from the instrument matches the type configured on the test specification (e.g., numeric result for a numeric field)
  </Accordion>
</AccordionGroup>