Operational apps
Operational apps: package reference
The package document field by field: record types, actions, permissions, files, datasets, flows, views, status, versions, and validation errors.
Updated: 2026-11-17
In this guide
The document
A package is a JSON object with five keys:
schema: always"qac.operational-app-package".packageId: identifier of the package.version: positive integer. It is your version number for the package.recordTypes: list of record types the app needs.app: the app definition.
Identifiers (packageId, appId, recordTypeId, actionId, flowId, slotId, datasetId, componentId, roles, and field names) start with a letter and use letters, numbers, dot, underscore, or hyphen, up to 80 characters.
The quickstart has a complete package. The fragments on this page build on it.
Record types
Each item in recordTypes:
recordTypeId,name: required.description,translations: optional.status:published(default),draft, ordeprecated. Only a published type accepts new records and can be used by an app.schema.fields: the fields, by name.schema.additionalProperties: iftrue, undeclared fields are accepted. By default they are rejected.lifecycle: optional.
Fields
Each field declares type and, optionally, label, required, readOnly, format, and translations.
string: text.number: number.money: number that represents an amount.boolean: true or false.datetime: text with date and time.enum: text withinenumValues.relation: identifier of another record. Declarerelation.recordTypeIdandrelation.cardinality(oneormany; withmanythe value is a list).attachment: text that references an attachment.array: list.json: free-form object.
format adjusts the presentation: text, currency, percentage, date, datetime, or email.
readOnly marks a field people do not edit. It does not appear in forms and the API rejects a direct change. Actions (with set) and flows can write it.
Lifecycle
initialState: state the record is born in.states: every state.transitions: for each state, the list of states it can move to.
A transition that is not declared is rejected, whether it comes from an action, a flow, or an edit. A type without lifecycle does not restrict the state.
The app
appId,name: required.description,translations,icon: optional.recordTypeIds: the record types the app governs. They must be published.status:published(default),draft, orsuspended.flows,actions,accessControl,files,datasets,settings,modules,views,customComponents: the sections that follow.
translations exists on almost every piece. The keys are languages and each one can carry name, label, title, description, states, and enumValues:
{
"translations": {
"es": { "name": "Devolución", "states": { "requested": "Solicitada", "refunded": "Reembolsada" } }
}
}
Flows
Each item in flows:
flowId,label: identifier and visible name.workflowType+taskQueue: the workflow and the queue of its worker. Installation registers an automation and fills inautomationId.automationId: instead of the above, an existing automation of your organization.input: fixed object sent to the flow on every start.
The details are in Flows.
Actions
{
"flows": [
{ "flowId": "import-returns", "label": "Import returns", "workflowType": "ReturnsImportWorkflow", "taskQueue": "automation-processes" }
],
"actions": [
{
"actionId": "register-refund",
"label": "Register manual refund",
"description": "For refunds issued outside the flow.",
"target": "record",
"recordTypeId": "returns.request",
"capability": "returns.decide",
"allowedStates": ["approved"],
"targetState": "refunded",
"input": { "reference": { "type": "string", "label": "Reference", "required": true } },
"set": { "refundReference": { "input": "reference" } },
"reserve": { "key": "refund-reference:{input.reference}" },
"requiresConfirmation": true
},
{
"actionId": "import",
"label": "Import file",
"target": "collection",
"capability": "returns.create",
"flowId": "import-returns"
}
]
}
actionId,label,description: identifier and button texts.target:recordacts on one record;collectionacts on the app (imports, runs).recordTypeId: required on record actions. It must be inrecordTypeIds.capability: capability the user needs. It must belong to some role. Withoutcapability, being able to open the app is enough.allowedStates: states in which the action is available. Without this list, it is available in all of them.targetState: state the record moves to. It must be an allowed transition from the current state.input: fields asked of the user, with the same shape as the fields of a record type. Undeclared fields are rejected.set: data the action writes to the record. Each field takes its value from a source:{ "input": "reference" }: a field ofinput. If it is optional and not sent, the record field is left untouched.{ "actor": "id" }or{ "actor": "email" }: whoever runs the action.{ "now": true }: the date and time of the run.{ "value": "manual" }: a constant (text, number, boolean, ornull).
reserve: uniqueness guard.keyis a template with{input.<field>},{record.<field>}, or{recordId}. The resulting key can belong to one record only: if another one already holds it, the action fails with 409.releaseOnStateslists the states that release the key.flowId: flow that starts when the action is applied.requiresConfirmation: the dashboard asks for confirmation before sending.
On a collection action only capability, input, flowId, and requiresConfirmation apply. The request body also accepts fileIds (up to 50 confirmed files of the app) and idempotencyKey.
Permissions
accessControl declares who opens the app and what they can do:
visibility:organizationorassigned.roles: for each role,labelandcapabilities.assignments: who receives each role. Each assignment hasuserIdororgRole(exactly one),role, and, optionally,scope.scopeFields: for each scope dimension, the record field that carries it.scopeValues: optional catalog of values per dimension (value,label,active). It is stored with the app for your flows and screens to read; Quantum does not validate against it.
The full model, with an example, is in Permissions and environments.
Files
{
"files": [
{
"slotId": "returns-file",
"label": "Returns file",
"target": "app",
"contentTypes": ["text/csv"],
"maxBytes": 5242880,
"capability": "returns.create",
"flowId": "import-returns"
}
]
}
slotId,label: identifier and visible name.target:recordattaches to a record;appattaches to the app.recordTypeId: required withtarget: "record".contentTypes: accepted types. It takes an exact type (application/pdf), a family (image/*), or any (*/*).maxBytes: maximum size.multiple: the screen lets the user pick several files at once.capability: capability to upload, list, and download. On a record slot the record's scope applies as well.flowId: flow that starts when an upload is confirmed.
The upload has three steps, which the dashboard does for you: request the upload with name, type, size, and SHA-256 checksum; send the file to the signed URL; and confirm. Quantum compares size and checksum before accepting the file as valid.
Datasets
{
"datasets": [
{
"datasetId": "refunds-by-day",
"label": "Refunds by day",
"fields": {
"day": { "type": "string", "label": "Day" },
"storeId": { "type": "string", "label": "Store" },
"refunds": { "type": "number", "label": "Refunds" },
"amount": { "type": "money", "label": "Amount", "format": "currency" }
},
"key": ["day", "storeId"]
}
]
}
fields: fields of each row, with the same shape as those of a record type.key: fields that identify a row. Writing another row with the same key replaces the previous one.
Flows write the rows. Screens read them with GET /operational-apps/{appId}/datasets/{datasetId}, which accepts limit (100 by default, 1000 at most), cursor, and equality filters filter.<field>=<value> on text, number, and boolean fields.
Settings
settings is a free-form object with the app's configuration in an organization: stores, tolerances, parameters. Flows receive it in the envelope and custom components in their context. Do not store secrets: everyone who can open the app reads it.
Views, modules, and custom components
views: the screens. See Views.modules: optional grouping of views, withmoduleId,name,description, andviewIds. The standard screen lists the views directly.customComponents: pages of your own shown inside a view. Each one declarescomponentId,label,url(https), and an optionalheight.
App status
draft: only those who manage definitions (adminandeditorroles) see and run it. It does not appear in the app chooser; it opens by direct link.published: available according to its permissions.suspended: nobody can run actions, upload files, or read datasets. The app and the records of its types stop being visible to those who do not manage definitions, and pending flows do not start.
status is the only switch. There is no other activation step.
Versions
- The package
versionis yours: raise it when you publish changes. It is recorded on the installed app. - Installation assigns the internal versions. A record type whose content changed gets a new version; an identical one stays as it is. The same goes for the app.
- Existing records keep the schema version they were born with and are validated against it.
- Installing an identical document writes nothing.
Install and export
POST /operational-apps/installwith{ "package": { ... }, "overrides": { ... } }installs or updates. It requires theadminoreditorrole.GET /operational-apps/{appId}/packagereturns{ "package": { ... } }with the installed app as a package document.
overrides adjusts the package for one specific installation without editing it. It only accepts:
settings: deep-merged overapp.settings.accessControl.assignments: replaces the assignments.accessControl.scopeValues: replaces the value catalog.
Validation errors
Installation answers 400 with message and an errors list. Nothing is written if there is at least one error. App errors carry the app: prefix and record type errors recordTypes.<id>:.
From the document:
schema must be 'qac.operational-app-package'.packageId is required and must use letters, numbers, dot, underscore or hyphen.version must be a positive integer.overrides: 'views' cannot be overridden.
From the record types:
recordTypes.returns.request: name is required.recordTypes.returns.request: Field 'amount' has an invalid definition or unknown type.recordTypes.returns.request: Lifecycle transition 'approved' -> 'paid' targets an undeclared state.
From the app:
app: recordTypeIds: 'returns.request' is not a published record type.app: flows: 'issue-refund' needs automationId or workflowType.app: flows: 'issue-refund' needs taskQueue with workflowType.app: actions.approve: record actions need recordTypeId.app: actions.approve: 'returns.request' is not in recordTypeIds.app: actions.approve: state 'aproved' is not in the lifecycle of 'returns.request'.app: actions.approve: set writes unknown field 'decidedOn'.app: actions.approve: set reads undeclared input 'note'.app: actions.approve: flow 'issue-refund' is not declared.app: actions.approve: capability 'returns.decide' is granted to no role.app: actions.approve: capability 'returns.decide' requires accessControl.app: accessControl: each assignment needs exactly one of userId or orgRole.app: accessControl: assignment uses unknown role 'manager'.app: accessControl: scope 'store' has no scopeFields entry.app: files.receipt: contentTypes is required.app: datasets.refunds-by-day: key field 'day' is not declared.app: customComponents.refund-calculator: url must be https.app: views.returns-detail: custom component 'refund-calculator' is not declared.
At run time, the most common errors are:
- 400: the action data does not satisfy
input, or the action would produce an invalid record. - 403: the capability is missing, or the record is outside the user's scope.
- 409: the record changed (
expectedVersion), the action does not apply in the current state, the transition is not allowed, thereservekey already belongs to another record, or the app is suspended.