Inflow.aiDocs

Optional technical reference. This material is for developers, integration specialists and platform administrators. For the consultant lesson, read the practical guide.

Preserved from source baseline d4587c7c0e073e58c2d430342f65ac55dd701bf4; source/static examples retain their stated scope. They are not new runtime verification or required consultant setup steps.

Task Persistence

Work a task from its pinned form to its receipt

The persistence tables below support a person’s task lifecycle: available work can be claimed, an assigned task can hold a revisioned draft, an authored form/action can be submitted, and a durable receipt explains the accepted response. Storage rows are implementation detail; ordinary app users use the task screen and secured task APIs.

In the people-ops story, Mohammad’s case produces actual Review work for Sara. Keep these coordinates separate: task ID, process instance ID, pinned form key/version, draft revision and business reference leave-2026-014. They are not interchangeable. The record’s manager text does not authenticate Sara, and viewing a task does not necessarily disclose all of its form inputs.

Surface Input/reference to retain Result/recovery
GET /api/tasks/{taskId}/form Actual admitted task Captured form, not latest designer draft
Claim/release Current candidate/assignee rights Assignment state rechecked by the service
GET/PUT .../form-draft Current revision, original clientMutationId, flat values Saved revision;409 requires reconciliation
POST .../complete Allowed flat output/formData, actual form/action context Safe completion receipt
GET .../completion-receipt Same actual task and current view admission Canonical recorded progression, not a generic operation ID
Attachments Exact document/version and server-owned task constraints Task-bound admission, not general folder authority

Human completion’s maps are flat on the HTTP wire. Its DTO also supports decision, comment, formSubmissionId, submitActionId, submitActionRows, keepFields and expectedDraftRevision where the current native form contract requires them. These are not all values a caller may invent: protected fields/action rows come from the pinned form policy and current prepared state. The examples below distinguish actual request shapes from safe response projections. Runtime and ordinary-user video verification were not executed for this documentation.

Task commands, states and public result fields

Search the supported state predicate

GET /api/tasks?open=true&page=0&size=20 asks for current permitted nonterminal work. open=false asks for terminal work; omission does not apply that predicate. OPEN is not a TaskStatus, so do not send status=OPEN. An explicit status is one actual enum value and still does not replace actor/workspace/object admission.

Status family Actual values Interpretation
Preparation/assignment DRAFT, CREATED, READY, ASSIGNED, CLAIMED, IN_PROGRESS Current work state; allowed transitions come from service actions
Waiting/intervention WAITING_FOR_INFO, ON_HOLD, ESCALATED, DELEGATED, RETURNED Still nonterminal; a visible state does not grant intervention
Terminal COMPLETED, CANCELLED, EXPIRED, FAILED Finished work; not an item to complete or escalate again

The search controller also accepts actual process instance, assignee/candidate/involved actor, priority, overdue, unassigned, sort, form and text/page selectors. They intersect actual admission; a supplied actor ID is not impersonation. The retained repository section explains which criteria-contract fields are not stored repository filters. Never infer business-key filtering from the parameter name alone.

Completion and draft wire dictionary

Field Role Source of authority/recovery
output Flat business-output map Actual allowed output contract; not arbitrary case mutation
formData Flat answers for the captured form Pinned form normalization, participant and field rules
decision, comment Submitted decision/comment context Actual authored policy; not a universal action grant
formSubmissionId Existing submission context when the native flow supplies it Preserve original admitted submission; do not invent a receipt
submitActionId Actual authored submit node/action Current pinned form validates it
submitActionRows Outer-to-inner saved repeater coordinates Bounded typed list, not array indexes or expressions
keepFields Current native protected-field retention request Must match admitted baseline; cannot reveal or overwrite hidden values
expectedDraftRevision Draft baseline used by completion Use the actual read revision; stale data requires reconciliation
Draft values Flat saved form work Normalized against the actual pinned form
Draft clientMutationId One original save intention Same ID/different values is a conflict
Draft expectedRevision Previously read draft or null for initial absence 409means reread/reconcile, not automatic overwrite

Each nonempty submit-action row contains exactly nodeId and key. The transport allows at most8ordered entries, unique nonblank node IDs up to200characters, and a nonblank key string up to256characters or an integral JavaScript-safe number. These checks only establish transport shape: the service separately verifies saved ancestry, row admission and the selected submit action. Never derive authority from a valid-looking coordinate.

The public receipt includes decision, reason, submittedActionLabel, progression, completedCount, requiredCount, completedAt, completedBy, taskLabel, processLabel, businessCaseLabel, nextActivityLabel, nextResponsibilityLabel, formRecorded and alreadyCompleted. completedBy is presentation, not an actor credential. No taskId, processInstanceId, submitActionId, raw variables or generic receipt ID is returned by that projection. Absence of an internal ID is intentional; use the original permitted task coordinate for its readback.

Source contracts: task search/controller, TaskStatus, submit row validation, receipt projection.

Worked examples

Example FLOW-TP-01 — Save the first draft and reconcile a second device

Scenario and inputs. Sara is the current assignee of an open task with a pinned ISL form. Her second browser tab may hold an older draft. GET /api/tasks/{taskId}/form-draft returns 204 when there is no saved draft. For that initial absence, this complete save body uses null expected revision; replace the synthetic values with fields permitted by the actual pinned form.

{
  "expectedRevision": null,
  "clientMutationId": "leave-review-draft-01",
  "values": {
    "approved": true,
    "decisionComment": "Team coverage confirmed"
  },
  "keepFields": []
}

Procedure. PUT the body to the same task’s /form-draft route. Retain its returned revision and original mutation ID. A later intentional edit uses the last read revision and a new mutation ID; an unchanged retry of the original save retains the original ID and values. Reload before saving from the second tab.

Expected result. The draft is attributed to the authenticated assignee and retains its pinned form. Repeating the same mutation with identical normalized values can return the same draft; changing values under that identifier is an idempotency conflict.

Failure and recovery. On 409 read/reconcile rather than swapping the revision in an old values map. A completed task can win the save race and return no-content; inspect the completion instead of reopening it. Another person’s broad task view is not permission to save Sara’s draft.

Sources. TaskController.java:881; TaskServiceImpl.java:1584; TaskControllerTest.java:130.

Example FLOW-TP-02 — Submit an authored approval and read its canonical receipt

Scenario and inputs. Sara has the actual Review task and a pinned form that explicitly offers an action with ID approve; that string is a sample authored action ID, not a built-in universal action. Its contract permits approved and decisionComment. The saved draft in this example has actual revision 2. This is a complete controller body for that stated form contract, not an importable form definition.

{
  "output": {
    "approved": true,
    "decisionComment": "Team coverage confirmed"
  },
  "decision": "approve",
  "comment": "Coverage confirmed for 14–18 December",
  "formData": {
    "approved": true,
    "decisionComment": "Team coverage confirmed"
  },
  "submitActionId": "approve",
  "submitActionRows": [],
  "keepFields": [],
  "expectedDraftRevision": 2
}

Procedure. Submit through /api/tasks/{taskId}/complete only while the current task/form/action policy permits it. If the native flow already has a formSubmissionId or authored row context, retain that original context instead of substituting this illustrative one. Read /completion-receipt after acceptance or a transport interruption.

Expected result. The server checks current participant, form/action and output authority and returns a safe receipt explaining recorded work and progression. A Boolean answer does not by itself publish a different action or mutate arbitrary record fields.

Failure and recovery. Do not submit hidden/protected answers merely because they were present in an old response, invent generic receiptId/operationId fields, or issue a second consequential action after an uncertain reply. Read current task/receipt evidence and reconcile the original submission.

Sources. TaskController.java:208; TaskController.java:848; TaskCompletionReceiptResponse.java:10.

Example FLOW-TP-03 — Explain a response that is recorded but still waiting for others

Scenario and inputs. The workflow author deliberately configured a shared step that needs three required responses. One eligible participant completes the first response using its actual allowed form/action. The following is a safe receipt projection: omitted fields still exist on the full response, and these numbers describe the illustrative authored policy rather than every task.

{
  "progression": "WAITING_FOR_OTHERS",
  "completedCount": 1,
  "requiredCount": 3,
  "formRecorded": true,
  "alreadyCompleted": false
}

Procedure. Read the canonical receipt after the participant’s accepted response. Explain completedCount versus requiredCount and inspect the actual case position. As later admitted responses arrive, refresh through the current task/case surfaces. Keep the receipt’s next activity/responsibility labels tied to this completion rather than naming any other open task in the case as its successor.

Expected result. The person’s response is recorded even though the shared step has not advanced. WAITING_FOR_OTHERS, RECORDED, SENT_FORWARD, ALREADY_ADVANCED and CASE_COMPLETED each make a different supported claim about progression.

Failure and recovery. Do not tell the user “approved and finished” from a disabled submit button or a short successful HTTP reply. A missing/denied receipt is not proof the response was never accepted. Keep the original submission and use its admitted reconciliation path before another action.

Sources. TaskCompletionReceiptResponse.java:10; TaskCompletionReceipt.java:1.

Example FLOW-TP-04 — Attach evidence through the task’s own admitted destination

Scenario and inputs. Mohammad is asked to supply evidence on a task form, and the form’s published constraints permit a synthetic document. He does not necessarily have general editor access to every folder in the workspace. The actual task/form context, admitted file constraints and document/version references come from the native task surface.

Procedure. Open the permitted task attachment/upload action. Use the task route, such as /api/tasks/{taskId}/attachments/upload, with its actual accepted multipart parts; let the server resolve and check the destination. Retain the returned attachment and exact document/version reference. Read or remove that relation only through the current supported task operation and permissions. When using an already stored document, inspect its actual version instead of choosing a title that looks right.

Expected result. Task-scoped admission can allow the specific evidence operation without creating a broad folder grant. A supplied taskId or client-selected folder is a declaration, not the server’s authorization evidence.

Failure and recovery. If the file, task state or destination is refused, correct the actual constraint with the responsible owner. Do not fall back to an unscoped folder upload, spoof a task ID or broaden document sharing merely to make the form submit. A task attachment is not proof that every case reader may download its content.

Sources. TaskController.java:421; TaskController.java:446; DocumentController.java:321.

Detailed reference

The task persistence slice stores human task state in PostgreSQL while keeping the task service contract unchanged.

Tables

Migration 000006_create_task_tables creates the core tables:

  • human_tasks: the main task row.
  • task_candidate_assignees: candidate actors that may claim or work on a task.
  • task_comments: comments, decisions, system events, and other task notes.

Later migrations extend the aggregate with workspace/form constraints, document attachments, completion policy/quorum, and the performer's separate completion output. Inspect the ordered migration files for the complete current schema.

Aggregate Shape

HumanTask is treated as the aggregate root.

flowchart TD
    Task["human_tasks"] --> Candidates["task_candidate_assignees"]
    Task --> Comments["task_comments"]
    Task --> Variables["variables_json"]

The repository saves the full aggregate in one transaction:

  1. Upsert the human_tasks row.
  2. Replace candidate assignee rows for the task.
  3. Replace comment rows for the task.

This keeps the Java task model and the database representation synchronized without changing the service API.

JSON Fields

Task variables are stored in human_tasks.variables_json.

Use this for workflow/task data that is dynamic or task-specific. Do not add a table column for every possible workflow variable.

Actor Fields

Actor references are stored as normalized triples:

  • *_id
  • *_type
  • *_display_name

This pattern is used for:

  • owner
  • assignee
  • delegated from
  • assigned by
  • completed by
  • comment creator
  • candidate assignees

Search Support

JdbcTaskRepository supports the same search behavior as the in-memory task repository for fields that exist on HumanTask:

  • process instance id
  • element id
  • assignee id
  • candidate actor id
  • status
  • priority
  • overdue: open past the deadline adjusted for SLA pauses, or completed after it; never cancelled, expired or failed (TaskOverdueSql, SCRUM-4639). The attention order ranks the same tasks first, and every task response carries the same verdict as overdue
  • due date range
  • created date range
  • form definition key
  • text query across name, description, and form key

businessKey and processDefinitionKey remain criteria-contract fields but are not repository filters because they are not stored on the HumanTask aggregate. Workspace scoping is enforced through the related runtime process instance.

Completion Receipts

Each completed task has one durable completion receipt (human_task_completion_receipts), which the task page shows after a submit and on reload (GET /api/tasks/{taskId}/completion-receipt). Its progression drives the "What happens next" line:

Progression Meaning What the worker reads
CASE_COMPLETED The case itself has ended: a plain process completed, or the lifecycle case (not only one state's flow) completed. "This case is complete. No further action is waiting in this process."
SENT_FORWARD The case moved on because of this completion. For a lifecycle state this means the next state started; the receipt names that state's task and who has it when that is unambiguous. Work opening elsewhere in the case is never named. "The case has moved to Assess the claim. The next response is expected from Claims assessors." or "The case has moved to the next step in the process."
WAITING_FOR_OTHERS A shared step still needs other people's responses. "1 of 3 required responses are complete. The process will continue when the requirement is met."
ALREADY_ADVANCED Another completion had already moved the case. "Your response was already recorded and the case had already moved forward."
RECORDED The response is recorded, and the case's next move could not be seen (for example, a lifecycle state finished but the case did not move on). "Your response is recorded. The process will continue according to its published workflow."

A lifecycle case moves to its next state only after the completion transaction commits. The task service therefore records the completion and advances the token in one transaction, then settles the receipt against the case once that transaction has committed (SCRUM-3631). The TASK_COMPLETED audit row keeps the progression known inside the transaction (RECORDED for a lifecycle state whose case moves on after commit). When the caller supplies its own transaction, as an authoring debug session does, the receipt stays RECORDED.

Spring Wiring

The platform Spring configuration now wires:

TaskRepository taskRepository(JdbcTemplate jdbcTemplate) {
    return new JdbcTaskRepository(jdbcTemplate);
}

TaskServiceImpl and the secured task service decorator therefore use PostgreSQL-backed tasks in the application runtime. In-memory task repositories remain available for focused tests.

Current-source update — SCRUM-5108 decision outcome

Decision outcome versus submitted form value (SCRUM-5108)

For a published decision form, the chosen, visible completion action is part of the authoritative form context. Suppose root-level Approve and Reject actions write distinct fixed values to the same hidden decision field. If the root decision key is absent from the submitted answers, the selected action supplies the recorded decision and fixed route value. The server does not add that value to the saved form-answer map. A plain submit action with no authored decision remains a plain completion with no decision.

This omission allowance is not a general default or repair rule:

Submitted state Selected action Result
Root decision key absent Root Approve Accept the authored Approved decision; do not synthesize the missing form answer.
Root decision is Rejected Root Approve Refuse with TASK_FORM_OUTCOME_ROUTE_MISMATCH; do not save.
Root decision is explicitly empty Root Approve Treat as a present value; refuse if it differs from the authored outcome.
Repeated-row decision key absent on the selected row That row's Approve Refuse; the root omission rule does not apply to a row occurrence.
Decision value appears only on another repeated row Approve on a different row Refuse; the row coordinate and outcome must agree.
Root decision equals the selected action's fixed outcome That root action Accept the authored decision.

The form must still define one common route field with a distinct fixed value for every authored decision outcome, and only an available rendered action can be selected. For a decision action inside a repeater, retain the exact saved row coordinates and require its outcome in that selected occurrence. The native task screen and API must preserve the same pinned-form boundary; clients must not choose a different action or outcome by changing transport fields.

Sources: root-route omission check, saved-row decision validation, SCRUM-5108 regression case, task completion endpoint, completion receipt endpoint, and SCRUM-5108 acceptance boundary.

The public receipt includes decision, reason, submittedActionLabel, progression, completedCount, requiredCount, completedAt, completedBy, taskLabel, processLabel, businessCaseLabel, nextActivityLabel, nextResponsibilityLabel, formRecorded and alreadyCompleted. completedBy is presentation, not an actor credential. No taskId, processInstanceId, submitActionId, raw variables or generic receipt ID is returned by that projection. Absence of an internal ID is intentional; use the original permitted task coordinate for its readback.

Source contracts: task search/controller, TaskStatus, submit row validation, receipt projection.

Try “document generation”, “integrations” or “first form”.