Welcome
Interface Mapping Adoption Guide
Common Errors and FAQ
This section addresses frequently encountered issues during the mapping exercise and provides remediation approaches.

HCL MaxAI CDM Documentation
Release Notes
Installation Guide
User Guide
Ops Guide
Interface Mapping Adoption Guide
- Introduction
  This Adoption Guide explains, in plain language, how to perform that mapping exercise end-to-end, from understanding your source data all the way to validated, signed-off mapping rows ready for metadata loading and ETL generation.
- Why Interface Mapping Matters
  A CDM onboarding project can only succeed if the mapping exercise is done well. Poor mapping has cascading effects across data quality, ETL generation, analytics, compliance, timeline, and MaxAI readiness.
- Where It Fits in CDM Onboarding
  CDM onboarding follows a structured lifecycle. The interface mapping exercise sits at the heart of the Discovery and Design phase — after source understanding and before any ETL or DDL is generated.
- Roles and Responsibilities
  The mapping exercise requires involvement from five key roles, each bringing specific expertise and perspective to ensure the exercise is complete and correct.
- Pre-requisites Before Mapping Starts
  Do not open the MID until the following artefacts have been collected from the client. Attempting to map without these leads to guesswork and rework.
- Understanding CDM Subject Areas
  You do not need to know the full CDM model in detail before starting. Use the subject area guide to identify which family of LDZ tables your source data likely belongs to.
- Mapping Principles
  These principles must guide every mapping decision. Violating them leads to data quality problems, ETL complexity, and rework.
- Step-by-Step Mapping Method
  Follow all eight steps in sequence for each source system in scope. Do not skip steps to save time — each step produces decisions that the next step depends on.
- How to Choose the Right Target Table
  Use this decision guide when you are unsure which CDM entity to target. Work through the questions from top to bottom and stop at the first match.
- Common Mapping Patterns
  The following patterns appear in almost every CDM onboarding engagement. Recognising the pattern early saves significant time.
- Worked Examples
  The following worked examples use a fictional retail bank, "Horizon Bank", which is onboarding its core banking data into CDM.
- Data Quality and PII Guidance
  Every mapping row in the MID should have at least one data quality rule. Every source column containing personally identifiable information must be flagged in the PII column.
- Handling Gaps and Extensions
  Not every source field will have a direct target in the standard CDM model. Follow a hierarchy of options before raising an extension request.
- Review and Sign-off Process
  The mapping is not complete until all three sign-off gates have been passed. The order matters — do not request engineering sign-off before business sign-off.
- Debugging and Validation Steps
  After the first ETL run, use the following structured debugging checklist to validate that data has loaded correctly from source to LDZ. Work through each check in sequence.
- Common Errors and FAQ
  This section addresses frequently encountered issues during the mapping exercise and provides remediation approaches.
- Final Checklist
  Use this checklist to confirm that the mapping exercise is complete and the MID is ready for handoff to engineering. Every item must be checked before sign-off.
CDM Redbook

Common Errors and FAQ

This section addresses frequently encountered issues during the mapping exercise and provides remediation approaches.

Table 1. Common Errors and Solutions
Error / Question	Root cause	Correct approach
Row counts in LDZ are lower than source	1) Rejected rows due to failing DQ rules. 2) ETL filter applied incorrectly. 3) Duplicate NK handling dropping records.	Check ETL rejection log. Review DQ rule thresholds. Inspect NK uniqueness logic.
"I can't find a column in CDM that matches my source field"	Attempting to match by column name rather than business meaning.	Identify the business concept the field represents, then use the target table guide to find the right entity. Map by meaning.
Multiple code values appearing after conversion	Source has introduced new code values after the mapping was designed.	Add an explicit ELSE clause to the code conversion with a default value (e.g., UNKNOWN) and a DQ alert for unmapped codes.
Referential integrity failures after first load	Load sequencing: child entity loaded before parent, or parent records rejected by DQ.	Always load in dependency order: Party → Account → Account_Party → Transactions. Investigate parent rejections first.
"Should I map this field to attrib_1 or request a new column?"	Unclear whether the field has long-term relevance in CDM.	If the field is client-specific and unlikely to be needed across other clients, use attrib_*. If it should be canonical, raise a Design Authority extension request.
Different source systems use different codes for the same concept (e.g., gender)	Each source system has its own code set.	Create a per-source code conversion table in the Transformation column. CDM always stores the canonical code set regardless of source.
"Which grain should I use for ldz_party_contact when my source stores email and phone in the same row?"	Source stores multiple contact types in a single row; CDM stores one row per contact type.	Use an UNPIVOT or UNION ALL in the ETL to generate one row per contact type. Email and mobile each become a separate row with cntct_typ set accordingly.
Duplicate records appearing in LDZ	1) Source has duplicates. 2) ETL running multiple times without truncate. 3) NK not unique at source.	Profile source for duplicates before load. Confirm LDZ load strategy (truncate-and-reload). Validate NK uniqueness at source.