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.

Document Management (DMS) API

Work with a document and its versions

DMS distinguishes a workspace’s cabinet, folders, a document identity and immutable versions of that document. A document’s current version can change; a task’s recorded evidence should retain its actual document/version reference. The displayed title and uploaded filename are also separate contracts, with safe naming rules.

In people-ops, prepare only synthetic leave evidence under an admitted cabinet/folder. Storage encryption and dependencies are operator prerequisites, not a key pasted into a tutorial. Ordinary users authenticate normally; development actor headers are not an ordinary-user test or production instruction.

Task Actual surface below /api/documents Important input/result
Discover upload limits GET /upload-capabilities maxFileBytes, maxFiles, maxBatchBytes
Create a cabinet/folder POST /cabinets, /cabinets/{id}/folders Actual returned IDs; folder body name,parentFolderId
Upload first content Multipart POST /folders/{folderId}/documents Required file, optional name and task declaration
Add a version Multipart POST /{documentId}/versions Existing document admission and actual returned version
Download a reviewed version GET /{documentId}/content?version={n} Exact version; omission resolves current
Soft-delete/restore Document/folder DELETE and supported restore routes Current rights, parent constraints and retained history
Declare task context Supported taskId parameter/native task operation Server validates it; declaration is not a grant

For task attachments, distinguish a normal permitted attachment from required attestation evidence. The task upload controller requires the request’s folderId parameter; ordinary attachment upload checks that destination, while the required-attestation path resolves its destination from server-owned task evidence. A caller cannot turn either path into arbitrary folder access. Use DocumentBrowser for a screen-embedded library and the connected document workflow for the whole sequence.

These examples are source-backed requests and procedures with deployment-specific IDs. They were not executed against a product/storage runtime by this documentation program.

Worked examples

Example FLOW-DM-01 — Prepare a library and upload the first evidence version

Scenario and inputs. Nadia can create/select an admitted cabinet in the synthetic people-ops workspace, and Mohammad has the specific folder/task upload rights intended by the application. The file is a small synthetic leave-evidence document. Actual cabinet/folder IDs and encryption/runtime preparation come from the authorized environment; no tutorial value grants that access.

Procedure. Read /api/documents/upload-capabilities. Create or select the cabinet, then POST this complete folder body to /api/documents/cabinets/{cabinetId}/folders:

{
  "name": "Leave evidence",
  "parentFolderId": null
}

Retain the returned folder ID. Upload to /api/documents/folders/{folderId}/documents as multipart with required part file and optional name; let the client set the multipart boundary. Record the returned document/version identity, filename/MIME/size and current document metadata.

Expected result. The content is stored as a version of an actual document in the admitted folder. A selected display title is not a physical path, and a successful source parse is not a storage acceptance receipt.

Failure and recovery. An empty/oversized/denied upload is diagnosed at its actual boundary. Do not weaken limits, use a different actor header or substitute sample version IDs to make a failed upload appear complete.

Sources. DocumentController.java:153; DocumentController.java:171; DocumentController.java:321.

Example FLOW-DM-02 — Review version1 after a correction creates version2

Scenario and inputs. Sara’s task recorded a specific document/version reference. Mohammad later uploads a correction, so the document’s current version changes. Sara needs the original reviewed bytes rather than whichever version happens to be newest. Use the actual returned IDs and integers; this story does not assume every document begins at the same application state.

Procedure. List /api/documents/{documentId}/versions and identify the task’s recorded version. Download that version through /content?version={versionNumber} under the currently admitted actor/task context. Upload a correction only through the supported new-version multipart route with editor rights. Retain both references in the business explanation; omitting the download version deliberately resolves the current document version.

Expected result. The original review reference remains meaningful after a later version is uploaded. Download captures workspace, scope and task-read context for the asynchronous content stream and uses the safe current filename/disposition behavior.

Failure and recovery. A denied or missing version must not fall back to another document or latest content. Also do not assume that conversion respects this version selector: the separate conversion API takes only a document ID and resolves its current source version. Read its returned sourceVersionNumber explicitly.

Sources. DocumentController.java:366; DocumentController.java:373; DocumentController.java:406.

Example FLOW-DM-03 — Soft-delete and restore the intended synthetic document

Scenario and inputs. An editor discovers an accidental synthetic evidence upload. The actor has the current document/folder permissions, and deletion is intentionally confirmed for that exact document. This example explains the supported lifecycle, not authorization to purge a shared library or delete physical storage files.

Procedure. Read the document metadata and retained version reference, confirm the intended object, and use the supported document DELETE operation. Inspect the cabinet trash/current unavailable presentation as appropriate to the caller. If restoration is the intended recovery, POST the document’s /restore operation and read its current location/metadata again. Apply the separate folder restore rules when the parent folder itself was removed.

Expected result. Soft deletion retains the document/version history and the system’s audit/lifecycle evidence. Restoration is governed by current parent/object conditions; a previous editor role is not a permanent right to restore anything anywhere.

Failure and recovery. Do not run SQL deletion, filesystem cleanup, bucket pruning or permanent purge to imitate the user-facing operation. If the parent is unavailable or permission changed, have the actual owner resolve the constraint. A neutral unavailable response is not proof the bytes were physically erased and does not authorize recovery through another user’s account.

Sources. DocumentController.java:514; DocumentController.java:563; DocumentController.java:291.

Example FLOW-DM-04 — Use an actual task context without inventing a folder grant

Scenario and inputs. A participant must supply required evidence for an actual human task. The form/task policy can admit a specific operation even when the user is not a general library editor. The request still needs the real task/form relation and allowed file; a text task ID chosen by the client is insufficient.

Procedure. Use the native task upload/attachment flow. At the HTTP task upload route, send the required multipart file and folderId parameter plus optional name/label as supported. For required attestation evidence, the controller uses the task service’s server-resolved destination; for ordinary attachment upload, the chosen folder remains subject to ordinary current checks. When a DMS read/upload declares taskId, let the secured service establish its actual task-scoped evidence and preserve exact returned document/version references.

Expected result. A task-aware action can remain narrowly admitted without creating broader cabinet/folder access. Client folder IDs, task IDs and labels do not override the server-owned relation or current actor.

Failure and recovery. If task evidence is unavailable, the service does not infer a grant from the declaration. Do not fall back to an unscoped DMS route, alter object sharing or reuse another task’s ID. Resolve the actual task/form/destination constraint and retain any uncertain upload result before attempting a duplicate.

Sources. DocumentController.java:317; TaskController.java:446.

Detailed reference

Date: 2026-07-20
Status: v1 API surface over the hardened domain package
Base path: /api/documents

Scope

Workspace-scoped cabinets, folders, documents, versions, upload/download, soft-delete/restore, and full-text search. Permission enforcement uses the shared typed AssetAccessGuard hierarchy:

workspace -> cabinet -> folder -> nested folder -> document

The nearest matching object grant wins and removing it restores the current parent grant; no inherited value is copied into the child. Document versions inherit their document. Workspace administrators remain the recovery authority and can add, change, remove, or restore grants at cabinet, folder, and document scope. Workspace is taken from X-Workspace-Id (WorkspaceContext). Actor from session / X-Actor-Id in local dev.

The Documents page supports mixed multi-selection of cabinets, folders, and documents. Its bulk Security action applies one principal/role change, or restores inheritance, through POST /api/workspaces/{workspace}/grants/bulk. The operation is atomic: canonical object/workspace validation, optimistic revision checks, grant writes, and audit writes all succeed or all roll back. The endpoint accepts 1-100 unique object targets. It reuses the normal grant service and does not provide a separate authorization path.

Auth

Header Purpose
Auth as configured (session / API key) Required for all routes
X-Actor-Id Local/dev actor (tests use root)
X-Workspace-Id Active workspace (defaults to platform default if omitted)

Unauthenticated → 401 / 403 depending on filter. Grant failures → 403 ACCESS_DENIED. Resources outside the current workspace (or unknown ids) → 404 DOCUMENT_*_NOT_FOUND (no cross-workspace existence oracle).

Endpoints

Cabinets

Method Path Role (via grants)
GET /api/documents/cabinets VIEWER (workspace)
POST /api/documents/cabinets EDITOR (workspace)
GET /api/documents/cabinets/{cabinetId} VIEWER (cabinet)
PUT /api/documents/cabinets/{cabinetId} EDITOR (cabinet)

Cabinet DELETE is not exposed in v1 (hard cascade would orphan encrypted blobs without soft-delete/purge).

Create body: { "name": "Policies", "description": "optional" }

Folders

Method Path
GET /api/documents/cabinets/{cabinetId}/folders
POST /api/documents/cabinets/{cabinetId}/folders
GET /api/documents/folders/{folderId}
POST /api/documents/folders/{folderId}/move
DELETE /api/documents/folders/{folderId}

Create body: { "name": "Root", "parentFolderId": null }

Parent must belong to the same cabinet when set. Move/delete require EDITOR on the folder (and on the target parent or cabinet for moves).

Documents

Method Path
GET /api/documents/folders/{folderId}/documents
POST /api/documents/folders/{folderId}/documents (multipart)
GET /api/documents/{documentId}
GET /api/documents/{documentId}/versions
POST /api/documents/{documentId}/versions (multipart new version)
GET /api/documents/{documentId}/content?version=
DELETE /api/documents/{documentId} (soft-delete)
POST /api/documents/{documentId}/restore
POST /api/documents/{documentId}/move
POST /api/documents/{documentId}/convert/pdf (new PDF sibling; see document-conversion.md)
GET /api/documents/conversion/status

Upload: multipart/form-data field file (required), optional form field name.

Download: streams decrypted bytes; Content-Disposition: attachment.

Move document: requires EDITOR on the document and EDITOR on the target folder (same cabinet only).

Convert PDF: requires VIEW on the source document and EDITOR on the folder (for the new PDF upload). Source is never replaced. Workflow equivalent: service.dms.convert.docx-to-pdf (gated by process.module.enabled).

Method Path
GET /api/documents/search?q=

Results limited to cabinets the actor may VIEW. Requires non-blank q.

Errors (ProblemDetail)

Code HTTP
AUTHENTICATION_REQUIRED 401
ACCESS_DENIED 403
DOCUMENT_NOT_FOUND / DOCUMENT_CABINET_NOT_FOUND / DOCUMENT_FOLDER_NOT_FOUND / DOCUMENT_VERSION_NOT_FOUND 404
DOCUMENT_DELETED 410
validation / illegal argument 400

Configuration

Config file: conf/custom_config.properties (loaded by DocumentStorageProperties — not Spring application.properties).

Precedence: environment variable (when set) → config file → default (for path / key-id only). Encryption key has no public default; blank key fails startup.

Property / env Purpose
dms.storage.path / DMS_STORAGE_PATH Encrypted blob root (default data/documents; may be absolute e.g. E:/data/inflow-documents)
dms.encryption.key / DMS_ENCRYPTION_KEY Required AES key (Base64 16/24/32 bytes). Leave file blank in git; Compose sets DMS_ENCRYPTION_KEY for local dev
dms.encryption.key-id / DMS_ENCRYPTION_KEY_ID Blob key-id header (0–255). Changing without migration breaks retrieval
dms.upload.max-file-size Centralized upload size cap in conf/custom_config.properties (default 50 MB; domain hard cap is 100 MB)
dms.upload.max-request-size Centralized multipart request cap in conf/custom_config.properties (default 50 MB)

Example in conf/custom_config.properties:

dms.storage.path=E:/data/inflow-documents
dms.encryption.key=
dms.encryption.key-id=0
dms.upload.max-file-size=50MB
dms.upload.max-request-size=50MB
# Required for host runs outside Compose (Compose already injects a dev key)
$env:DMS_ENCRYPTION_KEY = (openssl rand -base64 32)

Required DMS encryption key

An effective DMS encryption key is a deployment prerequisite, not an optional tuning value. Supply it through DMS_ENCRYPTION_KEY (recommended for deployed environments) or dms.encryption.key; the environment variable takes precedence. It must decode to exactly 16, 24, or 32 random bytes. The API fails closed during startup when neither source supplies a valid key; this prevents a node from writing plaintext blobs or creating data that another node cannot read.

For staging and production:

  • generate a dedicated random key for each environment and Base64-encode it;
  • store it in the deployment secret manager, never in Git, images, Compose files, logs, tickets, or database rows;
  • inject the same value into every API/worker node that reads or writes DMS blobs, including replacement nodes during rolling deployments;
  • back up the key through the organization's protected secret-recovery process and test that recovery procedure before accepting document uploads;
  • do not reuse the vault, record-handle, data-action, audit-receipt, or any local-development key.

The defaults in docker-compose.yml are development-only. A successful local or test startup using that value is not production key evidence.

Changing the key makes existing encrypted blobs unreadable. The current DMS provider does not implement online re-encryption or an old-key keyring, so do not rotate or delete the old key until a tested re-encryption migration and rollback plan exists. dms.encryption.key-id is stored with the blob for identification; it does not by itself retain the corresponding old key.

Deployment verification must include both cases: startup succeeds with the injected secret, and startup fails when both DMS_ENCRYPTION_KEY and dms.encryption.key are deliberately omitted. See the shared-secret checklist in docs/manuals/active-active-deployment.md.

Migrations

  • 000050_create_document_tables — base tables + search_vector
  • 000085_document_soft_delete — deleted_at / deleted_by on documents
.\scripts\migrate.ps1 -Command up

Smoke (local)

# Headers assume default workspace + root actor after auth setup
curl.exe -X POST http://localhost:8080/api/documents/cabinets `
  -H "X-Actor-Id: root" -H "Content-Type: application/json" `
  -d "{\"name\":\"Policies\"}"

curl.exe -X POST "http://localhost:8080/api/documents/folders/{folderId}/documents" `
  -H "X-Actor-Id: root" -F "file=@.\policy.txt"

Studio UI

Route: /workspaces/:workspaceKey/documents

Build workbench resource: ?tab=Build&res=documents

Surface Agent handles (examples)
Page documents.page, documents.split, documents.tree, documents.browser
Cabinet documents.cabinet.new, documents.cabinet.create.*, documents.cabinet.edit.*
Folder documents.folder.new, documents.folder.create.*
Security tree/table selection, documents.security.bulk, per-object *.security actions
Files documents.upload, documents.table, documents.row.<id>.download|versions|new-version|delete|security
Search documents.search, documents.search.submit, documents.search.clear
Versions drawer documents.versions, documents.versions.<id>.*

Visual evidence suite (Playwright, mocked API):

cd studio/frontend
npx playwright test tests/ui-human/documents/documents-browser-visual.spec.ts --config=playwright.human.config.ts

Screenshots land under studio/frontend/tests/ui-human/shots/documents-browser/.

Cross-workspace cabinets

Cabinets can be shared through the generic workspace contracts API (same mechanism as Fabric DATASET sharing):

Piece Detail
Kind CABINET
targetKey Cabinet id (UUID)
Publish / grant POST /api/contracts + grants (Studio: Share on owned cabinets). Publisher must hold DOCUMENT_MANAGE (global ceiling) and EDITOR on the target cabinet (documentCabinet object), not only workspace editor / contract manage.
Gate Fail-closed: foreign cabinets are hidden until a published contract grants the consumer workspace (or visibility ALL). Uses ContractService.isGranted, not fail-open canConsume. Owner workspace must be ACTIVE — archived/deleted owners fail closed and drop out of catalog().
Consumer UI Catalog rows appear in Documents list/tree with a By contract badge (names from GET /cabinets/{id}); browse/download is read-only. Share is gated with a disabled reason until access resolves; authorized actors get an enabled control only when session has exact WORKSPACE_CONTRACT_MANAGE + DOCUMENT_MANAGE (or *) and cabinet EDITOR.

Whole-cabinet grant semantics

A CABINET contract is a workspace-level share of the entire cabinet, not a copy of the owner’s per-folder / per-document object ACLs:

  • In the owner workspace, object grants still apply (folder/document VIEWER ceilings, NONE overrides, etc.).
  • In a consumer workspace holding an explicit grant (or visibility=ALL), every actor with platform DOCUMENT_VIEW may list folders/documents and download content under that cabinet. Owner-side object ACLs are not re-evaluated for consumer actors (they have no identities in the owner’s grant space).
  • Mutations (edit cabinet, create folder, upload, new version, delete, restore) always require the cabinet’s owner workspace — consumers stay read-only.

Publishers should only share cabinets that are appropriate for full read access by the granted consumer workspaces.

Attachment binding (document references)

Form fields and human tasks store document id references, never raw bytes.

Value shape (DocumentAttachmentRef)

{
  "kind": "document",
  "documentId": "<uuid>",
  "versionNumber": 1,
  "name": "invoice.pdf",
  "mimeType": "application/pdf",
  "sizeBytes": 12345
}

Studio FileUpload / ImageUpload / Signature

Author a DMS folder id (folderId) on the control. When set, the runtime uploads the file through POST /api/documents/folders/{folderId}/documents and binds the field to a DocumentAttachmentRef (or an array when multiple is true). Without folderId, the control keeps the legacy browser File behavior for local previews only.

Human task attachments

Method Path Permission
GET /api/tasks/{taskId}/attachments TASK_VIEW (+ process access)
POST /api/tasks/{taskId}/attachments TASK_COMMENT — body { "documentId", "versionNumber?", "label?" } links an existing document the actor can already DOCUMENT_VIEW
POST /api/tasks/{taskId}/attachments/upload TASK_COMMENT — multipart file + form folderId (required), optional name / label; uploads via secured DMS then links
DELETE /api/tasks/{taskId}/attachments/{attachmentId} TASK_COMMENT — soft-detach (document remains)

Completed/cancelled tasks reject attach/upload/detach (TASK_NOT_OPEN, HTTP 409). Duplicate active links for the same task+document fail with TASK_ATTACHMENT_EXISTS. Audit: TASK_DOCUMENT_ATTACHED / TASK_DOCUMENT_DETACHED (metadata includes taskId, documentId, and mode=link|upload for attaches). Migration: 000101_create_task_document_attachments.

Process service.dms.attach continues to bind case-file metadata by configured literal documentId at publish time (read-only).

Process service.dms.convert.docx-to-pdf converts a governed Word document to a new PDF sibling via LibreOffice (Gotenberg HTTP or local soffice). Full contract, config, Arabic/English notes, and BPMN usage: document-conversion.md.

Text extraction (Apache Tika)

Upload stores the encrypted blob first. Sync path only best-effort-extracts small text/* / JSON / XML payloads. Everything else is marked extractionStatus=PENDING and claimed by a dedicated extraction lifecycle thread on API / integration-worker nodes (not the shared timer/outbox runOnce loop).

Status Meaning
PENDING Waiting for a worker claim
RUNNING Claimed; extract in progress (extraction_claimed_at lease)
READY extracted_text + search_vector updated (text may still be null if empty parse)
FAILED Terminal extract failure; extractionErrorCode is a stable machine code (no stack traces)
SKIPPED Empty blob, missing storage, soft-deleted document at claim time, or paused historical backfill

Hardening (migration 000103)

Control Value
Parse timeout 30s wall-clock (Future.get + cancel)
Max stored text 1_000_000 chars
Max parse / buffer bytes 25 MiB (enforced on retrieve, not only size_bytes)
Embedded / recursive parse Disabled (NoopEmbeddedDocumentExtractor)
Claim FOR UPDATE SKIP LOCKED, newest first, batch ≤ 3
Stale RUNNING Requeued if lease > 2 min and attempts < 3; else FAILED(STALE_RUNNING)
Historical backlog from 000102 PENDING rows older than 1 hour at 000103 apply → SKIPPED(HISTORICAL_BACKFILL_PAUSED)

Security: extraction is system maintenance on already-stored blobs. It does not change search ACL. GET /api/documents/search still requires DOCUMENT_VIEW and post-filters hits with document VIEWER; User A never receives User B’s rows or snippets without grants. Audit: DOCUMENT_EXTRACTION_COMPLETED / DOCUMENT_EXTRACTION_FAILED (ids + status only).

Migrations: 000102_document_extraction_status, 000103_document_extraction_hardening. Version API responses include extractionStatus, extractionErrorCode, extractedAt.

OCR for pure scans (Tesseract / AI Gateway vision) remains a follow-on when Tika returns no text.

Out of scope (later)

Scan OCR (Tesseract / AI vision tier), additional convert targets (sheet/slide → PDF), S3/MinIO provider, cabinet soft-delete, RAG, canvas signature pad, and process-instance case-file attachment collections beyond task links + form refs.

DOCX→PDF conversion is in scope — see document-conversion.md.

Authenticated downloads (083/T105 developer candidate)

A document download retains its authenticated identity for later dispatches of that same request. The stream keeps the admitted workspace and API-key permission ceiling, including an empty ceiling that denies all permissions. Existing DMS permission checks still run while writing the content. The next HTTP request authenticates again and checks current authority; this creates no HTTP session.

The candidate regression checks exact Word bytes and Content-Length, followed by a workspace read, for 20 pairs on one persistent TCP connection. It also checks normal cookie/CSRF authentication, download denials, scoped and revoked keys, worker context restoration, and one download audit per successful stream. Evidence is in specs/083-document-location-inputs/evidence/t100-wrapper-mutation/t105-final-focused-validation.json. Packaged runtime acceptance and full release validation remain separate gates.

If a connection fails after a mutating document action, reconcile the action's existing invocation identity and stored outcome before retrying. A missing HTTP response does not prove that no document or rule draft was created.

When an upload has no explicit display name, its OS filename is sanitized into a display title. Explicit folder/document display names follow the shared naming policy; invalid or blank service names are refused before persistence. The filename and uploaded bytes are separate from the display title.

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