Flow Starter

Flow Concept

Flow is a more generalized concept for business processes.

Relationship: Flow > BP = Workflow > BPMN

Expression Engine is mainly used to solve data computation problems, implementing a calculation engine such as QLExpress. BPMN scenarios are better suited to workflow or rule engines like Flowable. For example, Flowable integrates JUEL to support simple expression parsing. DMN rule engines are better for true/false decision scenarios, for example, the sequenceFlow routing conditions in BP. Drools focuses more on rule configuration and management.

Example scenarios:

• Import: better suited to BPMN. Each action is a data update node; actions have an order but can be processed asynchronously.
• Approval: BPMN + DMN. BPMN handles the approval process and path. DMN handles complex approval routing. DQL solves complex approver queries.

flow-starter is Softa’s metadata-driven flow engine starter. It covers:

• design-time graph documents for a visual editor
• compile-time validation and transformation into runtime bundles
• published bundle revisions by designId
• runtime execution for process, validation, and compute flows
• persistent projections for instances, approval tasks, approval records, delegations, CC rules, and trigger events
• optional Pulsar-based trigger and async-task integration

This page documents the current backend contract implemented in flow-starter.

Current Model

Design, Publish, Runtime

Flow Identity And Revisions

• FlowDesign is the draft working copy.
• FlowBundle is the compiled published snapshot.
• Published revisions are keyed by designId, not by flowCode.
• FlowStartRequest resolves bundles in this order:
  1. bundleId — pin to an exact published revision
  2. designId — start the current active revision
• To start a specific historical revision, look up its bundleId via the revisions listing endpoint and pass that as bundleId.
• FlowBundle.designJson keeps the design snapshot used at publish time so the editor can restore a historical canvas.

Flow Scenarios

The module now uses a single FlowScenario enum instead of the old FlowKind + FlowPurpose split.

The scenario decides the execution strategy: PROCESS flows go through FlowRuntimeEngine.start (persisted, resumable); VALIDATION / COMPUTE flows go through evaluate — the same traversal with zero flow footprint. Business writes made by task nodes still join the caller’s transaction, so a failed evaluation rolls them back.

Node Types

Current FlowNodeType values:

• Control: Start, End, Timer
• Routing: InclusiveGateway, ParallelFork, ParallelJoin
• Human: Approval, HumanTask*
• Task: Script, CreateRecord, GetRecord, UpdateRecord, DeleteRecord, QueryRecords, ValidateData, Transform, CallService, CallWebhook, SendEmail, SendSms, SendInboxNotification, QueryAI, AsyncTask, GenerateFile
• Subflow: Subflow
• Data: ForEach*, ReturnValue

* HumanTask and ForEach are defined but not yet runtime-supported: they are omitted from the node palette and rejected at compile time (UNSUPPORTED_NODE_TYPE), so a flow containing them cannot publish.

Node-behavior invariants:

• Subflow is synchronous-only: the orchestrator fails the parent if a child enters a waiting state (WAITING_APPROVAL / TIMER / ASYNC), and recursive subflow invocation is rejected. Model human steps in the parent flow, not a child.
• ParallelFork branches execute serially (deterministic order), not wall-clock-parallel — the gateway models routing topology, not concurrency.

Runtime Statuses

Defined FlowExecutionStatus values:

• Pending
• Running
• Waiting — parked on one or more waits (a pending approval and/or timer / async callback). The specific reasons live in the instance’s pending-approval list and wait-token list, so a single status covers parallel branches suspended for different reasons at once.
• Rejected
• Returned
• Withdrawn
• Cancelled
• Completed
• Failed

API Overview

Host applications embedding the engine in-process should integrate through the FlowClient facade (io.softa.starter.flow.api) rather than looping back over REST — actor / initiator / tenant identity is always resolved server-side from the context, never passed as call parameters. See the in-module integration guide under starters/flow-starter/docs/integration-guide.md in the Softa source repository.

Design APIs (flow editor)

Base path: /flow/designs — the dedicated surface for the graphical editor (the full editor API contract lives in the Softa source repository under starters/flow-starter/docs/frontend-editor-api.md). The generic model API at /FlowDesign/** remains available as the platform data plane and is intentionally not intercepted.

Bundle APIs (published revisions)

Base path: /flow/bundles

Node Descriptor APIs

Base path: /flow/nodeDescriptors

Runtime APIs

Base path: /flow/runtime

Engine-internal resume callbacks live on /internal/flow/runtime/instances/{resumeAsync|resumeTimer} (INTERNAL identity scope) — they are not part of the user-facing surface.

actorId / initiatorId / tenantId are never sent by clients: every action request stamps them server-side from the login context (@JsonProperty(READ_ONLY)), and all query endpoints resolve the current actor from the context.

Approval Projection APIs

Approval Tasks

Base path: /flow/approvalTasks

Approval Records

Base path: /flow/approvalRecords

CC Config

Base path: /flow/ccConfigs

Delegation

Base path: /flow/delegations

Monitor

Base path: /flow/monitor — operator-facing; the search endpoint requires the system admin role (@RequireRole(SystemRoleAdmin), fail-closed when the host app wires no role provider). A caller holding that role also bypasses the participant scoping on the instance detail / overlay / trace / approval-history reads.

Event Logs

Base path: /flow/events

Approval Model

Approval And Reject Thresholds

• Approval modes: ANY_ONE, UNANIMOUS, MIN_COUNT, PERCENTAGE
• Reject modes: ANY_ONE, UNANIMOUS, MIN_COUNT, PERCENTAGE
• One actor can only cast one effective vote per cycle.
• Compile-time validators reject impossible threshold combinations.

Approver Resolution

Approval nodes support:

• static approvers via config.approvers
• dynamic approvers via config.approverSource
• empty-approver strategies via config.emptyApproverStrategy

Supported dynamic source types in the current default resolution path:

• VariableList
• Expression
• InitiatorManager
• Role

Important integration note:

• OrganizationService is defined as an SPI (MetadataOrganizationService is the default when wired). The default resolver path also supports variable-based sources via ApproverResolutionService.
• If you need real org-tree lookup, provide a custom OrganizationService bean or populate resolution variables such as initiatorManagerId and roleApprovers before the flow reaches the approval node.

Approver dedup: the default policy is GLOBAL — a user who already approved an earlier node is auto-passed on later nodes (recorded as AUTO_APPROVE). Residual risk: a mid-flow form edit is still auto-endorsed by that earlier approval; set the policy to CONTIGUOUS or NONE on flows where a re-look matters.

Additional Approval Actions

• transfer
• delegate
• add-sign-before
• add-sign-after
• cc
• read-cc
• return
• resubmit
• withdraw
• urge
• comment

Timeout Handling

Approval timeout strategies:

• REMIND
• AUTO_APPROVE
• AUTO_REJECT
• ESCALATE

ApprovalTimeoutScheduler handles reminders, auto actions, and escalation against persisted pending approvals.

Task Execution Model

Executor-backed task nodes use TaskNodeConfig. The node FlowNodeType selects the executor — there is no separate executor field in config.

{
  "input": {
    "to": ["{{ applicantEmail }}"],
    "subject": "Order {{ orderId }} confirmed",
    "htmlBody": "<h1>Thank you for your order!</h1>"
  },
  "outputVariable": "taskResult"
}

• input supports {{ expr }} interpolation; resolution is owned by the executor (type-aware for data executors, recursive interpolation for free-shape payloads)
• options is executor-specific
• outputVariable, when present, stores the raw executor result under one variable name

Every task node type has a typed input config DTO registered in TaskConfigTypes: the compiler parses config.input into the DTO at publish time and rejects missing required keys (MISSING_REQUIRED_INPUT), so a misconfigured node fails at publish instead of mid-execution. DefaultTaskExecutorRegistry asserts at boot that every registered executor’s node type has such an entry.

Bundled Task Executors

Current module notes:

• CALL_SERVICE ships a bundled executor but is disabled by default: it invokes an arbitrary Spring bean method by name, so it must be explicitly enabled and given a non-empty bean-name allow-list.

Trigger And Messaging Integration

Supported trigger sources (TriggerSource sealed sub-types):

• EntityChange
• Api
• Cron
• Subflow
• FieldChange (COMPUTE scenario only)

Pulsar-connected components are conditionally registered:

Important timer note:

• The module includes the timer resume consumer.
• A scheduler or producer that publishes FlowTimerMessage still has to be provided by the host application or another integration module.

Persistence Model

Primary storage adapters in this module:

• OrmFlowBundleRegistry
• OrmFlowInstanceStore

Node Descriptor Contract

The editor palette is built from FlowNodeDescriptor records exposed through /flow/nodeDescriptors.

• structural descriptors come from BuiltinNodeDescriptorProvider
• executor-backed task descriptors come from TaskExecutorDescriptorProvider
• descriptors include label, icon, sort order, config schema, default config, and allowed scenarios

TaskExecutorDescriptorProvider only exposes task nodes for executors that are actually registered as Spring beans, so conditional executors such as QUERY_AI and ASYNC_TASK only appear when their dependencies are present.

Frontend Graph Compatibility

Design graph DTOs remain aligned with xyflow/react style structures:

Host Application Integration Checklist

Before enabling flow-starter in a real app, verify:

• add flow-starter to the application classpath
• create and expose FlowDesign drafts through the generic model APIs
• provide a real ApprovalNotificationService if you need email, SMS, IM, or in-app notifications
• provide a custom OrganizationService or populate approver resolution variables if you need manager/role/department based approvers
• enable Pulsar topics if using triggers or async tasks
• provide timer scheduling/publishing if using TIMER nodes
• enable CALL_SERVICE explicitly (plus its bean-name allow-list) if flows need to invoke Spring beans; all other task node types ship working executors, conditionally registered on their capability beans