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
adminoreditorrole in an organization that has Operational apps enabled. - The Quantum API URL in
QAC_APIand your session token inQAC_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 toapprovedorrejected, and fromapprovedtorefunded. - Approving and rejecting require the
returns.decidecapability, which only thesupervisorrole holds. - Approving writes who decided and when, moves the record to
approved, and starts theissue-refundflow. readOnlyfields 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
- Package reference: every field and the validation errors.
- Permissions and environments: limit each role to its stores and take the app from QA to production.
- Views: the full component catalog.