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

# HL7/MLLP results and acknowledgement

> Receive HL7 ORU results, relay them to HMIS, and return an HL7 AA acknowledgement.

## Purpose

`Mock HL7 Results Inbound` accepts HL7 v2 `ORU^R01` messages over MLLP, normalizes each `OBX` result, relays it internally to the Results Relay, and returns an `MSA|AA` acknowledgement when the relay succeeds.

## Source: TCP Listener in MLLP mode

| Setting                  | Value                |
| ------------------------ | -------------------- |
| Local interface          | `0.0.0.0`            |
| Local port               | `2575`               |
| Transmission mode        | MLLP                 |
| Start bytes              | `0B`                 |
| End bytes                | `1C0D`               |
| Mode                     | Server               |
| Data type                | Raw / Text           |
| Keep connection open     | Yes                  |
| Buffer size              | `65536` bytes        |
| Maximum connections      | `10`                 |
| Source response          | Destination 1 (`d1`) |
| Respond after processing | Yes                  |

MLLP framing is handled by OIE. Do not strip `0x0B` or `0x1C 0x0D` in the source transformer.

## Source transformer

```javascript theme={null}
var raw = String(connectorMessage.getRawData())
    .replace(/\r\n/g, '\r')
    .replace(/\n/g, '\r');

var segments = raw.split('\r').filter(function (segment) {
    return segment.length > 0;
});

var msh = segments.filter(function (segment) {
    return segment.indexOf('MSH|') === 0;
})[0];

var pid = segments.filter(function (segment) {
    return segment.indexOf('PID|') === 0;
})[0];

var obxSegments = segments.filter(function (segment) {
    return segment.indexOf('OBX|') === 0;
});

if (!msh) {
    throw 'HL7 message does not contain an MSH segment.';
}

if (!pid || obxSegments.length === 0) {
    throw 'HL7 message must contain PID and at least one OBX segment.';
}

var messageId = msh.split('|')[9];
var specimenNumber = pid.split('|')[3];

channelMap.put('hl7_message_id', messageId);

var results = obxSegments.map(function (segment) {
    var field = segment.split('|');
    var testParts = field[3].split('^');

    return {
        analyzer_test_code: testParts[0],
        value: field[5],
        unit: field[6],
        flag: field[8] || null,
        observed_at: new Date().toISOString()
    };
});

msg = JSON.stringify({
    message_id: messageId,
    instrument_code: 'PILOT-HEM-01',
    specimen_number: specimenNumber,
    received_at: new Date().toISOString(),
    results: results
});
```

The barcode field (`PID-3`) and result fields (`OBX-3`, `OBX-5`, `OBX-6`, `OBX-8`) must be verified against the real analyzer's interface manual.

## Destination: Results Relay

| Setting        | Value                                 |
| -------------- | ------------------------------------- |
| URL            | `http://oie:6661/laboratory/results/` |
| Method         | POST                                  |
| Header         | `Content-Type: application/json`      |
| Content type   | `application/json`                    |
| Request body   | `${message.encodedData}`              |
| Authentication | No                                    |

The destination sends no HMIS credential itself. The Results Relay holds the results-write token.

## Destination response transformer: HL7 ACK

In **Destination 1 → Edit Response**, add this JavaScript step:

```javascript theme={null}
var controlId = String(channelMap.get('hl7_message_id') || '');
var timestamp = new java.text.SimpleDateFormat('yyyyMMddHHmmss')
    .format(new java.util.Date());

var ack = 'MSH|^~\\&|OIE|HMIS|MOCK-ANALYZER|LAB|'
    + timestamp
    + '||ACK|'
    + java.util.UUID.randomUUID().toString()
    + '|P|2.5\r'
    + 'MSA|AA|'
    + controlId
    + '\r';

msg = ack;
responseMap.put('d1', ack);
```

`responseMap.put('d1', ack)` is required because the source response is configured to return Destination 1. OIE adds the MLLP wrapper automatically.

## Validated outcome

A successful test returned an MLLP-framed response containing:

```text theme={null}
MSA|AA|{{ORIGINAL_MESSAGE_ID}}
```

HMIS recorded the integration message as `processed` and completed the requisition after the required HGB result imported.

## Source artifact

`oie-channel-exports/Mock HL7 Results Inbound.xml`