The Status Nobody Mapped: A Holding Queue for Unknown Enum Values

An integration usually receives a status field with a fixed list of values. One day the other side sends a value your code has never seen. Three bad outcomes are common: the record crashes the import, it is silently mapped to some default, or it is dropped. This article proposes a fourth path, an unknown-state mapping queue. It is a conditional design, not a statement about any particular system.

Primary artifact: the unknown-state mapping queue

Each queue entry holds:

the raw value exactly as received
the source record identifier
the source field name and source version or timestamp, if one exists
first seen and last seen times
count of records affected
state: waiting, mapped, rejected
the approved target value, empty until a person sets it
who approved it and when

The raw value is stored untouched, with no case folding that would hide a distinction.

Decision branches

Decide by what the field controls.

Branch 1: the field drives an action, such as sending a message, changing stock or closing a task. Do not act. Hold the record, do not apply a default, and show it as needing a mapping.

Branch 2: the field is informational only. Store the raw value, display it as 'unmapped: value', and let other fields continue. Still add a queue entry so the gap is visible.

Branch 3: a person approves a mapping. Release held records only if the source record has not changed since it was held. If the source sent a newer version meanwhile, discard the old held copy and use the newer one, which goes through the mapping like any other.

Branch 4: a person rejects the value as an error. Keep the entry for evidence and keep affected records held until the source corrects them.

Worked hypothetical

An order feed knows three statuses: paid, shipped, cancelled. A batch of six records arrives: paid, shipped, paid, on_hold, shipped, awaiting_review.

Four records have known values and proceed. Two have unknown values, and each value is different, so the queue gets 2 entries, each with a count of 1. The status drives fulfilment actions, so Branch 1 applies and neither record triggers anything.

Later a reviewer maps on_hold to an existing internal state called paused and rejects awaiting_review as an unclear value. The first held record is checked: its source version is unchanged, so it is released. The second remains held. Final counts: 5 processed, 1 held, 1 queue entry mapped, 1 rejected. Had the on_hold source record been updated in the meantime, the old held copy would be dropped and the newer record evaluated afresh.

Stop conditions

Stop automatic processing of that field if the count of distinct unknown values grows past a limit you set in advance, since the source contract may have changed.
Do not map by guessing from the spelling of a value.
Do not retry an outbound write whose outcome is uncertain; flag it for review.
Do not delete queue entries when mapped; keep them as history.

Proposed acceptance tests (not yet performed)

Send a record with an unseen value and expect a queue entry and no action.
Send the same unseen value five times and expect one entry with a count of five.
Send values differing only by letter case and expect separate entries.
Approve a mapping and expect only unchanged held records to be released.
Update a held record at the source before approval and expect the stale copy to be discarded.
Confirm informational fields show the raw value without blocking other fields.

The design limits damage from surprises; it does not predict which values will appear.