Field Mappings and Defaults

An action needs to know which fields it reads or writes, and what to do when the caller supplies nothing.

Where to find it

Architect Panel → Integration & Connections:

• API Server — the action and its field configuration
• OpenAPI Specification — what the caller is told to send

Architect Panel → Data:

• Datastores — the fields being mapped, and their own validation

What a mapping does

It connects what the caller sends to the field it belongs in. Where the two use different names — and they usually do, because the caller's vocabulary is theirs — the mapping is where that translation lives.

Keep your field names, not theirs

Resist renaming a datastore field to match a partner's API. The mapping exists so their vocabulary stays at the boundary; letting it into your data model means the second partner's names conflict with the first's.

Defaults

A default supplies a value when the caller does not. Useful for fields your process needs but the caller has no reason to know about — a source marker, a status, a channel.

They are also how you keep an API stable while your model grows. Adding a required field to a datastore would break every existing caller; adding it with a sensible default does not.

Required is a promise to the caller

Mark a field required when the operation genuinely cannot proceed without it. That produces a clear rejection at the boundary, which is far better than accepting the call and failing further in — the caller can see what they missed and fix it themselves.

Do not mark something required and then also give it a default; the two express opposite intentions and the result confuses everybody reading the configuration.

Validation still applies

The datastore's own field validation runs regardless of what the API does. An action can accept a value the field will then reject, so if a caller reports mysterious failures, check the field's rules and not only the mapping.

Sensitive values are encrypted

Where an action's configuration includes something secret, it is stored encrypted rather than in plain text — the same treatment credentials get elsewhere.

When a value does not arrive

Work through it in this order, which is roughly by likelihood:

1. Is the caller actually sending it? Check the inbound request log before anything else.
2. Is the mapping pointing at the right field?
3. Is a default silently overwriting what they sent?
4. Is the field's own validation rejecting the value?

The third catches people out most, because everything looks correctly configured and the value quietly disappears.

Publish what you expect

Give integrators the field list, which are required, what the defaults are and what validation applies — most of which the OpenAPI specification carries. An integrator guessing at your expectations will guess wrong, and you will spend the difference in support.

Worked example

A referral endpoint maps a partner's ref_id to the internal reference and dob to date of birth, defaults the source to that partner and the status to "new", and marks the reference and surname required. When the partner later adds a middle name field, nothing breaks — it is simply unmapped and ignored until somebody decides to use it.

Recommendations

• Translate at the boundary — keep your own field names.
• Default the things callers should not know about.
• Never mark a field both required and defaulted.
• Check for a default overwriting when a value goes missing.