Case documents and transitions

Operational cases follow the workflow definition linked to their monitored process. State-level documents define required file slots; transition-level require_documents: true tells the engine to block the move until every required slot is filled in the case providedDocuments context array.

Model the requirements

In the .kiket/workflows/ directory (workflow YAML files):

1. Attach document slots to a state:

states:
  risk_review:
    type: active
    documents:
      - id: security_questionnaire
        label: Security questionnaire
        required: true

2. Opt a transition into the document guard:

transitions:
  - from: risk_review
    to: dpa_review
    name: Submit DPA Review
    require_documents: true

In the visual editor, select the transition edge and enable Require documents in the property panel. The flag round-trips through YAML save.

Related guard toggles on the same edge:

• Require checklist → require_checklist: true
• Require approval → require_approval: true

Runtime behavior

When a user uploads a file for a case:

1. The attachment is stored through /api/v1/attachments/upload (dev) or /attachments/presign-upload (production storage).
2. Pass documentRequirementId matching the workflow RequiredDocument id.
3. The API writes a document record (id, filename, attachmentKey, and related metadata) into the case providedDocuments context array.
4. Transition checks read that array through the engine documentGuard.

Direct PATCH /platform/cases/:id with currentStateKey is rejected. Use the transition API instead so guards always run.

API surface

Web UI

Open Operational Cases, select a case, and use Workflow controls:

• Upload panels appear for each required document on the current state.
• Transition buttons show engine blockers inline when guards fail.
• Successful transitions refresh case state labels and close final states automatically.

Scanner alignment

The event scanner already evaluates blocked transitions using the same engine canTransition path. Keeping uploads and transitions on the platform APIs ensures UI actions, scanner findings, and audit evidence stay consistent.