API & Data

The REST APIs of flow-starter, the in-process FlowClient, the persistence model and the editor contracts, for reference. For how approvals and automation behave, see Approval Flows and Automation.

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. FlowAutoConfiguration registers the default InProcessFlowClient only when the application defines no FlowClient bean of its own. 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

Instance APIs

Base path: /flow/instances — launch, reads and approval actions on runtime instances.

Who may view an instance: its initiator and the people it gives a task to (approvers pending or done, CC recipients, transfer, delegation and add-sign targets) by default; anyone else through the standard role and data-scope configuration — they may read the FlowInstance row with their own permissions, or, for a record’s approval, read the record itself.

The defaults need no grant on the flow models, which no business role holds. The engine’s own bookkeeping — loading and saving instances, the approval ledger, the task and branch projections, delegation and auto-CC rules — runs past the caller’s data permissions: who may act is the action handlers’ call, who may see the access guard’s. The current user’s own lists — inbox counts, pending / completed / CC tasks and the inbox (/flow/approvalTasks), their approval history and sent CCs (/flow/approvalRecords), their delegations, and POST /flow/instances/search, with their FlowClient counterparts — carry @SkipPermissionCheck: pinned to the caller, row scope could only empty them. The per-instance reads (.../instance/{instanceId}, the instance detail endpoints) are not waived, because the guard judges everyone but the initiator and the task holders by their own permissions.

Instance search

POST /flow/instances/search (the caller’s own approvals) and POST /flow/monitor/instances/search (across initiators, see Monitor) take the same FlowInstanceSearchRequest and return the same rows, newest first, paged by pageNumber (default 1) and pageSize (default 50). Filters combine with AND:

A row (FlowInstanceSummaryView) leaves out the heavy state columns and the trace — fetch the instance or its overlay for those. It carries the flow, title, initiator, status and the steps the instance waits on now (currentSteps, each with the approvers still to act), every user named, and for a record’s approval what its submission recorded (Approving Business Records): subject, subjectDept, effectiveDate, recordCode, and awaitingRevision. On the caller’s own approvals that wait on their approvers, withdrawable and urge say whether they may withdraw or urge them now. recordDeleted marks an approval whose record is gone — a draft deleted after a return or a withdrawal — and effectStatus says where an approved record’s change stands, for a model whose approval takes effect later (ModelApprovalHandler.effectStatuses).

Automation APIs

Base path: /flow/automation — trigger firing and transient runs; none of these reads or acts on an existing instance.

Async-task and timer resumes have no REST endpoint: FlowAsyncTaskConsumer, FlowTimerConsumer and the due-timer sweep of the maintenance cron call FlowRuntimeEngine in-process.

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. The in-process FlowClient resolves the actor the same way and calls the same services as these endpoints.

Approval Projection APIs

Approval Tasks

Base path: /flow/approvalTasks

Each task (FlowApprovalTaskView) comes with its instance’s context — instanceTitle, modelName / rowId, instanceStatus, the initiator and submittedTime, and what a record’s approval recorded of its record (subject, subjectDept, effectiveDate, recordCode), every user, employee and department named — and with what its step’s configuration says about acting on it, read from the revision the instance runs on: handling (a handling step), returnAllowed (the step’s returnEnabled) and batchable (open to its approver now — pending, not blocked by an add-sign, the instance waiting — on a step that is not a handling step and makes no field required). See Batch actions and handling steps.

Approval Records

Base path: /flow/approvalRecords

An entry (FlowApprovalRecord, FlowApprovalRecordView) records its action (ApprovalActionType: APPROVE, AUTO_APPROVE, REJECT, TRANSFER, DELEGATE, ADD_SIGN, CC, READ, RETURN, WITHDRAW, URGE, COMMENT, TERMINATE), its actorId and, for an action done on the actor’s behalf, operatorId — the administrator who reassigned the actor’s task (a TRANSFER entry from the approver to the new one); empty when the actor acted themselves.

CC Config

Base path: /flow/ccConfigs

A rule (FlowCcConfig) CCs its recipients at its timing:

• OnSubmit: when the flow starts.
• OnApprove / OnReject: after an approver approves or rejects a step.
• OnComplete: when the approval completes approved.

A rule without a nodeId is flow-level and fires at every such moment. A rule naming a step fires at OnApprove / OnReject of that step only. recipientType INITIATOR CCs the initiator; any other type reads recipientConfig as comma-separated user ids. An optional ccCondition is evaluated over the instance variables.

An automatic CC is recorded like a manual one: one CC entry per recipient in the approval history. The entry has no actor, since no person sent it. It sits on the node the rule fired at — the step acted on, or the start node at OnSubmit (and at OnComplete when every step passed on its own) — in that node’s current cycle. So the recipient:

• has a CC task in the inbox, which they mark read;
• is a participant of the instance: they open it and comment on it.

A recipient already CC’d on the same node and cycle, by a rule or by hand, is not CC’d again, so a step that several approvers approve CCs once. sendNotification additionally notifies the recipients CC’d that time.

Delegation

Base path: /flow/delegations

Monitor

Base path: /flow/monitor — the administrators’ console. No role is built in: each endpoint is granted like any other, and what the console reads or acts on is the caller’s own permissions on FlowInstance — their roles’ grant and data scope; taking part in an instance is not enough. A department scope (DEPT_SUBTREE, MANAGED_DEPARTMENTS) narrows by FlowInstance.departmentId, the subject’s department at submission — a plain department-id column the permission-starter scopes filter by the ids of the departments in range — so a role scoped to the departments it manages sees and administers their approvals; an automation run belongs to no department. Opening another user’s instance (detail / overlay / trace / approval history) follows the viewing rule under Instance APIs, as for any viewer who is not a participant.

Event Logs

Base path: /flow/events

Persistence Model

Primary storage adapters in this module:

• OrmFlowBundleRegistry
• OrmFlowInstanceStore

OrmFlowBundleRegistry loads nothing at startup and caches per tenant:

• Trigger matching reads an index of the tenant’s active bundles, loaded in that tenant’s own context on its first event (an empty result is kept too) and merged with the platform-shared bundles (tenantId = 0); a context without a tenant matches the shared ones only. Entries live for flow.trigger-cache-ttl-seconds (default 60). Publishing or activating a revision drops the tenant’s entry at once on the instance that did it; other instances pick the change up within the TTL. Change logs of models no flow watches are not turned into trigger events.
• Definitions are cached by bundleId in a bounded LRU (a published revision never changes). A bundle of another tenant reads as not found, whether cached or not; platform-shared bundles are visible to every tenant.
• The active revision of a flow is read from the database on every lookup, so starting by flowId follows a publish or rollback made on any instance.

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: