Operational apps

Operational apps: quickstart

Build a returns app end to end: the package, the installation, the screen in the dashboard, an action, and the flow that issues the refund.

Updated: 2026-11-17

In this guide

What you will build

A returns app with:

  • One record type, returns.request, with four states.
  • Two actions: approve and reject.
  • One slot to attach the receipt.
  • One flow that issues the refund when someone approves.
  • Two screens: the request queue and the detail.

You need:

  • A user with the admin or editor role in an organization that has Operational apps enabled.
  • The Quantum API URL in QAC_API and your session token in QAC_TOKEN.

1. Write the package

A package is a single JSON document with the record types and the app. Save it as returns.package.json.

{
  "schema": "qac.operational-app-package",
  "packageId": "returns",
  "version": 1,
  "recordTypes": [
    {
      "recordTypeId": "returns.request",
      "name": "Return",
      "translations": { "es": { "name": "Devolución" } },
      "schema": {
        "fields": {
          "orderNumber": { "type": "string", "label": "Order", "required": true },
          "storeId": { "type": "string", "label": "Store", "required": true },
          "amount": { "type": "money", "label": "Amount", "required": true, "format": "currency" },
          "reason": { "type": "enum", "label": "Reason", "enumValues": ["defective", "wrong_item", "other"] },
          "decisionNote": { "type": "string", "label": "Decision note", "readOnly": true },
          "decidedBy": { "type": "string", "label": "Decided by", "readOnly": true },
          "decidedAt": { "type": "datetime", "label": "Decision date", "readOnly": true },
          "refundReference": { "type": "string", "label": "Refund reference", "readOnly": true }
        }
      },
      "lifecycle": {
        "initialState": "requested",
        "states": ["requested", "approved", "rejected", "refunded"],
        "transitions": {
          "requested": ["approved", "rejected"],
          "approved": ["refunded"]
        }
      }
    }
  ],
  "app": {
    "appId": "returns",
    "name": "Returns",
    "description": "Return requests, approval, and refund.",
    "translations": { "es": { "name": "Devoluciones", "description": "Solicitudes de devolución, aprobación y reembolso." } },
    "icon": "layers",
    "recordTypeIds": ["returns.request"],
    "flows": [
      {
        "flowId": "issue-refund",
        "label": "Issue refund",
        "workflowType": "ReturnsRefundWorkflow",
        "taskQueue": "automation-processes"
      }
    ],
    "actions": [
      {
        "actionId": "approve",
        "label": "Approve",
        "target": "record",
        "recordTypeId": "returns.request",
        "capability": "returns.decide",
        "allowedStates": ["requested"],
        "targetState": "approved",
        "input": { "note": { "type": "string", "label": "Note" } },
        "set": {
          "decisionNote": { "input": "note" },
          "decidedBy": { "actor": "email" },
          "decidedAt": { "now": true }
        },
        "flowId": "issue-refund",
        "requiresConfirmation": true
      },
      {
        "actionId": "reject",
        "label": "Reject",
        "target": "record",
        "recordTypeId": "returns.request",
        "capability": "returns.decide",
        "allowedStates": ["requested"],
        "targetState": "rejected",
        "input": { "note": { "type": "string", "label": "Rejection reason", "required": true } },
        "set": {
          "decisionNote": { "input": "note" },
          "decidedBy": { "actor": "email" },
          "decidedAt": { "now": true }
        }
      }
    ],
    "accessControl": {
      "visibility": "organization",
      "roles": {
        "agent": { "label": "Agent", "capabilities": ["returns.read", "returns.create", "returns.attach"] },
        "supervisor": { "label": "Supervisor", "capabilities": ["returns.read", "returns.create", "returns.attach", "returns.decide"] }
      },
      "assignments": [
        { "orgRole": "member", "role": "agent" },
        { "orgRole": "editor", "role": "supervisor" }
      ]
    },
    "files": [
      {
        "slotId": "receipt",
        "label": "Receipt",
        "target": "record",
        "recordTypeId": "returns.request",
        "contentTypes": ["application/pdf", "image/*"],
        "maxBytes": 10485760,
        "multiple": true,
        "capability": "returns.attach"
      }
    ],
    "datasets": [],
    "settings": { "refundProvider": "sandbox" },
    "views": [
      {
        "viewId": "returns-queue",
        "name": "Requests",
        "kind": "queue",
        "recordTypeId": "returns.request",
        "version": 1,
        "status": "published",
        "context": { "createCapability": "returns.create" },
        "layout": {
          "sections": [
            {
              "id": "totals",
              "title": "Summary",
              "columns": 2,
              "components": [
                { "id": "pending", "type": "metric", "title": "To decide", "props": { "aggregate": "count", "where": { "state": ["requested"] }, "accent": "amber" } },
                { "id": "refunded", "type": "metric", "title": "Refunded", "props": { "aggregate": "sum", "field": "amount", "where": { "state": ["refunded"] } } }
              ]
            },
            {
              "id": "list",
              "title": "Requests",
              "components": [
                { "id": "table", "type": "table", "fieldIds": ["orderNumber", "storeId", "amount", "reason"], "props": { "titleField": "orderNumber" } }
              ]
            }
          ]
        }
      },
      {
        "viewId": "returns-detail",
        "name": "Return",
        "kind": "detail",
        "recordTypeId": "returns.request",
        "version": 1,
        "status": "published",
        "layout": {
          "sections": [
            {
              "id": "summary",
              "title": "Request",
              "components": [
                { "id": "fields", "type": "record-detail", "fieldIds": ["orderNumber", "storeId", "amount", "reason", "decisionNote", "decidedBy", "refundReference"] },
                { "id": "decide", "type": "actions", "actionIds": ["approve", "reject"], "props": { "primaryActionId": "approve" } }
              ]
            },
            {
              "id": "receipts",
              "title": "Receipts",
              "components": [{ "id": "files", "type": "files", "props": { "slotIds": ["receipt"] } }]
            },
            {
              "id": "history",
              "title": "History",
              "components": [{ "id": "activity", "type": "activity" }]
            }
          ]
        }
      }
    ]
  }
}

What this document says:

  • A return is born in requested. From there it can only move to approved or rejected, and from approved to refunded.
  • Approving and rejecting require the returns.decide capability, which only the supervisor role holds.
  • Approving writes who decided and when, moves the record to approved, and starts the issue-refund flow.
  • readOnly fields do not appear in forms. Actions and flows write them.

2. Write the flow

The flow receives the approved record, issues the refund, and leaves the record in refunded.

from datetime import timedelta

from temporalio import activity, workflow

with workflow.unsafe.imports_passed_through():
    from qac.operational import OperationalFlowInput, SystemOfRecordsClient


@activity.defn(name="issue_refund")
def issue_refund(flow_input: dict) -> dict:
    envelope = OperationalFlowInput.parse(flow_input)
    client = SystemOfRecordsClient.from_flow_input(envelope)
    # Call your payment provider here. Use outbox_id as the idempotency key.
    reference = "RF-" + envelope.outbox_id[:8]
    client.transition(
        envelope.record["recordId"],
        state="refunded",
        data={"refundReference": reference},
        reason="Refund issued",
    )
    client.report_flow_result(envelope.outbox_id, "completed", output={"refundReference": reference})
    return {"refundReference": reference}


@workflow.defn(name="ReturnsRefundWorkflow")
class ReturnsRefundWorkflow:
    @workflow.run
    async def run(self, flow_input: dict) -> dict:
        return await workflow.execute_activity(
            issue_refund, flow_input, start_to_close_timeout=timedelta(minutes=5)
        )

The workflow name must match workflowType, and the workflow must be registered on the worker that serves the queue declared in taskQueue. Flows has the full version, with failure handling.

3. Install the package

jq -n --slurpfile pkg returns.package.json '{package: $pkg[0]}' |
  curl -X POST "$QAC_API/operational-apps/install" \
    -H "Authorization: Bearer $QAC_TOKEN" \
    -H "Content-Type: application/json" \
    -d @-

The installation validates the whole document before writing anything. If everything is fine, it creates the record type, registers the flow as an automation of your organization, and stores the app. The response, abridged:

{
  "packageId": "returns",
  "version": 1,
  "recordTypes": [{ "recordTypeId": "returns.request", "version": 1, "change": "created" }],
  "automations": [{ "flowId": "issue-refund", "automationId": "0f6c2b1a-7d3e-4a58-9b21-5c4e8d7f6a90", "change": "created" }],
  "appChange": "created",
  "app": { "appId": "returns", "version": 1, "status": "published" },
  "environment": "prod"
}

If something is wrong, you get a 400 with every problem at once:

{
  "message": "Invalid operational app package: app: actions.approve: state 'aproved' is not in the lifecycle of 'returns.request'.",
  "errors": ["app: actions.approve: state 'aproved' is not in the lifecycle of 'returns.request'."]
}

Installing the same document twice changes nothing: every part comes back as unchanged.

4. Open the app in the dashboard

Go to Operational apps in the dashboard and pick Returns, or open /en/automation-center/dashboard/operational-apps?appId=returns directly.

You will see the Requests view with the two metrics and the empty table. Click New record, fill in order, store, amount, and reason, and save. The record is born in requested and the dashboard opens its detail.

You can also create it through the API:

curl -X POST "$QAC_API/operational-records" \
  -H "Authorization: Bearer $QAC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"recordTypeId": "returns.request", "data": {"orderNumber": "A-1042", "storeId": "store-01", "amount": 129900, "reason": "defective"}}'

5. Run an action

In the detail, a supervisor sees the Approve and Reject buttons. On Approve, the dashboard asks for the note, then for confirmation, and sends the action.

The same action through the API:

curl -X POST "$QAC_API/operational-records/$RECORD_ID/actions" \
  -H "Authorization: Bearer $QAC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"actionId": "approve", "appId": "returns", "input": {"note": "Defective product confirmed"}, "expectedVersion": 1}'

The response, abridged, carries the record already in approved and the flow start:

{
  "record": {
    "recordId": "7c1d6a52-1f0e-4b7a-9a43-2f8f0f3f9b10",
    "recordTypeId": "returns.request",
    "state": "approved",
    "version": 2,
    "data": {
      "orderNumber": "A-1042",
      "storeId": "store-01",
      "amount": 129900,
      "reason": "defective",
      "decisionNote": "Defective product confirmed",
      "decidedBy": "ana@example.com",
      "decidedAt": "2026-11-17T15:04:05.120Z"
    },
    "availableActions": []
  },
  "flow": { "outboxId": "3b1f0c9e-52a7-4d1e-9c55-0a6d7e21f4b8" },
  "environment": "prod"
}

expectedVersion protects against simultaneous changes: if someone else modified the record, you get a 409 and must reload. availableActions is empty because no action applies in approved.

6. Watch the flow run

  • In the detail, the Running notice appears next to the actions.
  • In Executions, the run "Returns - Issue refund" appears, started by the user who approved.
  • When the flow finishes, the record moves to refunded, the refund reference is filled in, and the history shows the three changes: creation, approval, and refund.

To query the start through the API:

curl "$QAC_API/operational-apps/returns/flows/3b1f0c9e-52a7-4d1e-9c55-0a6d7e21f4b8" \
  -H "Authorization: Bearer $QAC_TOKEN"

What is next