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, ordetail. Adetailview 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
kindis neitherdetailnorform. - Clicking a table row selects the record and opens the first
detailview 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" }ornotEquals. 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.fieldIdssets the columns (by default, the first six schema fields).props.titleFieldpicks 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.fieldIdslimits the fields;readOnlyfields are never offered.props.mode:create(default) oredit.props.capability: capability required to see it.metric: one figure over the loaded records.props.aggregate:countorsum.props.field: field to sum.props.where:{ "state": ["requested"], "data": { "storeId": ["store-01", "store-02"] } }.props.formatandprops.accent(blue,amber,emerald,rose) adjust the presentation.chart: bars with the number of records per state.props.states(by default, the lifecycle's) andprops.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(defaultsourceRows),props.relationshipTypes,props.recordTypeIds,props.fieldIds,props.sources.execution-state: execution state read from the record.props.stateField(defaultexecutionState) andprops.executionIdField(defaultexecutionId).agent-plan: plan text read fromprops.field(defaultagentPlan).text: fixed text inprops.text, or the value of theprops.fieldfield.
Actions
actions/action: buttons for the selected record's actions.actionIds(orprops.actionIds) limits which ones;props.primaryActionIdmarks the main one. If the action declaresinput, a form opens; if it declaresrequiresConfirmation, confirmation is requested.collection-actions: the same for collection actions. It needs no record.
Files
files: upload area, list, and download.props.slotIdspicks 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).fieldIdsorprops.fieldIdssets the columns.props.filterFieldIdssets the filters (by default, theenumfields).props.pageSize(default 25).dataset-chart: grouped bars.props.datasetId(required),props.labelField(by default, the first key field),props.valueField,props.aggregate:sumto add upvalueField, 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 incustomComponents.
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
formwithprops.capabilityis 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 afterqac.readyand every time the record, the settings, or the language change.recordisnullwhen no record is selected.{ "type": "qac.action.result", "actionId": "approve", "ok": true }: result of the requested action. If it fails,okisfalseanderroris 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
inputyou send. If the action declaresrequiresConfirmation, 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
urlmust behttps. - Check
event.source === window.parentbefore trusting a message. - Do not store secrets in
settings: the configuration reaches the frame and everyone who can open the app.