Worklist relay channel

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:

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:

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:

{
  "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}`

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.

Required HMIS token

Use a dedicated Sanctum token with exactly this ability:

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:

{
  "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

Dispatch a new specimen to the target instrument in HMIS.
POST its barcode and instrument code to OIE at /worklist/.
Confirm OIE shows successful source and destination processing.
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

Foundation

Implementation

Operations

Purpose

Channel identity

Source: HTTP Listener

Source transformer

Destination: HTTP Sender

Required HMIS token

Expected response

Verification and troubleshooting

Source artifact

​Purpose

​Channel identity

​Source: HTTP Listener

​Source transformer

​Destination: HTTP Sender

​Required HMIS token

​Expected response

​Verification and troubleshooting

​Source artifact

Purpose

Channel identity

Source: HTTP Listener

Source transformer

Destination: HTTP Sender

Required HMIS token

Expected response

Verification and troubleshooting

Source artifact