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.

Current behavior note: This preserved technical body predates the separate Inject simulated data operation. Its “zero-side-effect” and side-effect-isolation statements apply to modeled Interactive Token Sandbox and Monte Carlo runs, not to physical data injection. Injection writes synthetic lifecycle/state-flow instances, tasks, sample documents, attachments and KPI projections into the selected workspace. It requires separate permissions, and purging a batch does not remove the append-only audit trail. Follow the practical guide for the current write boundary, safe-workspace rules and purge limits.

Current behavior update — 11 November 2026. Sandbox human-task decisions can now be synthesized from downstream gateway conditions. With automatic task completion enabled, both Step and Play ask the server for a deterministic, forward-verified outcome; with it off, consultants can inspect inferred outcomes and heuristic probability badges. Input-bound read-only form fields are not submitted as answers. These weights create synthetic route variety and are not observed approval rates or business policy. Physical data injection is more narrowly scoped: it accepts only a resolvable published lifecycle revision; drafts and standalone process flows are rejected. See the current gateway and published-lifecycle contracts in the Simulation Studio feature specification and the practical guide. The historical body below remains preserved from its stated baseline. Gateway option weights depend on available paths; common zero-config mixes include 80/20 for primary/alternate, 70/20/10 for primary/alternate/default, and 65/20/10/5 when all four categories are feasible. They are not observed approval rates.

Simulation Studio (SCRUM-3398)

Simulation Studio provides a sandboxed, zero-side-effect consultant environment for testing, explaining, branching, and regression-verifying any Lifecycle or Process Flow model before or after publication. Current source owners are SimulationService, MonteCarloSimulationRunner, ProcessSimulationTwinController, and LifecycleJourneySimulator.tsx.

1. Capability-Gated Entry & Revision Pinning (FR-01, FR-08)

  • Authorized Entry: The Simulate action in the Lifecycle Designer (data-agent-id="lifecycle-simulate-btn") and Process Flow Designer (data-agent-id="pd.flow.tb.simulate") is rendered only when the current user holds scoped process:read or process:update capability for the active workspace and object. Unauthorized users see neither the control nor any simulation catalog/session requests.
  • Exact Revision Pinning: Every simulation session pins its exact source (DRAFT snapshot or PUBLISHED revision), computes a deterministic SHA-256 pinnedRevisionHash, and records all referenced subprocess and form definitions (referencedDefinitions). Subsequent draft edits or new publications never mutate an in-flight simulation session or saved report.
  • Side-Effect Isolation: Simulation runs never write to production case tables, never enqueue live human tasks, and never invoke external HTTP connectors, plugins, messaging brokers, or notification channels. Every service/script/external step records a SimulationExternalOperationReceipt indicating whether it was satisfied by an explicit fixture (SIMULATED_WITH_FIXTURE), evaluated internally (INTERNAL_EVALUATED), or flagged as missing a fixture (UNRESOLVED_MISSING_FIXTURE).

2. Scoped Variable Inspector & Presence Semantics (FR-02, FR-10)

The Scoped Variable Declarations inspector (SimulationVariableDiffTree.tsx) surfaces all declared variables across LIFECYCLE, PROCESS, and SUBPROCESS scopes from step 0 onward without seeding synthetic defaults for unset variables:

Presence Badge Meaning
UNSET Declared on the lifecycle/process/subprocess model, but no initial input, default, or task/service output has written to it yet.
DEFAULTED Populated from the declaration's configured defaultValue at session start (origin: DECLARED).
NULL Explicitly written with a null value (distinct from UNSET).
FALSE Explicitly written boolean false (never conflated with UNSET or NULL).
ZERO Explicitly written numeric 0 (never conflated with UNSET or NULL).
EMPTY_STRING Explicitly written "" (length 0, distinct from UNSET and NULL).
WRITTEN Written by start input, human task output mapping, script/service fixture, or subprocess output propagation.
  • Provenance & Shadowing: Each variable row displays its type, scope (LIFECYCLE, PROCESS, or SUBPROCESS:<nodeId>), origin (DECLARED, START_INPUT, TASK_OUTPUT, SCRIPT_OR_SERVICE, RUNTIME_SYNTHETIC), and a clickable link to the lastWriterNodeId and lastWriterBinding. When a subprocess declares a variable with the same name as a parent scope variable, both rows remain distinct and display Shadows / Shadowed by indicators.

3. Interactive Human-Task Action & Output Mapping (FR-03)

When a simulation token reaches a userTask, execution pauses and exposes a SimulationPendingHumanTask card (data-agent-id="sim-pending-task-card-<nodeId>"):

  • Configured Actions & Custom Forms: Consultants can click any configured task outcome button (data-agent-id="sim-task-action-<nodeId>-<actionId>"), edit typed form fields (data-agent-id="sim-task-field-<nodeId>-<fieldName>"), or test the missing-decision path via Step Without Decision (UNSET) (data-agent-id="sim-task-omit-<nodeId>").
  • Generated Single Approval Parity: Matches runtime form normalization—selecting Approve or Reject writes title-case "Approved" or "Rejected" to the task's decision field before applying the configured output mapping (activity.output.form.decision.target / activity.output.decision.target) to the target process variable. Custom forms preserve their exact configured values.
  • Full Binding Operations: Supports SET, ADD / APPEND, REMOVE, and AT_INDEX (indexExpression), plus UPPER, LOWER, TRIM, NUMBER, and BOOLEAN transforms.

4. Gateway & Transition Routing Explainability (FR-04, FR-10)

Whenever a token evaluates an Exclusive (XOR), Inclusive (OR), or Lifecycle state transition gateway, Simulation Studio records a SimulationGatewayObservation using the same expression semantics as runtime (ProcessEvaluationContext.withDeclaredNulls and InflowExpressionEvaluator):

  • Per-Branch Evaluation Table: Lists every outgoing sequence flow in evaluation order with its condition expression, actual operand values, operand presence state (WRITTEN, UNSET, NULL, etc.), producer node/binding link, and evaluation status (TRUE, FALSE, SKIPPED, MISSING, INVALID, DEFAULT_SELECTED, or UNCONDITIONAL).
  • Missing Decision & No-Path Diagnosis: If a gateway condition references a declared variable that is still UNSET and no default branch matches, the branch is marked MISSING and the gateway reports NO_PATH_ERROR (ENGINE_GATEWAY_NO_PATH) with a clear explanation of which variable was unset and which upstream task or binding was expected to write it.

5. Non-Destructive Rewind, Run Branching & Idempotent Stepping (FR-05)

  • Non-Destructive Rewind: Rewinding or scrubbing the timeline (POST /api/process-simulation/sessions/{id}/rewind) repositions currentStepIndex while preserving all later snapshots for read-only inspection.
  • Run Branching (Forking): Clicking Branch Run (data-agent-id="sim-btn-branch-from-step" / POST /api/process-simulation/sessions/{id}/fork) creates a child session anchored at parentSessionId and forkedFromStepIndex so consultants can explore an alternate human action or fixture without overwriting the baseline run.
  • Idempotent Step Commands: Every step command carries a commandId (commandKey) and expectedStepIndex. Duplicate retries return the cached snapshot without double-stepping; stale step indices fail with 409 SIMULATION_STEP_CONFLICT.

6. Saved Scenarios, Assertions & Revision Comparison Reports (FR-06, FR-07)

  • Reusable Scenarios & Regression Suite: Consultants can save named scenarios (POST /api/process-simulation/scenarios) containing initial variables, fixtures, human-task step actions, virtual-time advances, and assertions (VARIABLE_EQUALS, VARIABLE_PRESENCE, TRANSITION_TRAVERSED, GATEWAY_OUTCOME, TERMINAL_STATUS, ERROR_CODE). Running all scenarios (POST /api/process-simulation/scenarios/run-all) flags any staleRevision mismatch and catches output-mapping or condition regressions across Approve, Reject, and Missing decision paths.
  • Revision Comparison & Redacted Reports: Consultants can compare two simulation sessions (POST /api/process-simulation/compare) to inspect variable, transition, and gateway diffs, and generate shareable run reports (POST /api/process-simulation/reports). Sensitive variables and fixture keys matching credential patterns (password, secret, token, apiKey, authorization, privateKey, clientSecret, credential) are automatically masked (***REDACTED***), and reports can be revoked (POST /api/process-simulation/reports/{id}/revoke) or expire via retentionMinutes.

7. Virtual Time, Seeded Batch Analysis & Performance (FR-09, T010)

  • Deterministic Seed & Virtual Clock: Both interactive sessions and Monte Carlo batch runs accept an explicit seed so identical seeds and inputs produce identical traces, timer firings (timerEventsFired), and branch distributions.
  • Bounded Cancellation & Explicit SLA Assumptions: In-flight batch runs can be cancelled immediately via POST /api/process-simulation/batch/{batchRunId}/cancel (data-agent-id="sim-btn-cancel-batch"). Batch reports surface explicit slaAssumptions alongside failure/blocked run counts.
  • Measured Scale & Latency (T010): Verified in SimulationServiceTest.shouldMeetInteractiveStepLatencyTargetAndCancelBatchCleanly on a 100-node workflow with 200 declared variables (p95 step latency < 50 ms, well below the < 1000 ms interactive target).

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