Map status and category fields without hiding unknown values
Prepared with AI assistance by Alactic Editorial. Examples identified as hypothetical are illustrative, not customer results.
A source sends a status your destination does not recognise. The integration accepts the record anyway and assigns its default category. Nothing looks broken, but the record now says something the source never said.
A reliable enum mapping strategy makes uncertainty explicit. Map equivalent values directly, consolidate only when the lost distinction is acceptable, reject values that cannot safely be represented, and hold undecided values as unmapped. Preserve the original input and the decision so someone can explain or correct the result later.
This is a translation problem between existing vocabularies, not an invitation to redesign sales stages or reporting categories. The workflow below is a recommended design, not evidence that a particular product provides these controls.
1. Establish meaning before matching labels
Build the crosswalk from the values both systems actually accept, including machine identifiers and definitions. Matching labels are not sufficient: two systems can use the same word for different conditions.
For each field, establish:
- Purpose: which condition it describes and which object it belongs to.
- Allowed values: current identifiers and inactive values still present on older records.
- Absence behaviour: what omission, explicit null, and an empty string mean.
- Write behaviour: whether invalid input is rejected, ignored, or replaced by a default.
- Dependencies: which reports, routing decisions, or authorised workflows depend on the field.
Use documented definitions and confirmation from the business owner. Verify destination behaviour before relying on it. A successful response does not establish that the intended value was stored.
Keep the mapping directional. Several source values may become one destination value, making the reverse transformation impossible without additional context.
2. Use four dispositions and separate reason codes
Every input receives one of four dispositions. These describe processing decisions; they are not necessarily destination categories.
- Direct: definitions match for the intended use. Write the approved destination value.
- Consolidation: several source values share one destination value. Approve the loss of distinction and retain the source value.
- Rejection: the input is known but unsupported under the current contract. Block the entire destination write.
- Unmapped: no approved mapping decision exists. Hold the status and apply the write boundary defined below.
Rejection is a decision; unmapped is an unresolved question. Neither is fixed by repeatedly retrying unchanged input against the same crosswalk.
Use reason codes to distinguish different causes within a disposition. In this design, omitted, null, and empty inputs all receive disposition unmapped, with reasons INPUT_OMITTED, INPUT_NULL, and INPUT_EMPTY. Absence does not create a fifth disposition.
A destination category meaning “the source does not know” is not automatically suitable for “the integration has no mapping.” If no appropriate destination value exists, hold the decision in a review record or staging area. Do not invent an enum member the destination cannot accept.
3. Adopt a filled crosswalk and write-decision matrix
Hypothetical worked example: all systems, values, identifiers, roles, and outcomes in the example are fictional. A service desk sends request_status to a work tracker that accepts OPEN, ACTIVE, and CLOSED. Its agreed definition of active work includes temporary dependency waits.
Reusable crosswalk header: mapping ID request-status; version v3; direction service desk to work tracker; business approver Operations Lead; technical maintainer Integration Engineer.
| Source input | Destination | Disposition and reason | Review owner |
|---|---|---|---|
new | OPEN | Direct: recorded, not started | Operations Lead |
in_progress | ACTIVE | Consolidation: work started | Operations Lead |
waiting_on_requester | ACTIVE | Consolidation: started work awaiting input | Operations Lead |
resolved | CLOSED | Direct: work complete under agreed definitions | Operations Lead |
archived_without_outcome | None | Rejection: UNSUPPORTED_SOURCE_VALUE | Source Data Steward |
| Previously unseen value | None | Unmapped: UNMAPPED_SOURCE_VALUE | Integration Operations; Operations Lead decides meaning |
| Field omitted | None | Unmapped: INPUT_OMITTED | Source Data Steward |
| Explicit null | None | Unmapped: INPUT_NULL | Source Data Steward |
| Empty string | None | Unmapped: INPUT_EMPTY | Source Data Steward |
The unsupported archival value does not establish a work outcome, so it cannot safely become closed. The consolidation also has a cost: destination status alone cannot distinguish working from waiting. If users need that distinction for a critical decision but cannot access the retained context, this consolidation is unsuitable.
Write-decision matrix for this hypothetical contract: status is required on creation. Omission on update is treated as unresolved absence, not as an instruction to leave status untouched. A different update contract would need an explicit, separately tested omission rule.
| Input outcome | Create | Update |
|---|---|---|
| Rejection | Block entire destination write. | Block entire destination write, including descriptive fields. |
| Unmapped value | Hold entire creation; write nothing to destination. | Hold status only; independent descriptive fields may proceed. |
| Missing input: omitted, null, or empty | Unmapped; hold entire creation. | Unmapped; hold status only, using the corresponding absence reason. |
Thus an unsupported value always produces no destination write. An unknown or absent value produces no destination write on creation, but may allow a partial update. These are intentional differences, not interchangeable meanings of “hold.”
4. Record the decision, not just the final category
A destination value cannot explain a many-to-one mapping. Keep a compact processing record rather than copying the entire payload by default. This filled hypothetical record can serve as a reusable starting point:
source_system: service_desk
source_event_id: EVT-771
source_revision: 18
source_record_id: REQ-1042
source_field: request_status
input_presence: present
source_value_raw: waiting_on_requester
source_value_normalized: waiting_on_requester
destination_record_id: WORK-208
mapping_id: request-status
mapping_version: v3
disposition: consolidation
reason_code: APPROVED_ACTIVE_CONSOLIDATION
proposed_destination_value: ACTIVE
written_destination_value: ACTIVE
status_result: written
record_result: complete
review_owner: Operations LeadAdd processing time and retain access restrictions appropriate to the context. For omitted input, record presence as omitted rather than inventing a raw value. For null or empty input, preserve that distinction.
For a held update, the proposed and written destination values are absent; record status as held and the overall result as partial or held, depending on whether independent fields were written. Record any previous destination status separately. Never present that old value as the result of the new mapping.
Preserve raw and normalised input separately. Trimming whitespace requires an approved rule. Case conversion can be unsafe when identifiers are case-sensitive; NEW should not silently become new.
5. Make partial updates visible and safe
The matrix permits partial updates only for unmapped input, including absence. It never permits them for rejection. Even for unmapped input, descriptive fields must be independent of status.
For example, a corrected request title might proceed while status is held. A completion date should not proceed if it would imply that unresolved work has finished. Agree on the eligible field list before processing; do not let the integration improvise it from each payload.
Hypothetical walkthrough: an update for REQ-1042 contains status paused_external and a corrected title. The destination currently says ACTIVE. The value is unseen, so the disposition is unmapped. The title is on the approved independent-field list: write the title, leave status unchanged, and record a partial result with reason UNMAPPED_SOURCE_VALUE.
If that same payload instead contains archived_without_outcome, reject the entire update: neither title nor status changes. If it creates a new record with paused_external, hold the entire creation so omission cannot trigger a misleading default.
Retaining an old status does not confirm it remains current. Expose the pending status decision to reviewers and consumers that rely on synchronisation completeness. If the workflow cannot show that distinction reliably or cannot enforce field separation, disable partial processing and hold the entire unmapped update.
6. Test stored outcomes and event identity
Acceptance tests should inspect destination data and processing records, not just successful requests. For the hypothetical crosswalk, use these cases:
- Direct: create with
new. ExpectOPEN, disposition direct, and versionv3. - Consolidation: process separate records with
in_progressandwaiting_on_requester. Expect both active, with distinct source values retained. - Rejection: test the unsupported archival value on both creation and update. Expect no destination writes, including descriptive changes.
- Unknown: create with
paused_external. Expect no destination record. Update with it and an eligible title correction; expect only the title written and a partial result. - Absence: test omission, null, and empty string separately on creation and update. Expect the same write boundaries as unknown input, but distinct absence reasons.
- Formatting: send
NEWwithout an approved case rule. Expect unmapped, not an inferred match.
Define duplicates using stable source identity, not status value. In this design, the duplicate key combines source system and source event ID; a documented source-record revision can substitute where appropriate.
Submit hypothetical event EVT-771 twice. Expect the second delivery to reference the existing processing result, without another destination write, business action, or review item. A held event stays held; delivery repetition is not approval to retry its business action.
Then submit distinct event EVT-772 carrying the same status. Treat it as a new event, check revision ordering, and evaluate it normally. The destination status may need no change, but retain the new event's outcome. Status equality alone must not suppress other legitimate changes.
Without stable event IDs or revisions, payload similarity cannot reliably distinguish redelivery from a later identical event. Flag suspected duplicates for review and hold potentially repeated side-effecting actions until identity and ordering are established. This fallback sacrifices unattended throughput rather than claiming duplicate protection it cannot establish.
7. Resolve held work without overwriting newer truth
Integration Operations investigates parsing and transport issues; the business owner approves meaning. A technical maintainer should not equate unfamiliar values merely to clear a queue.
Reviewers choose from the same four dispositions. Record the rationale and publish a new crosswalk version when the rule changes. Keep the original decision and append its resolution.
Before authorised replay, check the current source state and destination revision. An item may have changed while waiting. Replaying an old status after a newer event can overwrite correct information. Link the replay to its original event and new mapping version; distinguish deliberate reprocessing from duplicate delivery.
For earlier silent defaults, identify affected records using processing history. Do not assume every record in the default category is incorrect. Many-to-one mappings also need a separate reverse rule: ACTIVE cannot reveal whether the source was working or waiting.
8. Use observable readiness criteria
Sample actual source inputs before expanding processing. Count records as well as distinct values: one unknown code may affect much of the workload.
Track each disposition, unresolved-item age, partial updates awaiting completion, and destination defaults applied without an approved mapping. Keep delivery retries separate from distinct source events so repeated failures do not distort the workload.
Start with one field. Complete its crosswalk, assign owners, agree on the write matrix, and run the acceptance cases against stored results. Readiness means every sampled input has an explicit disposition, every consolidation has an approved rationale, and every held item has a visible resolution path. Unknown values may remain; they should no longer appear to be known categories.
Put the next conversation to work.
Explore Alactic Communications for WhatsApp conversations, campaigns and AI-assisted workflows. Choose the product and plan that fit your team.
Explore Communications