Skip to content

Reference data management

Mapping Datasets

Make code translations between systems explicit and maintainable.

Different systems often use different codes for the same business concept.

An ERP, CRM, data warehouse or reporting platform may classify customers, products or cost centres differently.

A mapping dataset records those relationships as governed reference data so every consumer uses the same translation.

ERP CodeCRM Segment
WH_LOCAL→B2B
WH_INTL→B2B
RETAIL→B2C
ERP to CRM segments · Version 2Owner: Data ManagementPublished
CRMReportingWarehouseIntegrations
One published mapping used across multiple systems.

Definition

What is a mapping dataset?

A mapping dataset stores the relationship between values used by different systems.

It allows integrations, applications and reports to consistently translate one code into another.

  • ERP → CRM
  • Legacy → New Platform
  • Internal Code → External Standard
  • Cost Centre → Reporting Segment
ERPWH_LOCAL
↓
Mapping datasetWH_LOCAL → B2B
↓
CRMB2B

Where it breaks

Why mappings end up in code

Mappings often start as spreadsheets, lookup tables or hard-coded transformations.

Over time, different systems start using different translations for the same value.

  • Different results
  • Different mappings
  • Hidden business logic
  • Unknown ownership
  • No review process
  • Difficult auditing

Hidden mappings

CASE ExpressionWHEN WH_LOCAL THEN B2B
Spreadsheetlookup.xlsx
JSON configurationmapping.json
ETL configurationetl_config.yml
ERP to CRM segmentsVersion 2Owner: Data ManagementEffective date: 2026-01-01Published
Hidden mappings → One published crosswalk

Deterministic lookup

One source code, one answer

Each source value appears once.

Every consumer receives the same answer for the same lookup.

Many source codes can deliberately map to the same target, but a source code never produces competing answers within one publication.

PossibleMany to one
WH_LOCAL→B2B
WH_INTL→B2B
Not possibleOne to many
WH_LOCAL→B2B
WH_LOCAL→SMB

Every source code resolves to one published answer.

Visible exceptions

What happens when a new code appears?

Most mapping problems begin when a source system introduces a value that does not yet exist in the mapping.

That decision should be reviewed explicitly rather than hidden in integration code.

When the source dataset gets a new version, the mapping draft shows which codes are new and not yet mapped, and which were removed from the source.

A draft of the mapping Cost centres to reporting after its source moved to Cost centres V3: code 1030 was removed from the source and is marked for deletion, and the new code 1450 is not yet mapped.

Controlled change

Manage mappings through a controlled process

Mapping changes move through the same review and publication process as other governed reference data.

PrepareDraft
→
ApproveReview
→
VersionPublishVersion 3Effective from 2026-06-01
→
APIConsume
  1. Base the mapping on a source dataset

    Select the published source values and the field that identifies each code.

  2. Review matches and exceptions

    Confirm each translation and keep missing targets visible.

  3. Publish the agreed crosswalk

    Create an immutable mapping version with a release note and effective date.

  4. Let consumers use the publication

    Applications and integrations retrieve the same crosswalk through the API.

Effective dating

Publish mapping versions with effective dates

Mappings change over time.

A new business classification or migration may require a different translation in the future.

Both mapping versions remain available, so consumers can use the translation that applied on a particular date.

Version 2Published
Effective until 2026-06-01WH_LOCAL→B2B
↓
Version 3Published
Effective from 2026-06-01WH_LOCAL→SMB
Consumers get the version that applies on the date they ask for.

Clear scope

A mapping dataset is not field mapping

Field mapping answers:
Which input column populates which field?

Mapping datasets answer:
Which business value corresponds to which business value?

Field MappingCustomer Type↓Segment
Mapping DatasetWH_LOCAL↓B2B

Examples

Common mapping dataset examples

ERP to CRM

Translate customer and segment classifications.

SAP Cost Centres to Salesforce Territories

Map organisational structures across applications.

Legacy to New Platform

Support migrations while preserving meaning.

Cost Centre Mapping

Relate operational and reporting structures.

Internal Codes to Industry Standards

Map business classifications to industry standards.

Warehouse Dimensions

Align reporting data across sources.

Why refrncr

Why teams use refrncr for mapping datasets

  • Published crosswalks
  • One source code, one answer
  • Review workflows
  • Missing mappings remain visible
  • Effective dates
  • Version history
  • Audit trail
  • API access

Start with real data

Start with one mapping that changes too often in code

Choose a mapping currently maintained in spreadsheets, ETL jobs or application code.

Replace hidden translations with a single published mapping dataset and make it available through the API.