ADR-0013: Event-Based API for Task Status Transitions

Status

Accepted

Decision

Fieldforce task status changes are triggered by sending a named event (start, submit, approve, reject, resubmit, cancel) in the PATCH body — not a target status string. The server enforces all guards (role, current state, required fields) via the state machine before accepting any transition. The event key and field-update keys are mutually exclusive in the same PATCH body.

Why

A target-status API (PATCH { status: "completed" }) lets clients drive any transition by guessing the right status string. Guards in the state machine become unreachable because the handler must re-implement role and state checks before calling the machine — or skip them and let bugs through. Separate endpoints per transition proliferate routes without adding expressiveness. Rejected alternatives:

Target-status API (PATCH { status: "in_progress" }): Business rules can be bypassed. Every consumer needs to know which status strings are valid from which state. Rejected.
Separate endpoints per transition (POST /tasks/:id/approve): Multiplies routes. A single PATCH with an event discriminator is the idiomatic REST pattern for state machines. Rejected.

How it works

The PATCH body has two mutually exclusive shapes:

Transition:    { "event": "reject", "review_note": "Missing photos" }
Field update:  { "priority": "high", "due_date": "2026-06-01", "assigned_to": ["uid1"] }
Both present → 400 Bad Request

Valid events:

Event	From	To	Guard
`start`	`pending`	`in_progress`	role ∈
`submit`	`in_progress`	`completed`	role = field_team
`approve`	`completed`	`approved`	role ∈
`reject`	`completed`	`needs_revision`	role ∈ + review_note present
`resubmit`	`needs_revision`	`completed`	role = field_team
`cancel`	any non-terminal	`cancelled`	role ∈

Handler dispatches to TaskService.TransitionTask for event bodies and TaskService.UpdateTask for field-update bodies.

Rules for agents

PATCH handler MUST reject with 400 if both event and any field-update key are present in the same body
Never accept a status field in the PATCH body to change task state — use event only
review_note is required when event = "reject" — validate at handler level before calling the state machine
Do not add role checks in the HTTP handler that duplicate guard logic already in the state machine transitions

Bad pattern (do not generate)

// Accepting a target status — bypasses state machine guards entirely
func (h *TaskHandler) PatchTask(c echo.Context) error {
    var body struct{ Status string `json:"status"` }
    c.Bind(&body)
    task.Status = body.Status // wrong — no guard, no role check
    return h.repo.Update(ctx, task)
}

// Client sending target status instead of event
await fetch(`/tasks/${id}`, {
  method: "PATCH",
  body: JSON.stringify({ status: "approved" }), // wrong — use event
});

Good pattern

// Handler dispatches on event vs field-update
func (h *TaskHandler) PatchTask(c echo.Context) error {
    var body TaskPatchBody
    if err := c.Bind(&body); err != nil { return err }
    if body.Event != "" && hasFieldUpdates(body) {
        return echo.NewHTTPError(400, "event and field updates are mutually exclusive")
    }
    if body.Event != "" {
        return h.handleTransition(c, body)
    }
    return h.handleFieldUpdate(c, body)
}

// Client sends a named event — not a target status
await updateTask({ event: "approve" });
await updateTask({ event: "reject", review_note: "Missing site photos" });

// Field update uses separate body shape
await updateTask({ priority: "high", due_date: "2026-06-01" });

Architecture Decision Records

Digital Worker

Fieldforce Mobile (Flutter)

0013 fieldforce event based task transitions

ADR-0013: Event-Based API for Task Status Transitions

Status

Tags

Decision

Why

How it works

Rules for agents

Bad pattern (do not generate)

Good pattern

​ADR-0013: Event-Based API for Task Status Transitions

​Status

​Tags

​Decision

​Why

​How it works

​Rules for agents

​Bad pattern (do not generate)

​Good pattern

ADR-0013: Event-Based API for Task Status Transitions

Status

Tags

Decision

Why

How it works

Rules for agents

Bad pattern (do not generate)

Good pattern