Hierarchy Selector

Hierarchy Selector is an input presentation for one scalar Reference. It helps users narrow a large hierarchy through cascading dropdowns, while the record or filter still stores one terminal record ID. It does not add country, region, or other helper fields to the entity schema.

Use Hierarchy Selector when a flat list or picker is technically correct but the hierarchy itself is the most useful way to reach the final value. A separate Reference Eligibility rule may further restrict which nodes can be confirmed.

Source modes

The Entity Definition surface editor offers only hierarchy sources that are valid for the selected Reference field.

Explicit path

ExplicitPath represents a fixed chain such as Country, Region, and City. The editor selects one server-provided relationship path and the runtime renders one dropdown for each level. Choosing an ancestor filters the next level; changing an ancestor removes every descendant selection.

An explicit path can contain up to four Reference segments, producing two to five dropdown levels. Intermediate levels are navigation steps and cannot be confirmed. The terminal level supplies the one ID stored in the Form or filter.

Recursive parent

RecursiveParent follows one direct, indexed, scalar self-Reference such as a Work Item’s Parent. Roots and direct children are loaded as the user opens the chain, so the number of business levels is not configured in advance.

The picker resolves and displays at most 256 nodes in one selected chain. A deeper or cyclic chain is not returned as a partial selection; the user receives an explicit unavailable or depth-limit state instead.

Configure a Form or Table filter

1. Add a direct, single-value Reference item to a Form, or a compatible direct Reference filter item to a Table Surface.
2. Choose Hierarchy as the Reference input type.
3. Choose Explicit path or Recursive parent.
4. Select one of the paths or parent fields supplied by the editor and save the surface.

The hierarchy configuration belongs to that saved surface item. Changing back to List, Long List, Lookup, or another Reference input removes the hierarchy configuration; it does not change the underlying Reference field or its saved values.

Navigation, confirmation, and eligibility

Every option independently reports whether it can be confirmed and whether it has accessible children. This distinction is important when Reference Eligibility is active:

• an explicit-path ancestor is navigation-only because it is not the terminal level;
• an ineligible recursive node cannot be confirmed, but can remain navigable when an accessible eligible descendant may exist;
• an eligible node can be confirmed only after the server re-resolves the full selected chain;
• inaccessible or archived-only branches are not exposed through labels, counts, or promoted descendants.

The Form or filter may also need values from eligibility driver fields. Until that context is complete, the dependent hierarchy control remains disabled and does not query options. Changing a driver clears the dependent terminal value before the hierarchy is queried again.

A Form field-behavior condition may independently need target values projected from the selected Reference. Hierarchy page options remain display-only; the confirmation and restore responses return the authoritative declared values in SelectedValue. Number, DisplayName, and Subtitle are direct members; dynamic scalar fields are under ProjectedValues, and Money keeps its Amount/CurrencyCode shape. Edit materialization may include the actor-readable target values needed to evaluate the saved Form. This projection-only context does not create an eligibility rule or an extra driver control.

The picker is a pre-filter and navigation aid. Entity Instance create and update APIs always enforce the active Reference Eligibility rule again at the authoritative write boundary.

Runtime behavior

• Opening an existing value resolves its readable root-to-terminal chain from the stored terminal ID.
• Search and paging apply to the current level only.
• Confirm emits one record ID; Clear emits null; Cancel leaves the original value unchanged.
• Table filters produce one ordinary Reference condition and preserve the existing saved-view model.
• A now-ineligible but readable saved selection can be displayed so that the user can clear or replace it. A restricted value remains opaque.
• Loading, empty, unavailable, retry, and depth-limit states are announced in the dialog. Closing the dialog returns keyboard focus to the input that opened it.

Limits and troubleshooting

Hierarchy input is supported for a direct scalar Reference in the primary table of an ordinary Data Entity Definition. Part, Association, Projection, collection, child-table, inverse, broken, inaccessible, and target-mismatched paths are rejected. Recursive mode additionally requires an indexed direct self-Reference on the referenced definition.

If the control reports that its configuration is unavailable, reopen the Entity Definition editor and choose one of the current server-provided sources. This can happen after a relationship or parent field is deleted, retargeted, or loses a required index. If the surface changed while a dialog was open, reload the page before trying again.

If a dependent hierarchy remains disabled, complete every Reference Eligibility driver first. If a previously selectable value is rejected during save, reload the current record: another write may have changed the driver, candidate, or rule after the picker was opened.