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.

DocumentBrowser control

Build a library view with a precise root and binding

DocumentBrowser is a normal screen node backed by secured DMS operations. It can show a read-only library, select governed references into a field, or offer individually enabled actions under the user’s actual rights. It is not a full document application, an iframe or a source of new permission grants.

Use a deliberately resolved cabinet and optional subtree root. A screen expression that has not resolved to a valid root must not trigger a request for some other cabinet. Design preview is static chrome; ordinary published/Preview interaction is a separate runtime context.

Setup choice Decide explicitly
Browse-only selectionMode:none; no bind is required if selection-dependent mutations are off
One evidence value single plus a document-compatible bound field
Multiple evidence values multiple plus a compatible collection field
Allowed actions allowUpload/Download/Move/Delete/Convert/Share describe authored affordances, not server grants
Confinement Cabinet/rootFolder determine navigation scope; move destinations stay in its admitted root
Selected reference kind:document, actual documentId, optional pinned versionNumber and metadata
Events Inspect actual event contracts; LiveForm currently emits onSelect with folderId:null

Selection can be promoted to single when a move/delete/convert/share affordance needs a target, even if authored selection mode is none. That promotion still does not authorize the effect. A task-bound document operation has its own server admission; embedding a control cannot create it.

The JSON snippets below are individual node/value fragments, not complete screens or importable applications. Validate the owning screen through the actual screen contract and publication workflow. These source-reviewed examples do not claim a newly executed browser, upload or permission-matrix result.

Worked examples

Example FLOW-BC-01 — Embed a browse-only HR policy library

Scenario and inputs. Nadia adds a document library to an admitted leave application screen. The intended users can view its policy cabinet/subtree, but the field must not collect a selection or offer mutation tools. The cabinet/folder strings below stand for actual returned IDs selected by the builder.

{
  "id": "hrPolicies",
  "type": "DocumentBrowser",
  "label": "HR policies",
  "cabinetId": "actual-policy-cabinet-id",
  "rootFolderId": "actual-policy-root-id",
  "selectionMode": "none",
  "allowUpload": false,
  "allowMove": false,
  "allowDelete": false,
  "allowConvert": false,
  "allowShare": false,
  "allowDownload": true
}

Procedure. Place the node through the actual designer and configure its root. With no selection-dependent mutation enabled, omit bind. Save/validate/publish the owning screen with its current revision and impact protocol. In an admitted runtime, navigate the folder tree and breadcrumbs only within the configured root; inspect the actual DMS list response rather than static design chrome.

Expected result. The library can be browsed without inventing a hidden form answer. The author’s root and the server’s current document admission both apply.

Failure and recovery. If the cabinet expression is empty/unresolved, keep the supported empty/unavailable presentation. Do not list all cabinets as a fallback or treat allowDownload as an override for denied content rights.

Sources. LiveForm.tsx:5363; DocumentBrowserControl.tsx:248.

Example FLOW-BC-02 — Store a single governed evidence reference

Scenario and inputs. Mohammad’s published form has an allowed document-compatible evidence field. Nadia configures the library with single selection and the actual supported bind. The value below is an illustrative reference projection; its document ID/version and metadata must come from the selected current response.

{
  "kind": "document",
  "documentId": "actual-document-id",
  "versionNumber": 1,
  "name": "Leave evidence.docx",
  "mimeType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
  "sizeBytes": 12000
}

Procedure. Select the permitted document in the rooted library. Inspect the bound field value and preserve its exact document/version pair when the form is saved/submitted. For multiple selection, author a compatible collection and expect an array of these references rather than silently joining names. Read the actual onSelect/onChange event data if an automation depends on selection; do not infer a folder from a currently null event field.

Expected result. The form stores a governed reference, not file bytes, a download URL or a title used as authority. The optional metadata describes the selection but does not grant download or mutation rights.

Failure and recovery. Correct a field/cardinality mismatch in the authored screen. Do not coerce arbitrary strings/objects into valid references, substitute a latest version for recorded evidence, or add an attachment to a task merely because its label was visible.

Sources. documentBinding.ts:1; DocumentAttachmentRef.java:10; LiveForm.tsx:5417.

Example FLOW-BC-03 — Upload to the current permitted folder inside a subtree

Scenario and inputs. The application deliberately offers upload in a case-evidence library, and the signed-in actor actually has the required destination/task admission. The root is a permitted subtree; it is not a starting hint that allows upward navigation. Upload size/count limits remain the actual DMS capabilities.

Procedure. Configure allowUpload:true only for the intended authored use and resolve cabinet/root correctly. Navigate to the desired admitted descendant and choose a small synthetic file. The control uploads to that current folder and emits onUpload with versions and folderId. Retain the actual returned references and, if selection is part of the form, select/store the supported document reference rather than assuming upload alone submitted the task. Keep mutation flags for move/delete/share off unless each is required and admitted.

Expected result. The uploaded version is associated with the actual current permitted folder, and the form/task still follows its own save/completion operation. Breadcrumbs and move targets do not escape the configured root.

Failure and recovery. A true authoring flag does not grant server rights. On refusal, correct the actual destination/actor/form constraint; do not switch cabinets, spoof a task context or retry through a broad raw API to bypass the denied operation. Reconcile an uncertain upload before another copy.

Sources. DocumentBrowserControl.tsx:276; LiveForm.tsx:5430; DocumentController.java:321.

Example FLOW-BC-04 — Tell empty, denied and temporarily unavailable apart

Scenario and inputs. Three admitted test situations are deliberately different: an authorized folder has no documents; the current reader cannot access the configured root; or an authorized read is temporarily unavailable. Nadia must teach support staff to recognize those states without using sample data or disclosing a protected library’s existence.

Procedure. Open the published node with the intended ordinary reader and inspect its actual state. For a genuinely authorized empty folder, show the normal no-files presentation. For denied access, apply the shared neutral unavailable behavior and omit unauthorized controls/requests. For an access/load outage, use the supported read recovery and refresh only after current access is established. If an action promotes selection to single, inspect that as a targeting behavior, not as newly granted authority.

Expected result. The user is not told that an inaccessible folder is an empty library, and a temporary failure is not mistaken for a permanent denial. Previous protected selection/content does not become a cached disclosure path when current admission fails.

Failure and recovery. Never add a permission-error banner, hidden-object Retry control or fabricated sample file to make the panel look populated. An available convert/share button still needs its actual server checks; an unavailable engine or object grant has its own owner-controlled recovery. Design-canvas screenshots alone cannot prove these runtime permission states.

Sources. DocumentBrowserControl.tsx:338; authorization-visibility-policy.md:1.

Detailed reference

Purpose

DocumentBrowser is an embeddable screen control that exposes the governed Documents (DMS) library inside forms, App Shells, and dashboards. Consultants place it like any other design control and configure roots, selection, and mutation flags with expression-enabled properties.

It is not a full-page Documents app and not an iframe. It is a first-class ISL control that calls the same /api/documents/* APIs with workspace ACL.

Product decisions (v1)

Decision Choice
Name DocumentBrowser
Modes Browse-only and browse + select into a field and browse + upload
Default root Whole cabinet (cabinetId)
Selection cardinality Consultant property: none | single | multiple
Drill-down confinement Cannot navigate above the configured root
Document preview Out of scope (later)
Expression dialect Same as other screen props (${…} / ex!)

Authoring properties

Key Kind Expression Meaning
label text yes Field label
bind bind — Where selection is stored (when mode ≠ none, or when move/delete/convert/share promotes selection). Not required for browse-only (selectionMode=none with those mutation flags off).
cabinetId text yes Root cabinet id (required for load)
rootFolderId text yes Optional subtree root; empty = cabinet roots
selectionMode select no none | single | multiple
allowUpload exprbool yes Show upload into current folder (default false)
allowDownload exprbool yes Allow download of listed docs (default true)
allowMove exprbool yes Move selected docs within the configured root (default false)
allowDelete exprbool yes Soft-delete selected docs (default false)
allowConvert exprbool yes Convert Word → PDF when engine available (default false)
allowShare exprbool yes Open object security / grants for selected doc (default false)
showTree bool no Show left folder tree (default true)
height number no Min height in px for the panel (default 360)
visibleWhen / disabled shared yes Standard control flags

When move/delete/convert/share is enabled and selectionMode is none, runtime promotes selection to single so users can target documents.

Unresolved / empty cabinetId → empty state (fail closed; no cross-cabinet leak).

Runtime behavior

  1. Resolve expression props in Live / published context.
  2. Load folders for the cabinet; if rootFolderId set, only show that subtree (ancestors above root are not navigable).
  3. Breadcrumb + folder tree (optional) + document list for the current folder.
  4. Selection: when mode is single/multiple, update bind with DocumentAttachmentRef or DocumentAttachmentRef[] (same shape as FileUpload DMS mode).
  5. Upload: when allowUpload and actor may mutate, multi-file upload into the current folder (not above root).
  6. Download: when allowed, use documentsApi.download.
  7. Move / delete / convert / share: when the matching allow* property is true, selection toolbar actions call the secured DMS APIs (move stays inside root; convert requires a healthy conversion engine; share opens object security).
  8. All list/get/mutation paths use existing secured DMS APIs.

Design canvas (ScreenRenderer) shows a static chrome preview (no live DMS unless Live mode / published).

Events

Trigger Payload
onSelect selection (refs), folderId: null in the current LiveForm adapter
onNavigate folderId, cabinetId
onUpload versions, folderId
onMove documentIds, folderId
onDelete documentIds
onConvert sourceDocumentId, pdfDocumentId, pdfName
onShare documentId

Surfaces

  • Form / task interfaces (LiveForm)
  • App Shell pages hosting published screens
  • Dashboards embedding the control in a widget region

Security

  • Server object grants remain authoritative.
  • Cross-workspace cabinet contracts stay read-only as today.
  • The control never invents visibility. A permission denial is not proof of an empty document library. Apply the shared neutral unavailable state for denied access; keep transient load failures distinct and never substitute sample files. See authorization visibility policy.

Out of scope (still)

  • In-panel document preview / PDF viewer
  • Workspace-wide cabinet picker (pass cabinetId from process/form)
  • Soft-delete restore UI inside the control

Tests

  • Unit: property defaults, expression root resolution, selection write shape, confinement above root
  • Registry drift: vocabulary ↔ schema ↔ nodeRegistry
  • Human Playwright: toolbox insert → props → Live browse/select/upload shots
  • studio/frontend/src/features/screens/document-browser/
  • documentsApi / documentBinding.ts
  • ScreenVocabulary / screen.schema.json / nodeRegistry.ts

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