Field annotations

Your CRM knows a field is called Account_Number and holds text. It does not know that your files call it Cust No, that it is always six digits, or that Mobile is personal data.

Annotations are where you write that down. They are the difference between auto-mapping that guesses and auto-mapping that knows.

The one you will use most has a button

Aliases can be taught from the Map step. When you accept a mapping the matcher would not have guessed, the wizard offers to remember that your files call the field that — and next time the free, deterministic matcher gets it right with no model call and no review.

It is the only write in the product where using the AI makes the AI less necessary, so take the offer when it appears.

The rest of an annotation — descriptions, formats, examples, the personal-data flag — is written through configuration as code or the /orgs/{org}/config/fields routes. For a set that will grow over years, a reviewed file in a repository is the right home.

What an annotation holds

Field	What it does
description	What this field means, in your own words. Shown in the wizard; sent to the AI.
format	The expected shape in plain English — “ISO date”, “E.164 phone”, “two-letter state”.
examples	Real example values.
aliases	Column names your source files use for this field.
pii	Personal data. Masked before any sample leaves the server.
derived	Never mapped from a column — computed, or left alone.
defaultMapping	A mapping applied when nothing else has claimed the field.
excluded	Hidden from mapping for this org.

Aliases are the highest-value entry

An alias says: our files call this field that.

It changes auto-mapping from a guess to a fact. A proposal from an alias is labelled “your org calls it this” in the wizard, and it is applied cleanly — including onto required, unique fields, where a mere name-similarity guess is deliberately held back for a person to confirm.

Add aliases as you meet them. The first time somebody’s export calls the account number Cust No, that is a thirty-second annotation that saves the same manual mapping every month afterwards, for everybody.

Marking personal data

pii: true makes the field’s data masked before it reaches a model, under the allow sample policy.

Worth understanding precisely, because it is a guarantee with a boundary:

At auto-map time, no column has been mapped to any field yet — so the link between a column and an annotated field is made by name. A column that fuzzy-matches the field’s API name, its label or one of its aliases is treated as that field’s data and masked.

That is a good-faith match, not a proof. If you need a guarantee rather than a heuristic, set the org’s sample policy to masked, which masks everything regardless. See Your data and the model.

Annotating pii is still worth doing under any policy: it is documentation of what the field holds, and it is what a future feature will act on.

Descriptions and formats

These reach two audiences.

People, in the wizard, where a field called CF_Ref_2 with a description is usable and one without is a guessing game.

The model, in every AI prompt. A field with a description and a format gets better proposals than one identified only by its API name — which is the cheapest possible improvement to auto-mapping quality.

Derived and excluded

derived: true — the field gets its value from an expression or a workflow, never from a source column. It stays visible but is not offered a column mapping.

excluded: true — the field disappears from the mapping screen for this org. Same effect as excluding it on the module, decided per field.

Doing it in bulk

One field at a time is fine for a correction. For a first pass over a module with 180 fields, write the whole set and replace it in one call — that is what the SDK’s push does, and what the PUT .../fields/{module}/annotations route is for.

Replacing sets the module’s whole annotation set, so send everything you want to keep.

What survives discovery

Annotations do. Discovery updates what the CRM says; annotations are what you say about it, and the two are stored separately for exactly this reason.

A field that is removed from the CRM keeps its annotation, so a project that mapped it can still explain itself.

A worked example

Three fields of one module. Account_Name records what source files call it; Phone is marked as personal data:

fields/accounts.json

[
  {
    "apiName": "Account_Name",
    "description": "The trading name of the organisation.",
    "aliases": ["Company", "Organisation"],
    "examples": ["Widgets Ltd"]
  },
  { "apiName": "Phone", "format": "E.164 phone", "pii": true },
  { "apiName": "Website", "format": "URL" }
]

Keeping them in a repository

Annotations are usually the largest part of a configuration bundle, and the part most worth reviewing — an alias is a claim about how your organisation’s data is shaped.

See Configuration as code.