Skip to content
MoltaroMoltaroMoltaro Docs

Entity list page API

Entity list pages have an optional FilterStatementId. It references an active Statement of the same Entity Definition with ExposeInClient: true. The server requires that Statement to evaluate to true for queries hosted by that page. For the Constructor workflow, see Entity list page filters.

Resolve every /api/workspace/... route below against the installation’s WORKSPACE_API_BASE_URL, never moltaro.com. Use its current Configuration API and Runtime API OpenAPI documents to confirm that the installed version supports FilterStatementId before writing it. Configuration uses the existing Entity Definition management permission gates.

Read and replace page configuration

Section titled “Read and replace page configuration”

Discover the definition’s Statements and use their returned IDs. Do not pass a Statement expression, technical name, or a Security Statement ID as FilterStatementId.

GET /api/workspace/admin/entity-definitions/{entityDefinitionId}/statements
GET /api/workspace/admin/entity-definitions/{entityDefinitionId}/ui/entity-list-page/configuration?surfaceKey={pageKey}
PUT /api/workspace/admin/entity-definitions/{entityDefinitionId}/ui/entity-list-page/configuration?surfaceKey={pageKey}

The PUT replaces the page configuration. Preserve the complete MainTableSelectors from GET when changing only its Statement:

const request = {
  MainTableSelectors: currentPage.Data.MainTableSelectors,
  FilterStatementId: selectedStatement.Id,
};

Send FilterStatementId: null to clear the restriction. Omitting the property also clears it; omission does not preserve a previous value. Read the page back after saving and confirm both the selected Statement and table selectors. The existing configuration DELETE resets the page configuration, including the Statement filter. Cloning a page copies its filter.

Create a separate page with POST /api/workspace/admin/entity-definitions/{entityDefinitionId}/ui/host-surfaces/EntityListPage using a distinct Name and Key. Each page owns its filter independently of the Table Surface it selects. In a Data Explorer menu node, set EntityDefinitionId and EntityListPageSurfaceKey to select the exact page; an omitted page key resolves the current default. Menu replacement must preserve the other nodes and use the latest menu RowVersion.

Query through the page host

Section titled “Query through the page host”
GET /api/workspace/entity/{entityIdOrKey}/ui/entity-list-page?surfaceKey={pageKey}
POST /api/workspace/entity/{entityIdOrKey}/ui/hosted/table/bootstrap?hostSurface=EntityList&surfaceKey={pageKey}
POST /api/workspace/entity/{entityIdOrKey}/ui/hosted/table/tree/children?hostSurface=EntityList&surfaceKey={pageKey}

Use the installed operation’s request schema, including Tree parent and concurrency context for child requests. Keep the same page key on each load. The server resolves the page’s current Statement and intersects it with the effective search and user filter after resolving saved, shared, personal, or global default views. Conceptually:

authorized records AND (page Statement = true) AND (resolved user filter)

The Statement is applied before SQL counts and pagination. Tree queries retain accessible ancestor context for matching descendants. The Statement is not copied into saved-view or personal query state. Manual Order is unavailable for a page with this restriction.

The list-page model exposes FilterStatementId; the hosted table model returns the Statement applied to its query. Data Explorer export combines that applied Statement with its effective export filter, following the latest loaded table query. Reload after a page configuration change before exporting.

Direct instances/query, standalone table queries, reference pickers, and the generic Entity export endpoint do not acquire a page filter automatically. An integration needing that subset must use the page host or explicitly AND the Statement condition into its query. See Statement condition payloads. Page filters are not authorization: root View, record permissions, and field-safe projection remain authoritative on every API route.

Invalid references and portability

Section titled “Invalid references and portability”

An unknown, foreign, deleted, or unexposed Statement is rejected when saving. If a selected Statement later becomes unavailable, hosted queries fail with moltaro.statements.notFound for FilterStatementId; clients must not retry through an unrestricted query to hide the error.

Entity Definition YAML carries FilterStatementId and FilterStatementName on the Entity List Page surface. The latter is the Statement’s technical name, not its display label. Import first resolves an active local ID on that definition, then uses the name when no local ID resolves. A resolved local ID takes precedence over a conflicting name, and its Statement must be exposed; a hidden local Statement is not replaced by an exposed namesake. Unresolved or hidden references fail validation before applying the import. Omitting both properties clears the page filter.

For portable configuration, keep the Statement definition and its technical name with the page in the export. Read the imported page back and verify its local FilterStatementId, table selection, rows, and totals.