Lesson 3 of 5
Writing mapping specifications
9 min
A mapping specification is the contract for one migration object. It says which source records are selected, which target fields they fill, and exactly how each value is derived. Developers build from it, testers test against it, data owners approve it and auditors read it. A vague specification produces a load that works and data nobody can defend.
What a specification contains
- Header: object (for example business partner as customer), version, owner, approval date, related cleansing rules.
- Selection rule: which source records are in scope, written so a tester can build records just inside and just outside it.
- Field mapping: one row per target field in the Migration Cockpit template, with the source field, rule type, rule detail and whether the field is mandatory.
- Value mapping tables: every source code and its target code, plus the behavior for codes that are not in the table.
- Exceptions: what happens to records that fail a rule: rejected, reported or held for a decision.
- Test references: the targeted test records that prove each rule.
Build the field list from the target, not the source. Download the template for each object from the Migrate Your Data app in the release you will use, and give every template field a row, even if the answer is "not used". This makes gaps visible: a mandatory target field with no source and no rule is an open question for the owner, not something the developer quietly defaults.
Rule types
| Rule type | Meaning | Example for Contoso customers |
|---|---|---|
| Move | Copy the value unchanged | Customer name to the organization name of the business partner |
| Value mapping | Translate a code through a table | Legacy payment term CR30 to target payment term 0004 |
| Fixed value | Same value for every record | Sales area 1910 / 10 / 00 for all migrated Alternadores customers |
| Derivation | Calculate from one or more fields | Business partner grouping derived from the legacy customer type |
| Lookup | Read a value from another object or table | Customer number of the merge survivor from the cross-reference |
| Reformat | Split, join or reformat | Postal code padded to five digits when a leading zero was lost |
Value mappings deserve particular care because the cockpit itself supports them. During a migration project, the Migrate Your Data app presents mapping tasks for fields whose source values must be translated into target values, and for fixed values. Decide in the specification which value mappings are maintained as cockpit mapping tasks and which are applied earlier in the staging area. Either way the approved table lives in the specification, and the cockpit content must match it.
| Target field | Source | Rule | Detail | Mandatory |
|---|---|---|---|---|
| Organization name | Legacy customer name | Move | Trim spaces; keep capitalization from cleansing rule CL-BP-002 | Yes |
| Payment terms | Legacy payment terms | Value mapping | Table VM-PT v1.3; unknown codes reported to Dan, never defaulted | No |
| Reconciliation account | Legacy receivables account | Value mapping | Table VM-RA v1.1, approved by Dan | Yes |
| Postal code | Legacy postal code | Reformat | Five digits; pad with leading zero when four digits are present | Yes for Mexico |
| Sales area | None | Fixed value | 1910 / 10 / 00 | Yes |
An extract from the Wave 2 business partner specification for company code 1910. Real specifications have many more rows.
What makes a specification testable
A tester should be able to read a rule and write down the expected result for any record without asking anyone. That means no words like "appropriate", "where relevant" or "as needed". It also means every rule says what happens when the input is empty, invalid or not in a mapping table. The specification from the testing course on migration applies here: an unmapped value must be reported for a data owner decision, not silently defaulted, unless the owner approved a default in writing.
- Does the target field just take the source value?Yes → move rule; state trimming and length handling · No → next question
- Is it a code that changes between systems?Yes → value mapping table with unmapped-value behavior · No → next question
- Is it the same for every record in scope?Yes → fixed value, approved by the owner · No → next question
- Is it calculated or read from elsewhere?Yes → derivation or lookup with a worked example · No → open question for the owner
What would you do?
The Wave 2 draft product specification says: "Map the legacy product family to the appropriate S/4HANA product group." The developer asks Priya how to test it. What should Priya do?
- A mapping specification is the contract for one object: selection, field rules, value tables, exceptions and tests.
- Build the field list from the target template so gaps are visible.
- Name a rule type for every field: move, value mapping, fixed value, derivation, lookup or reformat.
- Testable rules have no vague words and define empty, invalid and unmapped behavior.
Check your understanding · not graded
Lesson check
1. Why build the specification field list from the target template?
2. Which rule type translates legacy payment term CR30 into target payment term 0004?
3. What should happen to a source code that is missing from an approved value mapping table, unless the owner approved a default?
4. Which wording makes a rule untestable?