You’re exploring the full DataBridge platform free, with synthetic Future Horizons University data. Everything is unlocked; actions run in your demo session (in-session only, not saved to a real backend).

FHU Databridge
Enterprise
Pricing
Integrator & IT
8 min

Field mapping

Map source-native fields to the canonical model.

By the end you’ll be able to

  • Understand the **canonical model** and why the platform pivots through it.
  • Read an adapter's `resource-map.ts` and map a source field to a canonical one.
  • Know how crosswalks (e.g. HESA `ETHNIC`, `DISABLE`) plug into the mapping.

DataBridge does not write rules against source-native schemas. Instead, every adapter projects its source resources into a canonical model (`@databridge/canonical`) — `Student`, `Course`, `Module`, `Instance`, `Entry`, `Provider`, `Staff` and friends. Audit rules, return builders, lineage traces and crosswalks all operate on the canonical model. That's how one rule pack works against SITS, Banner, Workday and Callista without forking.

The bridge between source and canonical lives in each adapter's `resource-map.ts` — a typed map from source resource + field to canonical entity + field. The HESA-rich Student fields (`DOMICILE`, `HUSID`, `NATION`) added in PHASE_RESERVOIR A.2 are a recent worked example: SJMS-5 source columns now project into canonical Student fields, which means the F03 domicile / ethnicity rules fire on real lake data without any rule changes.

Where source values use a closed vocabulary (e.g. textual `ETHNIC` enums, codes for `DISABLE`), the mapper composes with a codeset crosswalk rather than embedding the translation inline. The crosswalk lives in `codeset-seeds-hesa` (or its sector equivalent) and cites the published HESA coding manual. Shipping a new source value list is therefore a citation exercise, not a mapping refactor.

Practically: open the Schema Mapper for a connected system to see candidate field bindings, confirm or amend them, and save. In demo mode you'll see the simulated 'saved' toast; the real backend persists the binding to the adapter's runtime config. The Integrations overview links to per-system mappings for everything currently connected.

Walkthrough

  1. 1.Open the Schema Mapper

    The Schema Mapper is where source-field → canonical-field bindings are reviewed and edited.

    Open Schema Mapper

  2. 2.Pick a system to map

    From the Integrations screen, drill into one system and follow the link to its mapping. Notice how candidate canonical bindings are suggested per source field.

    Open Integrations

  3. 3.Check the codeset crosswalks

    Open the Codesets reference to see published vocabularies (e.g. HESA `ETHNIC`, `DISABLE`, `DOMICILE`). Closed-list source values are translated via these, not hard-coded in the mapper.

    Open Codesets

Your turn

Open the Schema Mapper and identify one source field that already binds to a canonical entity (e.g. a Student field). Note the canonical entity it lands in and whether a codeset crosswalk is involved.

Hint: The 'Open Schema Mapper' step takes you straight there. Closed-vocabulary fields show their crosswalk; free-text fields don't.

Knowledge check

1.Why do audit rules and return builders run against the canonical model, not the raw source?
2.Where does the source → canonical binding live for a given adapter?
3.How are closed-vocabulary source values (e.g. ethnicity text) translated to published codes?

Complete this lesson