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

# Worklist relay channel

> Configure OIE to relay analyzer barcode lookups to HMIS.

## Purpose

`HMIS Laboratory Worklist Relay` lets an analyzer or simulator request only the worklist for a dispatched specimen barcode. It translates a small JSON lookup request into an authenticated HMIS `GET` request and returns the HMIS JSON response to the caller.

## Channel identity

| Setting                    | Value                            |
| -------------------------- | -------------------------------- |
| OIE version                | `4.5.2`                          |
| Channel name               | `HMIS Laboratory Worklist Relay` |
| Channel revision at export | `5`                              |
| Source connector           | HTTP Listener                    |
| Destination connector      | HTTP Sender                      |
| Source response            | Destination 1                    |

## Source: HTTP Listener

| Setting                  | Value       |
| ------------------------ | ----------- |
| Local interface          | `0.0.0.0`   |
| Local port               | `6662`      |
| Context path             | `/worklist` |
| Data type                | Raw         |
| Charset                  | UTF-8       |
| Authentication           | None        |
| Respond after processing | Yes         |
| Processing threads       | `1`         |

Clients must call this endpoint with a trailing slash:

```text theme={null}
http://oie:6662/worklist/
```

Calling `/worklist` without the final slash can trigger an HTTP redirect. Many HTTP clients follow a `302` by changing the original POST into an empty GET, which causes OIE's JSON parser to fail.

## Source transformer

Add one enabled JavaScript transformer step:

```javascript theme={null}
var lookup = JSON.parse(connectorMessage.getRawData());

channelMap.put('instrument_code', lookup.instrument_code);
channelMap.put('specimen_number', lookup.specimen_number);
channelMap.put('hmis_worklist_auth', 'Bearer {{LAB_WORKLIST_READ_TOKEN}}');
```

The caller sends this request body:

```json theme={null}
{
  "instrument_code": "PILOT-HEM-01",
  "specimen_number": "SP000001"
}
```

## Destination: HTTP Sender

| Setting        | Value                                               |
| -------------- | --------------------------------------------------- |
| URL            | `http://app/api/v1/laboratory/integration/worklist` |
| Method         | GET                                                 |
| Authentication | No                                                  |
| Content type   | `text/plain`                                        |
| Data type      | Text                                                |
| Charset        | UTF-8                                               |
| Request body   | Empty                                               |
| Socket timeout | `30000` ms                                          |
| Queue enabled  | No                                                  |

Configure these headers with **Use Table**:

| Header          | Value                   |
| --------------- | ----------------------- |
| `Authorization` | `${hmis_worklist_auth}` |
| `Accept`        | `application/json`      |

Configure these query parameters with **Use Table**:

| Name              | Value                |
| ----------------- | -------------------- |
| `instrument_code` | `${instrument_code}` |
| `specimen_number` | `${specimen_number}` |

<Warning>
  Commit each table cell with `Enter` or `Tab` before selecting Save Changes. In OIE Administrator, an active uncommitted table cell may appear filled but not persist.
</Warning>

## Required HMIS token

Use a dedicated Sanctum token with exactly this ability:

```text theme={null}
laboratory:worklists:read
```

It is distinct from the results-write token. Never place its real value in the exported XML.

## Expected response

When the specimen is dispatched, pending, and mapped to the requested active worklist-capable instrument, HMIS returns a worklist such as:

```json theme={null}
{
  "status": "available",
  "worklist": {
    "instrument_code": "PILOT-HEM-01",
    "specimen": {
      "number": "SP000001",
      "sample_type": "Blood",
      "tube_type": "EDTA"
    },
    "requisitions": [
      {
        "requisition_number": "DX000001",
        "tests": [
          {
            "analyzer_test_code": "HGB",
            "parameter_code": "PILOT-HGB",
            "result_type": "number",
            "unit": "g/dL"
          }
        ]
      }
    ]
  }
}
```

## Verification and troubleshooting

1. Dispatch a new specimen to the target instrument in HMIS.
2. POST its barcode and instrument code to OIE at `/worklist/`.
3. Confirm OIE shows successful source and destination processing.
4. Confirm the analyzer/mock displays only that instrument's active mapped tests.

| Symptom                          | Check                                                                                                             |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `SyntaxError: Empty JSON string` | The caller likely followed a redirect. Use POST to `/worklist/` with JSON body.                                   |
| `instrument_unavailable`         | Enable the instrument and turn on **Supports orders**.                                                            |
| Required specimen number error   | Add the two destination query-parameter rows and commit the values.                                               |
| `Unauthenticated.`               | Verify the `Authorization` header resolves to `Bearer {{LAB_WORKLIST_READ_TOKEN}}`.                               |
| Empty worklist                   | Confirm the specimen is dispatched, requisition is pending, and its tests are mapped to the requested instrument. |

## Source artifact

`oie-channel-exports/HMIS Laboratory Worklist Relay.xml`