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.
Workspaces
Practical guide and worked examples
Choose the correct boundary
A workspace groups authored assets, runtime data and scoped access. Its machine key is a reference coordinate; its human name is a display name. Use the returned id when an API or another object requires an ID. Do not treat a username, a workspace name or a URL label as an interchangeable identifier.
For the connected tutorials, create a disposable People Operations workspace with key people-ops. Nadia is the builder, Mohammad is the employee and Sara is the manager. Those names are fictional people, not pre-seeded accounts. Resolve their real account IDs in the reader's admitted environment. The workspace and its default general business function are created together, and the production composition grants the authenticated creator the workspace Admin membership. A creation permission is not a platform-wide administration bypass.
| Operation | Input to obtain or retain | Important distinction |
|---|---|---|
| Create | key, name, optional description |
Requires WORKSPACE_CREATE or WORKSPACE_MANAGE, plus authoring admission. |
| Rename | name and/or description |
Does not rename the machine key. |
| Add member | Actual userId, ADMIN/EDITOR/VIEWER |
Membership is not a grant to every record, task or identity profile. |
| Environment | DEV, then STAGING, then PRODUCTION |
A forward lifecycle classification, not a deployment copy operation. |
| Archive / unarchive | Existing workspace coordinate | Changes lifecycle state; it is not deletion. |
| Delete | Exact confirmKey, archived workspace, no blockers |
Separate platform-management authority; retain applicable data/evidence holds. |
Start with creation and membership, then read the function and security guide. Use the application-user guide for published App Shell access. Giving an end user a workspace Editor role merely to make an app work is not the application access procedure.
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-WS-01 — Create the People Operations development workspace
Scenario and inputs. Nadia has an ordinary authenticated builder session with workspace-creation and authoring admission. She needs a new isolated teaching workspace, not a copy of a production workspace. The chosen key is people-ops; the display name is People Operations. Confirm that the key is not already occupied before interpreting a creation error as a permission issue.
Procedure. In Studio, create the workspace and enter the three fields below. The equivalent complete JSON request body is:
POST /api/workspaces
Content-Type: application/json
{"key":"people-ops","name":"People Operations","description":"Synthetic leave-request learning workspace"}
Retain the returned id, key, environmentState, status and creation time. Resolve it with GET /api/workspaces/people-ops, then inspect its members and functions through the authorized surfaces. All later tutorial references must use this workspace's actual returned coordinates.
Expected result. Creation starts in DEV and ACTIVE. The secured create transaction includes the default function seed; production wiring records the authenticated creator as Admin. Reopening the workspace shows the saved display name. This does not create a leave model, an App Shell or employee accounts.
Failure and recovery. WORKSPACE_KEY_EXISTS means the key is already used: inspect the existing authorized workspace or choose another key rather than repeating creation under different credentials. Missing creation authority or authoring admission must be resolved by the legitimate administrator; changing the header to impersonate root is not a recovery path.
Sources. WorkspaceController.java:53, SecuredWorkspaceService.java:80, DefaultWorkspaceService.java:148.
Example ROOT-WS-02 — Add Sara without confusing membership and identity visibility
Scenario and inputs. The people-ops workspace exists. Nadia has effective workspace Admin authority and has resolved Sara through the permitted identity directory. The sample value <sara-user-id> below represents Sara's actual immutable account ID, not the text sara. The goal is to let Sara inspect the teaching workspace while keeping build and application-user privileges separate.
Procedure. Read GET /api/workspaces/people-ops/members first. If the required membership is absent, add it through the members panel or this body after substituting Sara's returned ID:
POST /api/workspaces/people-ops/members
Content-Type: application/json
{"userId":"<sara-user-id>","role":"VIEWER"}
Reload the members table and compare userId, resolved displayName/username, role and active. Use a normal Sara session to inspect the intended surface; the administrator's members response is not proof of Sara's business-task eligibility.
Expected result. Sara receives the requested workspace membership. The response carries display metadata when directory visibility permits it. Restricted profiles can be omitted from a non-administrator list; a missing row in that filtered list is not permission to disclose the profile through another endpoint. A Viewer membership does not assign Sara a human task or admit every record row.
Failure and recovery. If the account cannot be selected, resolve identity existence and visibility with the authorized owner before adding a raw ID. If Sara sees the workspace but cannot perform a task or open an application, inspect those domain/application grants separately. Do not upgrade her to Admin to conceal a missing task candidate or app-runtime contribution.
Sources. WorkspaceController.java:56, WorkspaceController.java:168, SecuredWorkspaceService.java:26.
Example ROOT-WS-03 — Understand a forward environment promotion
Scenario and inputs. Nadia is working in the disposable People Operations workspace and has explicit authority for its lifecycle. She wants to classify the already prepared workspace as staging. This is a workspace-state change: it neither exports assets to another server nor establishes production readiness. Retain the current environmentState and status before changing anything.
Procedure. Read GET /api/workspaces/people-ops and confirm an active DEV workspace. In its authorized settings, request the next state. The API body is:
POST /api/workspaces/people-ops/environment
Content-Type: application/json
{"environment":"STAGING"}
Read the same workspace again and compare the state. Use a separate test workspace if another tutorial still requires a DEV target. For a real cross-server promotion, follow the signed-release and target-admission procedure in the deployment manual.
Expected result. The state becomes STAGING; the change is audited with the old and new environment. Current transitions are DEV → STAGING → PRODUCTION. Requesting the already current environment returns the current workspace. The default/system workspace and non-active states have their own restrictions. None of these outcomes copies data or replaces a release import.
Failure and recovery. A jump directly from DEV to PRODUCTION or a backward transition is refused with WORKSPACE_ENVIRONMENT_TRANSITION_INVALID. Do not edit database state or send an invented TEST enum. Reassess the intended lifecycle, keep the original workspace intact and use a correctly admitted separate target when a fresh development state is needed.
Sources. WorkspaceController.java:62, DefaultWorkspaceService.java:276, WorkspaceEnvironment.java:1.
Example ROOT-WS-04 — Archive and restore while keeping deletion separate
Scenario and inputs. The training workspace is no longer in daily use, but its definitions, records and evidence must be retained. Nadia has workspace Admin authority. There may still be published contracts or dependent objects, so the intended operation is archival, not destruction. First identify the exact key and current state and retain any ongoing work according to the workspace's operating policy.
Procedure. Open the workspace settings, inspect current state and choose the authorized archive action. The API equivalent is POST /api/workspaces/people-ops/archive. Reload the workspace to observe ARCHIVED. When the training exercise resumes, use POST /api/workspaces/people-ops/unarchive and reload it again. Keep any migration, provider or runtime execution in the other tutorials subject to its separate authority; an archived workspace is not a safe sandbox merely because it is hidden from an ordinary list.
Expected result. Archive moves an active workspace to ARCHIVED; unarchive moves an archived workspace to ACTIVE. These operations retain the workspace identity and stored content. Deletion is a separate platform-management decision requiring an archived workspace, exact confirmation of its key and no reported blockers. The deletion implementation preserves its own audit/lifecycle semantics rather than treating archive as a file-system cleanup command.
Failure and recovery. Calling archive on a non-active workspace or unarchive on a non-archived workspace reports a state conflict. Reload the current state before choosing the next action. If deletion is blocked by dependencies or evidence retention, keep the archive and resolve the named dependencies with their owners; never delete unrelated data or rewrite the confirmation to bypass the gate.
Sources. DefaultWorkspaceService.java:309, DefaultWorkspaceService.java:334, SecuredWorkspaceService.java:153.
Document status: Current workspace reference. Verified against
origin/masteron 2026-08-14. Migration numbers below identify the historical introduction of a contract; the ordered migration directory is the current schema source of truth.
Workspaces are isolated logical containers for solutions: definitions
(processes, rules, forms) and their runtime instances live inside exactly one
workspace. The same key — vat, expense-approval — can exist independently
in different workspaces, each with its own version chain. Implemented in the
W0+W1 slice (migrations 25–26). Cross-workspace contracts, bindings,
workspace AI policy, usage attribution, and export/import promotion are also
implemented and described below.
The default workspace and backwards compatibility
Migration 25 seeds workspace default
(id 00000000-0000-0000-0000-000000000001); migration 26 backfills every
existing definition and runtime instance into it. Requests without an
X-Workspace-Id header run in the default workspace, so all pre-workspace
clients, scripts and tests behave exactly as before.
Request scoping
X-Workspace-Id: <workspace id or key> scopes a request. The
WorkspaceContextFilter (after authentication, before everything else)
resolves the workspace and enforces access:
- any reference the caller is not admitted to → 404
WORKSPACE_NOT_FOUNDwith the neutral message "This doesn't exist or you don't have access to it." That covers an unknown or deleted workspace, the System Cabinet workspace, and an existing (active or archived) workspace the signed-in caller is not a member of and cannot enter through WORKSPACE_MANAGE. Platform administrators hold*and may enter any workspace. The answer is byte-identical in every case and never repeats the requested key, so it cannot be used to probe which workspaces exist (SCRUM-3797, DEC-15). - a different workspace named in the path (
/api/workspaces/{ref}/..., for example/grants,/security-objects,/eligible-principals,/access-check,/members,/functions, or the workspace itself) must pass the same admission as the header workspace. A path workspace the caller may not enter gets the same neutral 404 as a missing one, so being scoped to your own workspace does not let you probe another one through the path (SCRUM-4372). Members of both workspaces and platform administrators keep working across workspaces; the path workspace's archived state stays the endpoint's decision. - archived workspace, write by an admitted caller → 403
WORKSPACE_ARCHIVED. "Archived" is only ever revealed to a caller who was admitted first. - the access check itself could not run → 503
ACCESS_UNCHECKEDwithRetry-After(an outage, never a refusal).
Refusals inside a workspace the caller may enter (for example 403
WORKSPACE_ACCESS_DENIED or ACCESS_DENIED from grant administration) are
unchanged; they are not workspace-existence answers.
The resolved scope travels in WorkspaceContext (a ThreadLocal holder in
com.inflowai.platform.common, mirroring how SecurityContextHolder carries
the actor). It always falls back to the default workspace.
What is scoped
Scoping lives in the repositories — explicit workspace_id predicates, no
interceptor magic:
- Definitions (process, rule, form): creates stamp the current workspace;
drafts, key-based lookups,
nextVersionand searches are filtered. Uniqueness is(workspace_id, key, version)— the old global(key, version)indexes were replaced in migration 26. - Runtime instances: stamped with the workspace at start (the stamp is never overwritten by later saves); instance search is scoped.
- Id-based version lookups stay global: ids are unguessable UUIDs and the runtime restores instances by id from background threads.
Background threads adopt the instance's workspace
Timers, service-task workers, and message handlers carry no request scope. Two mechanisms keep them correct:
WorkflowRuntimeServiceImpl.restoreEngineStateresolves the process model insideWorkspaceContext.runAs(instance's workspace, ...)— resume, signal, and cancel work from any thread.RuleEvaluateServiceTaskExecutorexecutes the rule inside the calling instance's workspace (viaProcessInstanceRepository.findWorkspaceId), so workspace-scoped rule keys resolve against the right workspace.
Pinned by WorkspaceIsolationTest.ruleTaskAdoptsTheWorkspaceOfTheCallingInstance.
Archived workspaces are frozen. The request filter refuses scoped API calls,
cross-workspace contract invocation refuses aliases whose owner workspace is
archived (CONTRACT_OWNER_ARCHIVED), and timer/service-task/agent workers
release claimed work for archived instances instead of executing or failing it.
Unarchiving lets the same work become claimable again.
API
POST /api/workspaces {key, name, description} (WORKSPACE_MANAGE);
GET /api/workspaces — all workspaces for WORKSPACE_MANAGE holders, the
workspaces the caller can enter otherwise; GET /api/workspaces/{idOrKey} and
GET /api/workspaces/{idOrKey}/members — only for a caller admitted to that
workspace (effective VIEWER through membership or grants, or the platform
bypass * / WORKSPACE_MANAGE). Global WORKSPACE_VIEW alone (for example the
predefined read-only-auditors and application-administrators groups) does
not admit a caller to a workspace: whether the workspace is named in
X-Workspace-Id (SCRUM-3797) or in the path (SCRUM-4372), such a caller gets
the neutral 404 for a workspace they are not admitted to; members: GET|POST /api/workspaces/{idOrKey}/members,
DELETE /api/workspaces/{idOrKey}/members/{userId} {userId, role} with
roles ADMIN | EDITOR | VIEWER (manage operations need WORKSPACE_MANAGE).
Being a member is itself the grant to view the workspace.
Workspace keys: lowercase letters, digits, dashes, 3–64 chars, unique.
Lifecycle endpoints:
PATCH /api/workspaces/{idOrKey}{name?, description?}renames display fields only; the key is permanent. Requires ADMIN membership of that workspace or WORKSPACE_MANAGE.POST /api/workspaces/{idOrKey}/archiveand/unarchivetoggle the reversible freeze state. Requires ADMIN membership or WORKSPACE_MANAGE.DELETE /api/workspaces/{idOrKey}{confirmKey}soft-deletes an already archived workspace. Delete requires WORKSPACE_MANAGE and exact key confirmation. It records statusDELETED, internally renames the stored key to free the original key for reuse, revokes owned contracts, and removes grants. Historical rows keep their workspace ids for audit/compliance.
Delete refuses the default workspace, active workspaces, running/suspended
process instances, and active bindings from other workspaces to contracts owned
by the workspace. Blocked deletes return 409 WORKSPACE_DELETE_BLOCKED with a
structured blockers array.
Historical verification example (2026-07-02)
Same rule key vat published in default (amount * 0.15) and finance
(amount * 0.05); POST /api/rules/vat/execute with amount=100 returns
15.00 without the header and 5.00 with X-Workspace-Id: finance — each
workspace's version chain advancing independently with stable definition ids.
Unknown workspace → 404; non-member → 403 at the time (since SCRUM-3797 the same 404 as an unknown workspace); after membership → 200. The
original W0/W1 candidate recorded 544 passing tests. That dated count is
historical evidence, not validation of the current repository head.
Scoped runtime lists and attribution (W2)
Task search returns only tasks whose process instance belongs to the current
workspace (tasks without a matching instance row stay visible everywhere, so
standalone fixtures behave as before). Open-incident lists are scoped the
same way; incident rows inherit their instance's workspace at insert.
rule_execution_records carries workspace_id (where the rule ran) and
caller_workspace_id (set only for cross-workspace contract calls) —
migration 27.
Cross-workspace contracts (W3)
Design: docs/workspace-contracts-addendum.md. Migration 28 adds
workspace_contracts, workspace_contract_grants,
workspace_contract_bindings.
A contract publishes ONE asset of a workspace (kinds PROCESS, RULE — DATASET / AGENT_TOOL / FORM are declarable, their invocation paths land with their subsystems) under a contract key, pinning a target version or following latest. Visibility is LISTED (explicit grants only) or ALL (the platform-utility pattern). Consumers import by binding a local alias; assets reference only the alias, so promotion re-binds per environment without asset edits. The grant is re-checked on EVERY invocation — revocation bites on the next call. Publishing/granting/binding requires an ADMIN or EDITOR membership of the current workspace (or WORKSPACE_MANAGE).
API (all endpoints act on the current X-Workspace-Id workspace):
POST /api/contracts (publish), GET /api/contracts/published,
GET /api/contracts/catalog (what other workspaces expose to you),
POST /api/contracts/{key}/revoke, GET|POST /api/contracts/{key}/grants,
DELETE /api/contracts/{key}/grants/{consumer},
GET|POST /api/contracts/bindings, DELETE /api/contracts/bindings/{alias}.
Invocation from processes:
- Rules:
service.rule.evaluateacceptsruleAliasinstead ofruleKey. The rule executes in the OWNING workspace (internals never leak), audited with owner + caller workspaces. - Processes: new
service.process.starttask (implementationprocess-start, catalog count now 243) starts another process — same-workspace viaprocessKey, cross-workspace viaprocessAlias— fire-and-forget; outputsstartedProcessInstanceIdandstartedWorkspaceId. The started instance is stamped with the owner workspace. Request/reply (caller waits for completion) arrives with the BPMN message-event slice. Config:businessKey,inputVariables(names to forward; all variables when absent).
Error codes: CONTRACT_NOT_GRANTED, CONTRACT_REVOKED,
CONTRACT_ALIAS_NOT_BOUND, CONTRACT_KIND_MISMATCH,
CONTRACT_TARGET_NOT_FOUND, CONTRACT_FORBIDDEN — human-readable messages,
403/404/400 mapping in the API.
Per-workspace AI policy and usage attribution (W4)
Migration 29 adds workspace_ai_policies and workspace_ai_usage. Every AI
gateway call is checked against the CHARGED workspace's policy — the
contract caller during a cross-workspace call (caller pays), the current
workspace otherwise. A policy has model/provider allow-lists (empty = allow
everything), an enabled kill switch, and a monthly token limit
(monthlyTokenLimit, empty = no limit): a soft cap refusing calls once
month-to-date total tokens reach it (SCRUM-4817 replaced the USD budget; migration
000416 adds the token columns and old USD columns stay unused). Refusal codes:
AI_DISABLED_FOR_WORKSPACE, AI_MODEL_NOT_ALLOWED_FOR_WORKSPACE,
AI_PROVIDER_NOT_ALLOWED_FOR_WORKSPACE, AI_WORKSPACE_BUDGET_EXCEEDED.
After each successful call, usage is recorded with its token counts, the charged workspace, and the workspace it executed
in. Usage accounting never fails the AI call.
API: GET|PUT /api/workspaces/{idOrKey}/ai-policy (PUT needs an ADMIN
membership or WORKSPACE_MANAGE — limits are a governance control, EDITOR is
not enough), GET /api/workspaces/{idOrKey}/ai-usage → month-to-date tokens (monthToDateTokens) +
recent entries.
Export / import — workspace promotion (W4)
GET /api/workspaces/export snapshots the current workspace: the latest
PUBLISHED version of every process, rule and form, the contracts it
publishes, and its dependencies — every imported contract alias with the
contract it was bound to. Secrets are never included (secretsIncluded: false; connector credentials stay in the environment — full hydration
prompts arrive with the credential vault). Runtime state is never exported.
The current package format is version 3. It preserves each exported rule
version's ordered rule-input contract (name, type, required/cardinality flags,
and description). Every version 3 rule must carry an inputs array; an empty
array is explicit, while an omitted property is rejected as possible contract
loss. Version 2 packages remain importable and an omitted property is
interpreted as an empty rule-input contract. Packages from newer, unsupported
versions are rejected rather than guessed at.
Format 3 exports legacyScopeCompatibility as inventory evidence for immutable
pre-contract rules that used exact-key ri! or local! syntax. The package is
not signed, so import never trusts that bit as provenance: legacy-scoped rules
from format 2 or 3 fail with WORKSPACE_IMPORT_INVALID_RULE_INPUTS before any
asset is created. Format 2 rules using ordinary bare-name compatibility remain
importable. Only an exact-body restore from a local immutable version preserves
the marker; a legacy-scoped body change is rejected and modernization clears it.
POST /api/workspaces/import {exportPackage, bindings: {alias: contractId}} imports into the current workspace. Validation runs FIRST and
fails fast creating nothing: key conflicts →
WORKSPACE_IMPORT_CONFLICTS; a dependency alias without a valid, granted
contract in this environment → WORKSPACE_IMPORT_UNRESOLVED_DEPENDENCIES;
an invalid rule-input contract or unverified historical-scope marker →
WORKSPACE_IMPORT_INVALID_RULE_INPUTS.
Then rules, forms and processes are created and published, contracts are
re-published (grants are NOT exported — re-grant consumers explicitly; the
report warns about this), and every dependency alias is re-bound to the
contract chosen for this environment. That alias re-binding is the whole
point: assets reference aliases, so Dev → Staging → Production needs no
asset edits.
Business calendars (spec 077)
Each workspace owns its business calendars; no calendar is shared across workspaces. They define working time for business-time reporting: a named IANA time zone, up to 4 working periods per weekday (a weekday without periods is a weekend day), holidays (days off, one date or a range) and exceptions (dates whose 1–4 periods replace the working week; a holiday wins on the same date). Exactly one calendar per workspace is the default: it is used by process insights and forecast, by the Process tasks source, by every Lifecycle data connection set to "Default calendar", and its zone is the workspace zone for date groups. Migration 000307 turned each existing workspace calendar into its default ("Workspace calendar"); every other workspace, and every workspace created later, gets a default "Standard" calendar (Monday–Friday 09:00–17:00 UTC) inside the workspace-creation transaction.
The Studio workspace page, under Settings → Business calendars, lists the calendars (default badge, zone, working-week summary, To review count, Used by), and lets an administrator create (Standard week or a copy), duplicate, edit, delete and mark one as the default. Holiday and exception dates can be entered as Gregorian or Hijri (Umm al-Qura); the converted Gregorian date is shown and stored. Import public holidays previews a country's holidays for one year (Saudi Arabia, the United Arab Emirates, Bahrain, Kuwait, Oman and Qatar), skips dates already in the calendar, and adds the rest as To review; administrators confirm them one by one or per import. Moon-sighted Islamic holidays must be confirmed every year; the holiday library is used only at import, never when business time is calculated. Changing the default, or saving (or importing into) a calendar that is the default or is picked by a connection, first warns that business times already shown are recalculated, and that date groups move when the default's zone changes. The default calendar and a calendar picked by any draft or published Lifecycle data connection cannot be deleted; the refusal names the interfaces the actor may open and counts the others.
API: GET /api/business-calendars (list), GET /api/business-calendars/{id},
GET /api/business-calendars/choices (ids, names and the default flag only,
for the Lifecycle data picker), plus create, update, mark as default, delete,
holiday import (preview and import) and confirm. Definitions need
PROCESS_CALENDAR_VIEW; /choices accepts PROCESS_CALENDAR_VIEW or
SCREEN_MANAGE; every change needs PROCESS_CALENDAR_MANAGE and writes an
append-only BUSINESS_CALENDAR_* audit event with the old and new value. The
routes answer whenever the process module is on. GET/PUT /api/process-calendar keep working on the default calendar
and refuse (409 PROCESS_CALENDAR_NOT_REPRESENTABLE) a change they cannot
express. The user guide, with screenshots, is
Lifecycle reporting §24;
security evidence is in docs/compliance-readiness.md.
Current limitations
Request/reply process contracts over message events (BPMN Phase 0), DATASET / AGENT_TOOL / FORM contract invocation paths, contract-level version history (a contract republish updates in place today, keeping its id and grants), and credential-vault-backed secret hydration at import remain separate limitations. Studio already exposes authorized workspace settings, environment changes, archive/unarchive and guarded deletion. Business-state blocks retain their reasons; controls the user may not administer are absent.