Appearance

Dropdown columns ​

Dropdown columns turn a document field into a Select-type field whose options come from entity rows. Both Mapping and Dropdown Definitions can have Dropdown columns; the filtering behavior differs by definition type.

This page covers how Dropdown columns are configured and the per-column settings. The type-level distinction is on Mapping vs Dropdown definitions.

What a Dropdown column does ​

When a definition has a Dropdown column:

  1. The target document field becomes a Select-type field. The reviewer sees a dropdown instead of a text input.
  2. The dropdown's options are sourced from entity rows. The specific column's values from rows (matching the Context, depending on definition type) populate the options.
  3. A value is written to the field. By default, the top matching row's value for the Dropdown column. Optionally overridden by the Defaults tool.

So Dropdown columns simultaneously populate options and write a value. They're a richer behavior than Mapped columns (which only write).

Filtering behavior depends on definition type ​

The single biggest decision: filtered or unfiltered.

Mapping Definition with Dropdown columns ​

Options are unfiltered. The dropdown lists every value of the entity column across the entire entity, regardless of the Context.

Example: a Header Products entity with rows for many customers and vendors. A Mapping Definition's Dropdown column on itemDescription shows every itemDescription value from every row, even if the current document's customer is AC and you'd think only AC's items should appear.

Use for "this dropdown should show all options, not just contextual ones."

Options are context-filtered. The dropdown lists only values from rows that match the Context AND.

Example: same Header Products entity, but as a Dropdown Definition with Context (customerInitials, vendorAccount) and Dropdown column itemDescription. The dropdown narrows to itemDescriptions for the current (customer, vendor) pair — typically a much smaller list.

Use for "this dropdown should narrow based on what else has been selected."

Per-column settings ​

Each Dropdown column has additional configuration:

Document Field ​

The target document field. Becomes a Select-type field once a Dropdown column targets it.

Add "Not set" to dropdown ​

Toggle that controls whether the dropdown includes the explicit —Not set— option. When on, the reviewer can clear the field by picking —Not set—. When off, the reviewer can only pick from the non-empty options.

For mandatory fields, you probably want this off (so the reviewer can't accidentally clear a required field). For optional fields, on is the typical choice.

Default Value ​

The user's override for which value the field gets when this Dropdown column writes. If unset, the top matching row's value is written (same as Mapping). If set, the user-specified value is written instead.

This is the Defaults tool.

Use cases:

  • The top row of a context cluster isn't the "right" default. You explicitly set a different row's value as the default.
  • You want the default to be a literal value not present in any row.
  • You want a stable default that doesn't shift as the entity's row order changes.

The Default Value is most meaningful for Dropdown Definitions. For Mapping Definitions, the unfiltered options make the concept of "default" less crisp.

The write portion of a Dropdown step ​

Even for Dropdown Definitions, the step still writes a value to the document field. The mechanics:

  1. Lookup finds matching rows via Context AND.
  2. Rebuild the dropdown options from the matching rows' Dropdown column values.
  3. Write the field's value: by default, the top matching row's value; if Defaults Tool is set, the user-specified value.
  4. Reset if needed: if the document field's previous value isn't in the new option set, the field is reset (the Select can't hold a value outside its option list).

The empty-cell rule applies to the write portion: if the matched row's cell for the Dropdown column is empty, the document field isn't overwritten. But the option list still rebuilds — empty values are typically excluded from the option list.

When the dropdown clears ​

A common gotcha: a Dropdown step's new option set doesn't include the field's current value. The field is reset.

This is by design — Select-type fields must always hold a value that's in their option list. If the lookup yields zero matching rows, the dropdown becomes empty, and the field clears even if it had a value before.

The implication: changes to the Context cascade-clear dependent Select fields. If you pick a new vendor and the new vendor has no items in the catalog, the itemDescription field clears.

A common partial-cascade pattern

Picking a new vendor whose entity has no rows for the current customer-vendor pair clears all dependent Select fields. The reviewer sees fields that "got blanked" by the cascade.

This is correct behavior — the engine prevented an invalid state. The fix is data: populate the entity for the new combo, then either re-pick the vendor or Reset data on the affected fields.

Multiple Dropdown columns ​

A single definition can have multiple Dropdown columns — each driving a different Select-type document field. All driven by the same Context lookup.

Example: a Dropdown Definition with Context (customerInitials, vendorAccount) and Dropdown columns:

  • itemDescription
  • erpItemCode
  • quantity

The same lookup populates three Select fields. The reviewer picks an itemDescription; the other two narrow accordingly (since they're driven by the same Context).

What's next ​