Inflow.aiDocs

Optional technical reference. For end users and workspace administrators, read Inflow Home.

Source status — 13 November 2026

The Home configuration model, service, native authorization owner, persistence adapter and API controller were introduced in PR #4412. The controller is conditional on both inflow.home.enabled=true and inflow.application-user-access.enabled=true. Current master also has the caller-self Home Search API with Task and personal Requests source adapters, plus a separately default-off Social search adapter (inflow.home.social.enabled=false). The Requests source delegates to current personal CaseVisibility and reauthorizes references; none of these sources creates a Home search page or operator screen. The Studio source does not contain HomeConfigurationPage.tsx; there is no current Home operator form. Consolidated tests, API/DB transaction qualification, migration application and runtime qualification remain pending. This page describes the source contract; it is not a production runbook or permission to call an unqualified endpoint.

Request path

flowchart LR
  A[Original signed-in workspace administrator] --> B[Home configuration API]
  B --> C[Native workspace ADMIN; HOME_CONFIGURE when ceiling applies]
  C --> D[Revision and target revalidation]
  D --> E[(Home workspace configuration)]
  D --> F[Identified audit, operation receipt and event intent]
  U[Home operator UI: not in current Studio source] -. planned client .-> B

Every read and write is bound to the caller's established login session and current workspace. The path workspace coordinate does not grant access. The native owner requires current ADMIN on the canonical workspace and, when an API-key ceiling is present, HOME_CONFIGURE within that ceiling. A capability hint or permission catalog entry is not authorization. The group-options route also requires current IDENTITY_MANAGE to search groups; it does not add or remove group memberships. Publisher and moderator membership remain with their existing owners.

Routes in the current source

Base path: /api/home/workspaces/{workspace}/configuration.

Method and path Source behavior Bound
GET / Read the current configuration, or the source-defined defaults when no row exists. No-store; original session, current workspace administrator and HOME_CONFIGURE ceiling.
GET /functions?cursor={functionKey}&limit=25 List existing functions for the current workspace and return up to three already assigned functions separately. Default 25; maximum 50. A next cursor is the last returned key.
GET /groups?q={text}&cursor={id}&limit=25 Search active directory groups by name, key or ID. Query up to 100 characters; default 25, maximum 50; current IDENTITY_MANAGE is also required.
PUT / Submit one complete configuration successor using operationKey and expectedRevision. Strict top-level JSON shape; configuration body maximum 32 KiB; current targets are checked again inside the native write.
GET /operations/{key} Read the outcome recorded for this exact caller, account incarnation and operation key. NOT_FOUND means no matching receipt was observed; it does not prove an uncertain request had no effect.
POST /operations/{key}/cancel Explicitly close a still-unrecorded operation, or return its already-recorded outcome. The same original-session/current-admin boundary; never reverses a committed configuration.

Denied or unavailable workspace access returns a neutral 404 HOME_NOT_AVAILABLE. A stale revision or changed payload for a reused operation key returns 409 HOME_CONFIGURATION_CHANGED; reload and review the current state before preparing a new operation. Invalid input returns 400 INVALID_HOME_CONFIGURATION. An unavailable configuration dependency returns 503 HOME_CONFIGURATION_UNAVAILABLE. The response bodies are intentionally generic and no-store.

Configuration fields and default example

GET / returns the current workspace configuration. When it has no saved row, the source default is revision 0, enabled areas tasks and applications, brand label Inflow, no function bindings, no workspace-wide audience, and no selected audience groups. The allowed area keys are social, tasks, data and applications.

The following is an illustrative response only; it is not a request to call a live environment:

{
  "workspaceId": "workspace-west",
  "revision": 0,
  "enabledAreas": ["applications", "tasks"],
  "brandLabel": "Inflow",
  "socialFunction": null,
  "dataFunction": null,
  "startsFunction": null,
  "workspaceAudience": false,
  "audienceGroups": []
}

workspaceId and function keys are machine coordinates. The brand label is a display name and is normalized by the shared display-name policy. Enabling social requires a valid socialFunction; enabling data requires dataFunction. startsFunction is optional. A function binding can be assigned once, but cannot later be replaced or cleared through this configuration contract. Audience groups are selected IDs, not memberships; at most 50 IDs are accepted. Configuration changes never create functions, group memberships, grants, providers or business records.

Revision-bound update example

A client reads revision 3, reviews the current targets, and prepares the complete successor at revision 4. The operation key is stable for this one intended update. The values below are synthetic and illustrative only:

{
  "operationKey": "homecfg-20261112-0001",
  "expectedRevision": 3,
  "configuration": {
    "workspaceId": "workspace-west",
    "revision": 4,
    "enabledAreas": ["applications", "tasks"],
    "brandLabel": "West Operations",
    "socialFunction": null,
    "dataFunction": null,
    "startsFunction": null,
    "workspaceAudience": false,
    "audienceGroups": []
  }
}

The source requires configuration.revision = expectedRevision + 1, the exact canonical workspace and current saved revision. It revalidates any function and group targets in the write boundary. On a successful update, the source records configuration, identified audit, exact caller-owned operation receipt and durable event intent in one transaction. The response identifies the result with status, operationKey, revision, auditId and eventId; it does not grant rights or confirm that any external deployment has adopted the configuration.

Uncertain update handling

Keep the original operation key and the exact payload while its outcome is uncertain. Do not invent a replacement key to make a second change.

  1. Read GET /operations/{key} through the same original identity. COMMITTED returns the recorded outcome. CANCELLED means this operation key is terminal and cannot update the configuration. NOT_FOUND is only an observation, not rollback proof.
  2. If the operation must be abandoned, an authorized operator explicitly requests POST /operations/{key}/cancel with the same key. Cancellation either returns an existing committed outcome unchanged or records a terminal CANCELLED receipt, audit event and event intent without changing configuration.
  3. A delayed update using a cancelled key cannot apply a new configuration. Do not automatically retry cancellation or send a different payload under the same key after an uncertain response; reconcile that exact operation first.
  4. A 409 for a stale revision requires a fresh read and a new human review of the complete successor. A 409 for a changed payload under a prior operation key is not permission to mutate the old operation.

These rules describe source behavior, not a qualified operator interaction. The planned /home/configuration?workspace=... page is not present in current Studio source. Use the approved product interface only after its implementation and consolidated qualification are complete; do not turn these examples into manual production requests.

Source references

No feature flag, migration, provider, database, service or runtime was changed by preparing this reference.

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