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, or deprecated. Only a published type accepts new records and can be used by an app.
  • schema.fields: the fields, by name.
  • schema.additionalProperties: if true, 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 within enumValues.
  • relation: identifier of another record. Declare relation.recordTypeId and relation.cardinality (one or many; with many the 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, or suspended.
  • 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 in automationId.
  • 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: record acts on one record; collection acts on the app (imports, runs).
  • recordTypeId: required on record actions. It must be in recordTypeIds.
  • capability: capability the user needs. It must belong to some role. Without capability, 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 of input. 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, or null).
  • reserve: uniqueness guard. key is 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. releaseOnStates lists 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: organization or assigned.
  • roles: for each role, label and capabilities.
  • assignments: who receives each role. Each assignment has userId or orgRole (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: record attaches to a record; app attaches to the app.
  • recordTypeId: required with target: "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, with moduleId, name, description, and viewIds. The standard screen lists the views directly.
  • customComponents: pages of your own shown inside a view. Each one declares componentId, label, url (https), and an optional height.

App status

  • draft: only those who manage definitions (admin and editor roles) 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 version is 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/install with { "package": { ... }, "overrides": { ... } } installs or updates. It requires the admin or editor role.
  • GET /operational-apps/{appId}/package returns { "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 over app.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, the reserve key already belongs to another record, or the app is suspended.