Mapping (or transformation) failures occur when CIC is unable to successfully translate or transform an inbound or outbound payload using the configured map, ruleset, or schema. These issues commonly arise from data‑quality problems, schema mismatches, or mapping logic errors and can halt document processing until corrected.
What Are Mapping Failures?
Mapping failures occur during the transformation stage of processing, where CIC converts inbound or outbound documents using predefined maps, rulesets, and schema standards (such as X12, EDIFACT, XML, or JSON).
A mapping failure could occur when:
- Required segments, elements, or fields are missing in the input data.
- The inbound payload does not conform to the expected schema.
- A ruleset or mapper function throws an exception.
- A configuration mismatch occurs between the route, profile, or schema version.
- A value cannot be cast, converted, or iterated as defined in the mapping logic.
These failures often stop the integration flow and require targeted investigation.
Detailed Error Types
The following sections outline common mapping failure types, their characteristics, and why resolving them quickly is important for uninterrupted processing.
Schema Validation Error
Definition
Occurs when the inbound payload does not conform to the expected schema (X12, EDIFACT, XML, JSON, or custom structures). The map cannot execute because the document structure is invalid based on required segments, elements, hierarchy, or version.
Key Characteristics
- Violations such as missing required segments/elements, unexpected elements, or incorrect ordering.
- Often linked to incorrect trading‑partner configuration, outdated schemas, or envelope mismatches.
- CIC shows precisely where the failure occurs, including segment position or field reference.
Why It Matters
These errors prevent CIC from reliably interpreting the document, stopping the integration flow early and potentially delaying time‑sensitive transactions. Quick identification helps avoid downstream issues and unnecessary partner escalations.
Ruleset or Functional Mapping Error
Definition
Occurs when a mapping rule or transformation function fails during execution—such as type conversion errors, null dereferences, failed lookups, broken loops, or malformed expressions.
Key Characteristics
- Usually thrown by a specific step or function inside the map or ruleset.
- May result from missing expected values, bad data types, or incorrect script logic.
- CIC identifies the failing map action and provides targeted guidance.
Why It Matters
Functional mapping errors halt processing after the route is successfully matched, meaning the document was otherwise valid. They often require technical intervention, and Guided Resolution helps reduce reliance on specialized mapping experts.
Configuration Mismatch Error
Definition
Triggered when map‑related configuration is inconsistent—such as the wrong schema version, incorrect profile assignment, incorrect route binding, or incompatible map artifacts.
Key Characteristics
- May occur even when the payload itself is valid.
- Often seen after version upgrades, map updates, or partner onboarding changes.
- CIC highlights which configuration objects don’t align (route, profile, schema, or map).
Why It Matters
Misconfiguration can silently break otherwise stable flows and is a common root cause in multi‑partner or multi‑version environments. Addressing these issues quickly prevents repeated failures across multiple transactions.
Data Quality Error
Definition
Happens when required fields within the payload contain missing, invalid, or incorrectly formatted values—even if the overall structure is correct. Examples include invalid dates, non‑numeric values in numeric fields, unsupported codes, or empty mandatory elements.
Key Characteristics
- Payload passes structural validation but fails on value‑level constraints.
- Often introduced by trading partner systems or upstream application exports.
- CIC explains which fields or values caused the failure and their expected format.
Why It Matters
Data issues are common and can cause repeated failures until corrected at the source. Guided Resolution reduces the time to diagnosis and provides partner‑notification templates to streamline communication when the issue originates externally.
Comments
0 comments
Please sign in to leave a comment.