Referral Status Mapping: Build a Dictionary Both Systems Can Use

The method and examples below are editorial guidance for administrative records. They do not define clinical completion, establish an EHR's actual behavior or describe a tested Linear Health implementation.

Start with meaning, not similar labels

Two systems can use the word "Closed" for different administrative purposes. One might mean a work item was finished; another might require a closure reason. Treat those as questions to resolve with the workflow and integration owners, not interchangeable labels.

AHRQ's workflow assessment toolkit addresses health IT's impact on administrative workflow. A status dictionary is one proposed planning artifact. The detailed rules here are our method, not AHRQ requirements.

Mapping determines what exchanged values mean. Reconciliation checks whether expected records and changes arrived and agree. For broader context, see referral tracking and referral coordination software.

Inventory documented values and actual use

Gather each system's field definitions and allowed values. Then review a representative, approved report of values used across the locations and workflows in scope. Record the period, included sites and exclusions. A local export can reveal older codes or workarounds, while documentation may contain valid but infrequent states absent from that sample.

For each value, capture the field, code, display label, who or what sets it and the event it is intended to represent. Ask whether the same label is used differently across locations. Record any unresolved meaning rather than choosing the interpretation that makes mapping easiest.

Keep free-text notes as contextual evidence unless the workflow owner has defined a supported structured interpretation. A comment containing "booked" should not automatically become a verified appointment state.

Separate the label from its supporting evidence

For every target state, decide what evidence the workflow requires. A linked appointment record, an interface event and a manual assertion are different evidence types. None should be treated as infallible merely because of its format. Capture source, relevant record identifier and event time so a reviewer can inspect the relationship.

The Operational AI Evaluation Kit distinguishes vendor claims, demonstrations and verified evidence. That distinction is useful when asking a vendor to demonstrate the mapping. It is not a clinical truth scale for deciding whether a patient attended.

Keep arrival, a completed visit, a returned note and administrative closure distinct unless a documented local definition explicitly links them. In particular, do not translate a check-in event into a completed-visit claim simply because it looks like progress.

Build a dictionary that shows conditions and lost detail

The following dictionary is synthetic. It illustrates questions to resolve and is not an actual EHR configuration.

There are three separate design questions:

1. Conditional selection: one label can map differently depending on additional evidence. Write the condition explicitly. This is not necessarily information loss if the evidence and original value remain available.
2. Many-to-one conversion: several distinct values may share a target label. Identify the detail that would be lost and preserve it in a supported reason field or history when required.
3. Reverse direction: a target value may not identify one original source value. Specify the write-back rule separately; do not assume the forward mapping can simply be reversed.

A mapping with no lost detail can be valid. The goal is to explain every conversion, not to manufacture lossy entries. Keep independent facts in separate fields where the target supports them rather than forcing every event onto one progress ladder.

Handle unknown and late events without erasing known information

When an unknown value arrives, preserve the source event and expose a mapping issue with an owner. Avoid replacing a supported booking state with a friendly default such as "New." If the software uses a hold state, retain the last supported state alongside it so staff can distinguish an unresolved mapping from a change in the referral itself.

For late events, inspect which referral and appointment the event concerns, its source time, arrival time and any available version or correction relationship. "Latest arrival wins" and "furthest progress wins" can each discard relevant corrections. Choose rules with the workflow owner and test them against the actual integration's event model.

Synthetic event history

At 09:02, a scheduling event links referral R-44 to appointment A-10. At 11:15, a cancellation for A-10 arrives. At 11:16, an arrival event for A-10 arrives with source time 10:58.

The receiving system now has evidence requiring interpretation. Preserve both events, their identifiers and times. Show the conflict to the authorized owner and retain the last supported interpretation. Do not automatically infer attendance, discard cancellation or treat the arrival timestamp as the correct final state. The resolution depends on the source's documented semantics and any correction evidence.

Repeat the example with the cancellation referring to a different appointment, A-11. The dictionary should distinguish the records rather than treating every event on the referral as one sequence. Bring these histories to a Linear Health demo and request the equivalent trace from any vendor under consideration.

Test and approve each dictionary version

Prepare synthetic histories for a clean supported path, a missing record link, an unknown code, a changed closure reason, a duplicate event, a late event and a correction. Include a reverse update that cannot recover the original meaning from the target label alone.

For each test, record the input, expected interpretation, preserved evidence, target fields and next owner if the rule cannot resolve it. Run the same events in different arrival orders where the integration permits that variation. Inspect both the visible worklist and the resulting record; a plausible label alone is not enough.

The evaluation kit asks for handling of missing, contradictory and late information. Use that framework to request proof of the particular behavior in your proposal. It does not prescribe the dictionary shown here.

Version the approved mapping with its scope, owner, reason for change and effective date. Identify affected existing records and whether a historical correction is needed. Do not silently reinterpret old reports under a new definition. If a rule fails, retain the evidence and use the supported recovery process rather than overwriting records from a spreadsheet.

To review a proposed integration's status handling, book a demo with the dictionary and synthetic histories. Ask the vendor to show each uncertain conversion, not just the clean path.

Frequently asked questions

Sources

Sources accessed November 10, 2026.

• AHRQ, Workflow Assessment for Health IT Toolkit.
• Linear Health, Operational AI Evaluation Kit.