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.

Business Functions and Inherited Security

Practical guide and worked examples

Build a permission model before granting access

A business function is an organizational grouping for workspace assets, not an expression function and not a service identity. Use a leave_management business function to keep the leave model, rules and interfaces together. An asset's function and its object's native authorization determine how inherited grants are interpreted; moving the asset can change that inheritance and therefore needs review.

Grant scopes are WORKSPACE, FUNCTION and OBJECT. Principals are USER or GROUP; use actual directory IDs. Roles are VIEWER, EDITOR, ADMIN, and the explicit scoped override NONE. The effective resolver examines the most specific applicable level before falling back to broader scope. NONE is meaningful at function/object level; restoring inheritance removes the override rather than adding another broad permission.

Reader question Surface Value to retain
What can be directly secured here? Authorized security-object catalog Native objectType and exact object ID.
Where did this access come from? Grant panel / effective access Principal, scope, direct/inherited provenance and revision.
May I replace this override? Grant mutation Current expectedRevision, or -1 for a genuinely new grant.
Does this person have object access? Check access Authorized current decision, not an assumed directory-role expansion.
May this person work this task/read this row? Owning task/record policy Separate current business eligibility.

The UI hides unauthorized controls and avoids unauthorized catalog requests. A direct link does not manufacture a grant. Application-only access should use the published application contribution path rather than a general Editor grant. Start with a narrow group/object scope and test both an intended object and an ungranted sibling.

The examples below use synthetic teaching data. They are grounded in the cited source contracts; this documentation change did not execute these operations against a running Inflow deployment. Use normal authenticated sessions and the actual returned identifiers, revisions and versions from an authorized environment.

Example ROOT-SEC-01 — Organize leave assets under a business function

Scenario and inputs. Nadia administers people-ops and wants an understandable ownership group for the leave application. The existing default general function remains available for uncategorized assets. A new function key leave_management will identify the grouping; its display name is Leave management. These values do not create a role, a callable InflowEL function or a workflow service account.

Procedure. List the current functions using GET /api/workspaces/people-ops/functions. Create the grouping only if it is absent:

POST /api/workspaces/people-ops/functions
Content-Type: application/json
{"functionKey":"leave_management","name":"Leave management","description":"Leave application assets","ownerUserId":null,"sortOrder":20}

Keep the returned function identity. Associate the intended assets through each native authoring surface, then inspect GET /api/workspaces/people-ops/functions/leave_management/assets before moving any remaining content.

Expected result. The new business function appears in the authorized workspace list. Its asset-count response describes actual current grouping, not the number of published runtime rows. The general function remains the default. Assets continue to enforce their own contracts and may inherit different access when their function association changes.

Failure and recovery. If a duplicate key is reported, inspect the existing function rather than creating near-duplicate groupings with different spelling. If moving assets would change access, review the affected grants and source objects first. A function-owner label is not a substitute for workspace administration or an object-specific action grant.

Sources. WorkspaceFunctionController.java:28, WorkspaceFunctionController.java:70.

Example ROOT-SEC-02 — Create one object grant with a real revision fence

Scenario and inputs. Nadia has authorized workspace security administration. The security-object catalog has returned an actual object type and ID for the leave interface, and the group directory has returned the intended Employees group ID. These must be native references; screen and <interface-id> below illustrate the selected catalog result, not a promise that a display key is the object ID.

Procedure. Open the grant panel for the exact object and inspect direct versus inherited sources. For a genuinely absent direct group entry, use the new-grant revision -1:

PUT /api/workspaces/people-ops/grants
Content-Type: application/json
{"scopeType":"OBJECT","objectType":"screen","scopeId":"<interface-id>","principalType":"GROUP","principalId":"<employees-group-id>","role":"VIEWER","functionKey":"leave_management","expectedRevision":-1}

Reload the panel and retain the saved revision. If the catalog uses a different native object type, use that returned type rather than copying this illustrative value.

Expected result. Only the chosen principal/scope entry is changed. The panel records the direct grant and its provenance. This grant is not proof of a complete application-runtime contribution, a data-row policy, task candidacy or provider disclosure. Test the intended interface and a sibling with normal user sessions within an admitted environment.

Failure and recovery. GRANT_REVISION_REQUIRED means the request omitted or misrepresented its concurrency coordinate. A stale write requires reloading and reviewing the new state, not replacing it with -1. If the object or principal cannot be selected, resolve its authorized catalog visibility instead of guessing a hidden ID or granting the whole workspace.

Sources. WorkspaceSecurityController.java:68, WorkspaceSecurityController.java:154, GrantScope.java:1.

Example ROOT-SEC-03 — Restore inheritance instead of adding a compensating grant

Scenario and inputs. Sara's manager group has an explicit override on a leave object. Nadia wants that group to follow the existing business-function/workspace inheritance again. She has read the current grant panel and knows the precise principal, scope, object reference, function and saved revision. Removing this override must not remove another group's independently valid contribution.

Procedure. In the security panel choose the action that restores inheritance for that exact row and review the current source explanation. The API uses a conditional DELETE, for example:

DELETE /api/workspaces/people-ops/grants?scopeType=OBJECT&objectType=screen&scopeId=<interface-id>&principalType=GROUP&principalId=<managers-group-id>&functionKey=leave_management&expectedRevision=<current-revision>

The angle-bracket values are URL-encoded actual returned coordinates, not literal strings to send. Reload the panel and Check access after the delete. Inspect both the direct override and the effective inherited decision.

Expected result. The direct entry is removed and the resolver can fall back to the applicable broader scope. That differs from persisting role NONE, which expresses a scoped override rather than absence. Independent principals and other application sources remain part of effective access. A successful removal therefore need not make the person unable to read the object.

Failure and recovery. If the panel changed, retain the new revision and review before retrying. Do not create an extra broad allow to hide an unexpected result: first determine whether another group, a direct user grant or platform authority explains it. Preserve explicit denials and never delete unrelated grants until their legitimate owner has reviewed the effect.

Sources. WorkspaceSecurityController.java:207, GrantRole.java:1.

Example ROOT-SEC-04 — Check Sara’s access without turning the check into a grant

Scenario and inputs. The leave interface is visible to Sara, yet a task or record action is absent. Nadia can administer the relevant workspace security but must distinguish an inherited object decision from Sara's actual participant/row eligibility. Prepare Sara's immutable user ID, the exact object reference and its business function; keep any record contents out of diagnostic screenshots and logs.

Procedure. Use Check access for the specific user and object. The single-object surface is GET /api/workspaces/people-ops/access-check?userId=<sara-user-id>&functionKey=leave_management&objectType=screen&objectId=<interface-id>. Substitute and encode actual references. Read the effective role and source explanation. Then inspect the owning task assignment, current task state and record policy through their authorized surfaces. For a list, use the bounded native access-checks request instead of firing one directory lookup per rendered row.

Expected result. The check reports a current authorization decision; it does not mutate permissions. A permitted interface can still hide a task action for someone who is not an eligible participant, or a field/row that its domain policy excludes. An administrator's successful check cannot replace testing the actual normal-user journey when runtime qualification is required.

Failure and recovery. If Check access is unavailable, preserve the distinction between a policy outage and an explicit denial. Do not render an unavailable result as an allow or issue the forbidden catalog/detail request. Resolve missing business eligibility at its owner rather than promoting Sara to a broad administrator or passing a client-supplied user ID as authentication.

Sources. WorkspaceSecurityController.java:221, WorkspaceSecurityController.java:238, authorization-visibility-policy.md:1.

This manual covers the two-layer organization/security model implemented from docs/workspace-functions-and-inherited-security-plan.md: business functions organize assets INSIDE a workspace, and one unified grants store secures the whole tree — workspace → function → object — through inheritance with per-principal overrides.

Business functions

A function is a required, lightweight attribute on assets plus a small per-workspace table (workspace_functions). It is organization, not isolation: contracts, AI policy, and runtime scoping stay at the workspace boundary, and assets in different functions of one workspace call each other freely. Function-level security gates visibility and editing, never invocation mechanics.

  • Every workspace is born with the undeletable general function (seeded by migration 40 for existing workspaces, by DefaultWorkspaceService.create for new ones, and mirrored by the in-memory repository).
  • Asset tables carry business_function_key TEXT NOT NULL DEFAULT 'general': process/rule/form drafts AND versions. Drafts expose the key on their records; versions keep it on the row only (publish copies the draft's key via the saveVersion(version, functionKey) repository overload).
  • Deleting a function requires it to be empty (409 FUNCTION_NOT_EMPTY with per-kind counts in the message) or an explicit move-assets call first. general can never be deleted (FUNCTION_GENERAL_UNDELETABLE). Function-scope grants are removed with their function.

API

GET/POST         /api/workspaces/{idOrKey}/functions
PATCH/DELETE     /api/workspaces/{idOrKey}/functions/{functionKey}
GET              /api/workspaces/{idOrKey}/functions/{functionKey}/assets
POST             /api/workspaces/{idOrKey}/functions/{functionKey}/move-assets  { toFunctionKey }

Create/edit/delete/move require an effective workspace ADMIN role (platform WORKSPACE_MANAGE and '*' bypass through resolution). Listing requires any effective access or WORKSPACE_VIEW.

Asset create/update APIs accept businessFunctionKey (blank defaults to general); process and form list APIs accept a function filter query parameter. Export packages carry a functions section plus per-asset keys; import creates missing functions in the target workspace before assets land, so no import produces dangling keys.

The assist endpoints accept an optional functionKey that steers the model's vocabulary ("the expression belongs to the 'recruitment' function") — context only, never a policy or model switch.

Inherited security

The grants store

scoped_grants (migration 39) is the ONE store for every scope level:

workspace_id | scope_type (WORKSPACE|FUNCTION|OBJECT) | scope_id
principal_type (USER|GROUP) | principal_id | role (ADMIN|EDITOR|VIEWER|NONE)

workspace_members migrated into it and was dropped; WorkspaceRepository.saveMember/findMembers/isMember are views over workspace-scope USER grants only. GROUP principals (identity groups, nested semantics included) are valid at every level. A workspace-scope GROUP grant of VIEWER or above admits every effective member (SCRUM-2175). Direct USER workspace grants are exceptions, not a ticket (SCRUM-2171). NONE is a stored value meaning "revoked at this scope for this principal" — it is only legal below workspace scope (GRANT_NONE_AT_WORKSPACE otherwise; remove the grant instead).

In Studio, the workspace's Explore tab lists these direct USER members under "Direct user access". A workspace admin (or platform bypass) adds and removes them there; anyone else who can open the workspace sees the same list read-only, with no role picker, Add members or Remove control rendered (DEC-16, SCRUM-3747). The server still refuses add and remove to a non-admin.

Resolution (the pinned contract)

EffectiveAccessService.effectiveAccess(userId, workspaceId, functionKey?, objectId?) implements, and WorkspaceSecurityResolutionTest pins:

  1. Principals = the user + all groups the user is an effective member of (nested groups resolve through ancestors).
  2. Scopes walk from the node UP: OBJECT → FUNCTION → WORKSPACE. The FIRST scope containing ANY entry for the actor's principals resolves the role and STOPS — nearest scope wins; better roles above are ignored for matched principals. This is what makes overrides real.
  3. Within the winning scope a USER entry beats all GROUP entries; among GROUP entries the MOST PERMISSIVE role wins.
  4. No entry at any scope → no access (deny by default).
  5. '*' / WORKSPACE_MANAGE bypass as effective ADMIN (platformBypass=true in results).

Deliberate properties: overrides are per PRINCIPAL, not node snapshots (no SharePoint-style broken-inheritance drift — workspace changes for other principals keep flowing down past an override); there is no cross-principal deny (to hard-block one person, place a USER-level NONE — it beats their groups at that scope); the last effective workspace ADMIN (a USER ADMIN grant, or a GROUP ADMIN grant whose group is active and has members) can neither be removed, downgraded, nor overridden to NONE below (409 LAST_WORKSPACE_ADMIN). An empty GROUP ADMIN grant is not a recovery seat.

Resolution is memoized per thread; WorkspaceContextFilter clears the cache at request end and grant mutations clear it immediately so same-request reads always see their own writes.

Enforcement

  • SecuredWorkspaceService now authorizes through effective roles: view = effective VIEWER or WORKSPACE_VIEW; rename/archive/member management = effective ADMIN. A platform admin who is also a non-admin member is never locked out (fixes the pre-grants denial-order bug). No relationship at all presents as WORKSPACE_NOT_FOUND so existence is not leaked.
  • WorkspaceContextFilter admits actors with ANY effective grant — including group-derived ones — or the platform bypass.
  • Asset services keep their platform-permission checks and add the effective-role layer via AssetAccessGuard: create = EDITOR at the target function; edit/publish = EDITOR at the object; view/run = VIEWER. List endpoints post-filter by effective VIEWER. Rules gained SecuredRuleDefinitionService; its lookups/execution enforce only when a request actor exists — service-task executors and cross-workspace contract calls can run on worker threads without an HTTP actor. This does not waive governed step authorization: supported executors resolve their trusted requester/run-as context and reauthorize the exact resource through their native boundary (for example document conversion). Do not use actor absence as a general authorization bypass.
  • Object coordinates: process drafts use the draft id, published processes the definition id; rules the definition id; forms the form key.
  • Process instances and an explicit NONE (spec 125). The platform permission PROCESS_INSTANCE_VIEW is a ceiling, not a bypass: opening a case also needs effective VIEWER on its process definition (ProcessInstanceObjectAccessGuard), so a USER NONE, or GROUP entries that are all NONE, on the definition (or, for a registered state flow, on its lifecycle definition when the state flow has no entry of its own) refuses the case. The set-based readers (Lifecycle data, the Live view, Monitor, Model KPI, the publish census, the process activity data source) apply the same definition NONE: the holder of the global permission then sees only the cases an instance grant or an open task gives them, like any reader without it (opening a case shared only by an instance grant still answers 403). A workspace ADMIN and the platform bypass are not stopped by a definition NONE. Exception: a NONE at business-function scope is applied when a case is opened but not by the set-based readers (SCRUM-3401).

Security panel API

GET    /api/workspaces/{idOrKey}/grants?scopeType&scopeId&functionKey   → rows with provenance
PUT    /api/workspaces/{idOrKey}/grants        { scopeType, scopeId, principalType, principalId, role, functionKey? }
DELETE /api/workspaces/{idOrKey}/grants?...    (below workspace scope this is "restore inheritance")
GET    /api/workspaces/{idOrKey}/access-check?userId&functionKey&objectId

Panel rows mark inherited, originScope, and overridesInherited (with the shadowed inheritedRole) so the UI can render provenance. An OBJECT panel walks the object's security parents first, nearest first, exactly as enforcement does (WorkspaceObjectGrantResolver.parent): a lifecycle's state flow shows the lifecycle's grants (spec 114), a document its folders and cabinet. Such a row is inherited with originScope OBJECT, originScopeId the parent's id, and originScopeName the parent's display name (SCRUM-3406), so a NONE on lifecycle L shows on L's state flows as the NONE it is, with a tooltip naming the parent object (Inherited from the parent object <DisplayName>), never as the workspace role it hides (spec 126 O4, SCRUM-3396). As in enforcement, a principal whose workspace grant is ADMIN is shown ADMIN inherited from the workspace on every object panel, whatever a parent or the function says. A parent's rows are listed only to a caller who may read that parent's own panel (ADMIN there, or WORKSPACE_VIEW with an effective VIEWER there). Each parent is judged on its own: a refused parent is skipped, and a grandparent the caller may read is still listed. A principal the refused parent governs falls back to the row of the nearest ancestor the caller may read, else to its function or workspace row, and the refused parent's principals, roles and grantors are not shown by the panel. When every parent is refused the panel is exactly as before spec 126. Such a fallback row can differ from the enforced role in either direction: a refused parent's NONE is shown as the workspace role, and a refused folder's ADMIN for P is hidden, so a direct VIEWER for P on a document in it reads as "Overrides inherited Viewer" although deleting it raises P to the folder's ADMIN. Whenever any security parent in the walk is withheld, the panel sets parentGrantsWithheld = true (computed before reading the parent's grants, disclosing nothing about whether the parent holds grants), the Studio panel displays "Security from a parent object is not shown to you.", and deleting (restoring inheritance) or downgrading a direct grant row on that object warns that removing or lowering the direct override may change access in ways the caller cannot see and requires confirmation (SCRUM-3408). On a state flow such a row is display-only, because grant changes on a state flow are refused. The secured service decides this filter itself and ignores any filter a caller passes. Check access uses the same parent-panel rule after the caller is admitted. When the winning grant sits on a parent the caller may read, AccessCheckResult carries scopeName and Check access names that parent by display name ("revoked at <ParentName>", "granted at <ParentName>", SCRUM-3406). When the winning grant sits on a parent the caller may not read, the role stays and the provenance is the sentence "inherited from a parent object you cannot view", with no parent id, name (scopeName = null), principal, grantor, or time. A grant on the checked object and a workspace or function grant keep their provenance. A caller who may not run Check access still receives WORKSPACE_ACCESS_DENIED and no body (SCRUM-3409). Mutations require effective ADMIN at the target node; panels and Check-access additionally open to WORKSPACE_VIEW holders so read-only auditors can run access reviews.

Every grant upsert/removal is audited (WORKSPACE_GRANT_UPSERTED/REMOVED with scope path + old/new role); function lifecycle events audit as WORKSPACE_FUNCTION_*.

Studio UI

The workspace detail gained a Security tab (grants table for users AND groups + the Check-access debugger), the Build tab groups assets by function with filter chips and per-asset Security drawers, Settings gained the function management panel (create/rename/move-assets/ delete-with-guard, per-function Security drawer), and the New Workspace wizard's Structure step scaffolds REAL functions from templates. Inherited rows render dimmed with an "Inherited from workspace" chip ("Inherited from the parent object" for a row from a security parent) and an Override action; overridden rows show "Overridden here" plus Restore inheritance. Check access answers with a provenance sentence: "Editor — inherited from the workspace via group hr-builders". When that role comes from a parent the caller may not read, the sentence is "Editor — inherited from a parent object you cannot view" and names no parent, principal, grantor, or time.

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