Skip to main content

Writing and completing work orders

Writes follow the same rules as the kommuns app and have the same effects: notifications to the people concerned, the work order's history, the organization's Log Records (as <integration name> (API)). Send an Idempotency-Key with every write you may retry (conventions). Every write answers the record as the read endpoints show it.

Feedback — issues:write​

POST /issues
{"inventory_id": "…", "subject": "Chiller 2: high temperature", "description": "12.4 °C for 15 min", "external_id": "BMS-ALARM-8841"}

Needs the node's "feedback: create" permission. A building automation system typically sends one per alarm with the alarm's number as external_id (a second one with the same number answers 409).

Work orders — work_orders:write​

Create

POST /work-orders
{"inventory_id": "…", "title": "Quarterly filter change", "description": "From SAP PM order 4711",
 "priority": "medium", "target_date": "2026-10-20T09:00:00Z", "form_id": "…",
 "assignees": ["…"], "consultants": [], "external_id": "SAP-4711"}

Needs the node's "work orders: create" permission and a plan that allows manual work orders. priority is none, low, medium or high; form_id one of GET /forms. Assignees must be connected to the node: identities assigned to it or above it (people, teams, organizations, integrations — see GET /people, /teams), members of such a team, or the integration itself. Without assignees the work order goes to the node's inventory managers, as in the app.

Change — PATCH /work-orders/{id} with any of title, description, priority, target_date, external_id; only the fields you send change. Allowed while the work is open, in progress or back from the consultant, with the node's "work orders: update" permission.

Assign — POST /work-orders/{id}/assignees {"assignees": [...], "consultants": [...]} (the "forward" permission); DELETE /work-orders/{id}/assignees/{identity_id} (a work order keeps at least one worker). A service company forwarding its customer's work order assigns its own people.

Cancel — POST /work-orders/{id}/cancel {"reason": "…"} (the "delete" permission, while in process).

Answering and completing​

POST /work-orders/{id}/answers saves the form's answers; with "complete": true it also completes the work order.

POST /work-orders/{id}/answers
{"answers": [
   {"question_id": "…", "value": "<option id>"},
   {"question_id": "…", "value": ["<option id>", "<option id>"]},
   {"question_id": "…", "value": 42},
   {"question_id": "…", "value": 3.75},
   {"question_id": "…", "value": "Belt replaced"}],
 "complete": true}
  • Only when the integration is assigned to the work order (as a worker, not a consultant) and the work is open, in progress or back from the consultant — as for a person in the app.
  • The value follows the question's type (GET /work-orders/{id}/answers shows the types and options). Questions you don't send are left unanswered; required questions must be answered to complete (422 rule_violation names the question).
  • Saving without complete puts the work in progress. Completing makes it complete — or, when a consultant is assigned, sent to the consultant's review, which stays in kommuns.
  • Time records, attachments, comments and putting on hold are not in the API yet.

A read-only organization (an unpaid plan) refuses new work orders and changes (403 read_only) but answering and completing go on, as in the app.