Operational apps

Operational apps: views

How to compose the screens of an operational app: views, sections, the component catalog with its props, and custom components.

Updated: 2026-11-17

In this guide

How a screen is put together

An app has a list of views. Each view has sections and each section has components. You do not write interface code: you pick components from the catalog and configure them with props.

{
  "viewId": "returns-detail",
  "name": "Return",
  "kind": "detail",
  "recordTypeId": "returns.request",
  "version": 1,
  "status": "published",
  "layout": {
    "sections": [
      {
        "id": "summary",
        "title": "Summary",
        "columns": 1,
        "components": [
          { "id": "fields", "type": "record-detail", "fieldIds": ["orderNumber", "storeId", "amount", "reason"] },
          { "id": "decide", "type": "actions", "actionIds": ["approve", "reject"], "props": { "primaryActionId": "approve" } }
        ]
      },
      {
        "id": "evidence",
        "title": "Receipts",
        "components": [{ "id": "receipts", "type": "files", "props": { "slotIds": ["receipt"] } }]
      }
    ]
  }
}

Views

  • viewId, name: identifier and title. The dashboard lists the app's views in the order you declare them.
  • kind: table, queue, overview, automation, form, or detail. A detail view needs a selected record; the others work on the list.
  • recordTypeId: the record type the view loads. The dashboard fetches the records of that type the user can read.
  • actionIds: actions that apply to the view's components that name none of their own.
  • context.createCapability: capability required to see the create-record button. If you do not declare it, everyone who can open the app sees it.

Two behaviors worth knowing:

  • The app opens on the first view whose kind is neither detail nor form.
  • Clicking a table row selects the record and opens the first detail view of the same record type.

Each view loads up to 100 records, filtered by the search box. Record metrics and charts are computed over those loaded records. For totals over larger volumes, use a dataset.

Sections

  • id, title: identifier and heading.
  • columns: 1 to 4. Components are laid out on that grid.
  • components: the list of components.

What every component accepts

  • id: unique within the view.
  • type: the catalog component.
  • title: title, when the component shows one.
  • fieldIds: fields the component uses, in order.
  • actionIds: actions it offers.
  • props: the component's own configuration.
  • visibleWhen: { "field": "reason", "equals": "defective" } or notEquals. It is evaluated against the selected record's data. With no record selected, the component is shown.

A type that does not exist does not break the screen: a note is shown in its place.

Component catalog

Records

  • table / queue: table of records with their state. fieldIds sets the columns (by default, the first six schema fields). props.titleField picks the field that titles each row.
  • record-detail / status: fields of the selected record, with the origin of each value when available. fieldIds (by default, the first ten).
  • form: form generated from the schema. fieldIds limits the fields; readOnly fields are never offered. props.mode: create (default) or edit. props.capability: capability required to see it.
  • metric: one figure over the loaded records. props.aggregate: count or sum. props.field: field to sum. props.where: { "state": ["requested"], "data": { "storeId": ["store-01", "store-02"] } }. props.format and props.accent (blue, amber, emerald, rose) adjust the presentation.
  • chart: bars with the number of records per state. props.states (by default, the lifecycle's) and props.limit (default 3).
  • activity: history of the selected record.
  • relationship: relationships between the selected record and other records.
  • evidence / artifacts: evidence linked to the selected record.
  • source-rows: source rows of the record. props.inlineField (default sourceRows), props.relationshipTypes, props.recordTypeIds, props.fieldIds, props.sources.
  • execution-state: execution state read from the record. props.stateField (default executionState) and props.executionIdField (default executionId).
  • agent-plan: plan text read from props.field (default agentPlan).
  • text: fixed text in props.text, or the value of the props.field field.

Actions

  • actions / action: buttons for the selected record's actions. actionIds (or props.actionIds) limits which ones; props.primaryActionId marks the main one. If the action declares input, a form opens; if it declares requiresConfirmation, confirmation is requested.
  • collection-actions: the same for collection actions. It needs no record.

Files

  • files: upload area, list, and download. props.slotIds picks the slots. Without that prop it shows the app's slots and, with a record open, the slots of its type.

Datasets

  • dataset-table: paginated table. props.datasetId (required). fieldIds or props.fieldIds sets the columns. props.filterFieldIds sets the filters (by default, the enum fields). props.pageSize (default 25).
  • dataset-chart: grouped bars. props.datasetId (required), props.labelField (by default, the first key field), props.valueField, props.aggregate: sum to add up valueField, or it counts rows if you leave it out. props.limit (default 12). It reads up to 500 rows.

Custom

  • custom:<componentId>: a component of your own, declared in customComponents.

Visibility by grant

The dashboard hides what the user cannot do and the server checks it again on every request:

  • An action only appears if the server returned it as available for that record: the user holds the capability, the record is in their scope, and the state allows it.
  • A file slot is not offered when its capability is missing.
  • A form with props.capability is not shown when that capability is missing.
  • The create-record button honors context.createCapability.

There is no generic capability prop for any component. To hide a whole section from a role, rely on these points or split the content into another app.

Custom components

When the catalog is not enough, you can show a page of your own inside a view.

{
  "customComponents": [
    { "componentId": "refund-calculator", "label": "Refund calculator", "url": "https://apps.example.com/refund-calculator", "height": 420 }
  ]
}

Then you use it as { "id": "calculator", "type": "custom:refund-calculator" }.

You host and maintain the page. Quantum loads it in an isolated frame and passes it context through messages.

The protocol

Your page sends to the parent window:

  • { "type": "qac.ready" }: ready to receive context. Without this message nothing arrives.
  • { "type": "qac.resize", "height": 520 }: asks for a height in pixels, between 80 and 4000.
  • { "type": "qac.action", "actionId": "approve", "input": { "note": "..." } }: asks to run an app action.

Your page receives:

  • { "type": "qac.context", "app": { "appId": "...", "settings": {} }, "record": {}, "locale": "en" }: arrives after qac.ready and every time the record, the settings, or the language change. record is null when no record is selected.
  • { "type": "qac.action.result", "actionId": "approve", "ok": true }: result of the requested action. If it fails, ok is false and error is included.
<script>
  window.addEventListener("message", (event) => {
    if (event.source !== window.parent) return;
    const message = event.data || {};
    if (message.type === "qac.context") {
      render(message.record, message.app.settings, message.locale);
      window.parent.postMessage({ type: "qac.resize", height: document.body.scrollHeight }, "*");
    }
    if (message.type === "qac.action.result") {
      showResult(message.ok, message.error);
    }
  });

  function approve(note) {
    window.parent.postMessage({ type: "qac.action", actionId: "approve", input: { note } }, "*");
  }

  window.parent.postMessage({ type: "qac.ready" }, "*");
</script>

What the frame can and cannot do

It can:

  • Read the selected record, the app settings, and the language.
  • Ask for an action declared in the app. It runs with the user's identity and permissions, with the input you send. If the action declares requiresConfirmation, the user confirms first.
  • Run scripts and submit forms inside its own frame.

It cannot:

  • Receive the session token or call the Quantum API as the user.
  • Read or modify the dashboard page.
  • Open pop-ups or navigate the main window.
  • Use cookies or local storage of its own domain: the frame is loaded without an origin of its own.
  • Run anything other than a declared action. Permissions are checked on the server.

Three rules for your page:

  • The url must be https.
  • Check event.source === window.parent before trusting a message.
  • Do not store secrets in settings: the configuration reaches the frame and everyone who can open the app.