Manual Order

Manual Order gives one record type a durable relative order. The same order is used by every supporting Table Surface: a Flat list reads the global sequence, while Parent Tree View reads the same ranks within each visible sibling set. Manual Order is separate from board-item ordering and does not expose a rank field to users or API clients.

Enable the capability

An Owner or Admin enables Manual Order from the Entity Definition. Existing active records are assigned one canonical order during activation. The dialog can also recommend making Manual Order the Entity Definition default sort. That follow-up choice is optional and is saved separately; declining it still leaves the capability available to individual Table Surfaces.

Activation is supported only for ordinary data Entity Definitions. Projection, Association, Part, and other incompatible shapes are rejected without leaving partial metadata or storage. Package-owned declarations remain package-owned; administrators cannot adopt or remove them through the ordinary dynamic action.

Configure a Table Surface

When the capability is active, the Table Surface sorting editor offers Manual order as a typed sort item. It may be the default only as the sole ascending criterion. Ordinary field and system-field sort items stay available. Choosing a different effective sort does not change stored Manual Order ranks; it enters Field Sort mode and disables movement until Manual Order is selected again.

For Parent Tree View, the sibling-sort selector can explicitly choose an ordinary field or Manual Order. An explicit Tree selector wins over the entity default. With no Tree selector, the entity Manual Order default applies when configured; otherwise the existing Display name ascending fallback applies.

Entity Definition YAML version 8 carries the capability and typed Special: ManualOrder selectors. The platform-owned rank field, rank values, indexes, and provenance are never exported. Versions 1 through 7 are rejected by the current importer.

Move records

On a supporting surface, pointer users can use the drag handle. Keyboard and mobile users use the same Move… row action and dialog. Both controls call the same server validation and move operation.

Flat lists can place a record before or after another record in the global order. Tree surfaces additionally support sibling placement, moving inside a parent as its last child, and moving to the start or end of the visible root set. Parent and rank changes commit atomically. A drop that already represents the authoritative position completes quietly without a write or success notification.

Movement is available only for an active, unfiltered projection using sole ascending Manual Order and for rows the current user may update. Search, filters, another sort, Archived/All mode, synthetic rows, hierarchy issues, or row-level access can leave the controls visible but disabled with a safe reason. The UI never reveals a hidden parent, inaccessible target, or raw rank.

Reference Eligibility, Reference validity, hierarchy cycle protection, access, business invariants, mutation effects, and package concurrency checks run for both validation and commit. A visually plausible target can therefore be rejected. The client restores the authoritative projection and does not retain an optimistic move.

Refresh, history, and recovery

A committed move publishes a non-sensitive projection hint. Open Data Explorer, picker/Lookup, Details, Drawer, and related-table hosts silently requery their loaded page or Tree branches. Duplicate hints are coalesced, and reconnect performs an authoritative recovery query. Selection, expansion, focus, scroll, query state, and the last committed projection are retained where still valid; background refresh does not show the page loader or a success toast.

When Audit Trail is enabled, history shows one semantic Manual Order activity per committed move. Reparenting also shows the ordinary Parent before/after change. No-op, denied, cancelled, and rolled-back moves create no activity, and history never renders rank values.

Remove the capability

Removal is dependency-aware and is never an automatic cascade. Preview the dependency graph first. An Owner or Admin may explicitly clear only matching per-user Manual Order sort overrides, after confirmation, and then retry the separate capability removal. Surface defaults, saved views, query shares, package declarations, and other surviving dependencies must be changed or removed through their owning workflow.

Package reapply uses the same ownership-aware preview/execution contract. A retained declaration is idempotent and preserves exact order. Declaration or whole-Entity removal may delete dependencies already inside the confirmed package plan, but any dependency that would survive blocks the operation.

Record creation and imports

Each successful ordinary create appends independently at the active tail. Partial-success imports allocate order only for rows that actually commit, and concurrent creates may interleave. Create/import requests do not accept a rank or position. To place a new record elsewhere, commit the create first and issue a separate move; the two operations are not one atomic positioned-create transaction.

For Tree configuration and daily interaction, see Using Tree View. For the query target shape, see Table filters and sorting.