Concept explainer
Mapping fields
Explains how fields in an incoming or outgoing message are matched to Pensieve fields, so data lands in the right place.
A message from another system carries its fields in that system's own layout. Field mapping matches each field to a Pensieve field, so an incoming value lands in the right place and an outgoing message is assembled the way the receiving system expects.
A mapping is per connection and per direction
Each connection holds a separate set of rules for messages coming in and messages going out. Inbound and outbound are held apart, and the reverse of a mapping is tested rather than assumed, so a field dropped on the way out is caught rather than presumed safe.
The rules a mapping is built from
A mapping is a list of rules, and each rule is data, checked when it is saved. A rule reads a field at a source path and writes it to a target path through one transform drawn from a small, closed set.
| Transform | What it does |
|---|---|
| Copy | Carries a value across as it stands. |
| Fixed value | Writes a set value. |
| Translate | Resolves a coded value through terminology. |
| Join | Joins several source values into one. |
| Change type | Converts a value's type, holding its precision. |
| Reformat date | Rewrites a date into the platform's form. |
| Split | Breaks one value into several targets. |
| Default | Supplies a fallback when the source is absent. |
A rule holds data, not code
The transform set is closed, and a rule carries data rather than a script. A saved mapping is checked field by field, so an unknown transform or a stray code string is refused at the boundary rather than run. Logic lives in the named transforms, which keeps a mapping reviewable.
A base and its overrides
A mapping starts from a base, a prebuilt pack for a known message type and vendor, and per-connection overrides sit on top. A field resolves in a fixed order, so the result of a mapping stays predictable across every message on the connection.
An override for a field wins, then the base rule, and a field with neither is surfaced as unmapped and held for attention. A coded field with no rule goes to the terminology queue, and a plain field surfaces as a gap, so the reader sees exactly what a mapping leaves open.
Repeats made explicit
Repeating fields rarely line up one to one between two systems, so a rule states how a repeat is handled. A repeated field can be joined into one value, split across linked entries, taken first, or flagged when more than one value arrives, and the strategy is written into the rule rather than left implicit.
Versions that stay fixed
A live mapping is held fixed. A change cuts a new version and promotes it, and the prior version is retired and kept, so a historical record is always explained by the exact rules that produced it. One version is active for each connection and direction at a time.
Proven before it carries traffic
A mapping reaches live traffic only after a dry run proves its output. A paired check also runs a message in and back out and reports any field lost along the way, and a field dropped on purpose carries a flag, so an honest loss reads as honest and an accidental one is caught.
Common questions
What happens to a field with no rule?
It is surfaced as unmapped and held for attention rather than dropped. A coded field goes to the terminology queue, and a plain field surfaces as a mapping gap.
Can a mapping run a script?
A rule holds data and one transform from a closed set. Logic lives in the transforms, so a mapping stays reviewable and safe to promote.
See how coded terms are matched onto the platform's vocabulary in terminology mapping.