| name | message-lookup |
| description | Check whether an HL7v2 message is already supported by this pipeline (parse → preprocess → convert, prints verdict). Use before building a new converter, triaging "is this supported?", or verifying a parsing/conversion_error fix. |
Message Lookup
Quick go/no-go check: does this HL7v2 message already flow through the pipeline, or does something need to change?
When to use
- Before designing a new converter. If the message already converts cleanly, there is nothing to build.
- When a developer asks "do we support X?" Routing, preprocessing, and config are all in play — don't answer from memory.
- After a fix. Verify the message now succeeds before claiming done.
- Triaging user-supplied sample messages. Produces a one-screen summary instead of walking the code.
Prerequisites
Aidbox must be running. The converter calls resourceExists and loads config; without Aidbox, the script fails before reaching a real verdict.
docker compose ps
If Aidbox is down, tell the developer and stop — do not proceed.
Step 1: Save the message to a file
Put the raw HL7v2 bytes in any file (.hl7, .txt, whatever). MLLP framing bytes (\x0b, \x1c) and CRLF/LF line endings are stripped automatically. One message per file.
Do not hand the script MLLP-framed multi-message dumps — split them first.
Step 2: Run the check
Brief human-readable summary (default):
bun scripts/check-message-support.ts <path-to-file>
Full JSON result (bundle + messageUpdate), for programmatic use or deeper inspection:
bun scripts/check-message-support.ts <path-to-file> --json
Exit code: 0 if the message produces status processed or warning; 1 otherwise.
Step 3: Interpret the output
The brief output has fixed lines: Message, Sender, Routing, Status, Resources, optional Error, Verdict.
| Verdict line | What it means | What to tell the developer |
|---|
supported — message converts cleanly | Status = processed. Bundle built. | "Already supported. No work needed. Here's the resource summary: …" |
supported with caveats | Status = warning. Something was skipped (typically Encounter from a missing/invalid PV1). | "Supported, but [Error line] — decide whether that's acceptable." |
routed but data fails conversion | Status = conversion_error. Message type is known; data is missing/invalid. | Read the Error line — it names the field. Options: sender fixes the data, add a preprocessor, or relax config (required: false). Route to check-errors for a full diagnosis. |
routed but contains unmapped codes | Status = code_mapping_error. | Unmapped codes went to /mapping/tasks. Route to check-errors for resolution. |
malformed — sender must fix | Parse failed, or MSH missing. | Show them which segment/framing is off. No code fix on our side. |
NOT supported — no converter registered | Routing threw Unsupported message type: X_Y. | This is a real "build a new converter" case. Route to hl7v2-to-fhir-pipeline. |
Rules
- Run the script rather than reasoning from the filename or MSH-9 alone. Routing, preprocessing, and config interact — "we have an adt-a01.ts file" is not the same as "this message works."
- Do not paraphrase the
Error line when a conversion fails. Copy it exactly; it names the field.
- Do not keep the temp file around.
rm it after the check.
- Do not edit code based only on this output. A
conversion_error may be a sender issue, a preprocessor gap, or a config tightness — pick one deliberately, with the developer's input.
- NEVER count pipe positions by hand. When the script's
Error line mentions a field (e.g., PV1-19) and you want to confirm what the sender put there, or inspect any other field, use scripts/hl7v2-inspect.sh <file> --segment <SEG> --values (or --field <SEG.N>). Do not read the raw message and count pipes. Do not say things like "the 1 at position N" without running the inspector first. This is the single easiest place to be subtly wrong; eyeballing is banned, full stop. This rule also applies when telling the user what a field contains in a follow-up explanation.
