Appearance

Definitions overview ​

A definition is a lookup specification — "given these document field values, find a matching row in this entity, then do X." Definitions live inside the entity they read from; each entity can host multiple definitions.

This page is the orientation. The sub-pages below cover each piece of a definition's anatomy.

What a definition does ​

In plain terms, a definition says:

  1. Look in this entity.
  2. Match by these columns (the Context columns, each with its own Matching Type).
  3. If a row matches, write these columns' values to these document fields (the Mapped columns), and/or populate these dropdowns (the Dropdown columns).
  4. If no row matches, either fall back to a chosen row or do nothing.

That four-step shape is every definition. The shape is fixed; what changes is the Context, the Mapped columns, the Dropdown columns, and the fallbacks.

Where definitions live ​

Definitions live inside their target entity. To create or edit one:

  1. Settings → Mapping → Entities.
  2. Click into the entity that will hold the definition.
  3. Expand the entity's definition section (typically via a chevron or "Show definitions" button).
  4. Click Add definition or edit an existing one with the pencil icon.

Each entity can host multiple definitions. The Vendors entity might host:

  • Initialize Vendors — used by the project's Initial_Workflow.
  • Vendor Select — used by the user-driven Vendor Select workflow.

Both definitions live inside Vendors. They use the same columns to do different things — one targets extraction-time lookup, the other targets user-driven lookup.

The four pieces of a definition ​

Each definition has four configurable areas plus its identity:

Definition Name           (free text)
Type                      Mapping | Dropdown
Target entity             (locked — the entity the definition lives in)
─────
Context columns           (1–N — the lookup key)
Mapped columns            (0–M — Mapping Definition only; what gets written)
Dropdown columns          (0–K — what populates the dropdown)
Fallback Records          (0–N+1 levels — substitute rows on no-match)

Each piece is its own page in this sub-section.

Mapping vs Dropdown definitions ​

Two types exist:

  • Mapping Definition — when a row matches, writes the row's column values to document fields (the Mapped columns). Can also expose unfiltered dropdowns.
  • Dropdown Definition — when a row matches, rebuilds a document field's dropdown options from the matching rows' Dropdown columns. Also writes the top row's value.

Both types can write to document fields. The real difference is in how dropdowns get populated — unfiltered in Mapping Definitions, context-filtered in Dropdown Definitions.

See Mapping vs Dropdown definitions for the full distinction.

What's in this section ​

A walking example ​

Imagine a Vendors entity in the Acme Invoices project:

Definition Name:   Initialize Vendors
Type:              Mapping Definition
Target entity:     Vendors (200 records)

Context columns:
  1. VendorId         Matching Type: Exact

Mapped columns:
  - vendorName (Metadata)        Transform: No Transform
  - vendorAccount (Metadata)     Transform: No Transform
  - currency (Metadata)          Transform: No Transform

Dropdown columns:  (none)

Fallback Records:  (none configured)

When invoked (typically by Initial_Workflow after extraction):

  1. Read the document's current VendorId (set by extraction).
  2. Look up the Vendors entity for a row where VendorId exactly equals that value.
  3. If a row matches: write vendorName, vendorAccount, currency from that row to the document fields. The empty-cell rule applies — empty entity cells don't overwrite.
  4. If no row matches: silent no-op (no Fallback configured).

This is the simplest definition shape. More complex definitions add more Context columns, switch to Dropdown type for dropdown-driving behavior, or add Fallback Records for graceful degradation.

What's next ​