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).
Search
| 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_vector000085_document_soft_delete—deleted_at/deleted_byon 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,
NONEoverrides, etc.). - In a consumer workspace holding an explicit grant (or
visibility=ALL), every actor with platformDOCUMENT_VIEWmay 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.