Process Designer

Process Designer

The process designer lets a non-developer build a configurable handheld operator process (goods-in, packing, stock check, an ad-hoc move) as a versioned definition, assign one version as active for a process type, and have the handheld PWA run it. It complements, and does not replace, the Flowable BPMN process-engine, which stays for heavy backend orchestration.

It is backed by the process-designer service (Java, port 8097, own process_designer schema), introduced in Phase 1 and extended in Phase 2 (version management, JSON import/export, step skip conditions, more curated tasks, instance monitoring; spec: docs/process-designer-spec.md in the repo). See Services for the one-line summary.

Base path note. The process designer lives under /api/process-designer/**, deliberately not /api/process/** (the Flowable process-engine owns that prefix). The two engines coexist.

What a process is

A process is a versioned JSON flow of two kinds of steps:

• Screens: what the operator sees. Six screen types ship: text, number, date, acknowledge, yes/no, choice. Each can validate input, bind to a scanner, and write its result into a named field on the process data object.
• Tasks: calls into the rest of the WCS (see the curated library below). A task reads from the data object, runs, and merges named outputs back.

Steps connect with transitions; branch conditions decide the next step from the data collected so far. A step can also carry a skip condition (skipWhen, Phase 2): when it evaluates true, the runtime skips that step (the same restricted grammar as a transition condition). A data object carries values across the whole run, and screen titles / prompts can interpolate {{placeholder}} values from it (placeholders resolve to codes via the catalog, never raw UUIDs).

How to design a process

1. Open Engineering → Process Designer (/process-design, ADMIN / SUPERVISOR). The permission is PROCESS_DESIGN_EDIT.
2. The screen is a WYSIWYG three-pane layout:
   • a flow list of the steps,
   • a LIVE handheld preview that renders the selected screen exactly as the operator will see it (it reuses the very same ProcessScreenView component the runtime uses, so what you see is what runs),
   • a properties panel for the selected step plus a data-object panel for the fields the flow reads and writes,
   • a version-management pane (Phase 2) listing drafts / active / archived versions (only a DRAFT is editable), with duplicate / clone and JSON export / import controls.
3. Add screens and tasks, set transitions, branch conditions and step skip conditions ("Skip this step when…"), and bind screens to the data object. The task picker is driven by the live server task catalog (GET /api/process-designer/tasks), so it always lists the real available task types and their inputs / outputs.
4. Use Simulate to walk the flow in the preview without touching real data.
5. Validate, then Publish.

Version management, import and export (Phase 2)

• Duplicate / clone: POST /defs/{key}/{version}/duplicate copies any version into a new DRAFT, so you can iterate from a published version without disturbing it.
• Export: GET /defs/{key}/{version} returns the full definition JSON; the designer offers it as a download.
• Import: POST /defs/import creates a new DRAFT from a full definition JSON (an upload in the designer). Together, export + import move a process between environments (dev → test → prod).

Drafts, active versions, and publishing

• Every edit happens on a DRAFT version. Editing a non-draft is rejected.
• Publish first validates the definition (step reachability, no dangling transitions, every writeTo / task reference resolves, a valid start, and Phase 2: no unreachable steps, no skippable step without an onward path, well-formed branch and skipWhen conditions — validated by a recursive-descent ConditionParser with no eval, so a malformed condition is rejected with 422 — task steps that supply every required input per the live catalog, and no duplicate step ids). If anything is wrong you get the list of problems back and nothing changes.
• On success, publish flips the draft to ACTIVE and archives the prior active version atomically (there is always exactly one ACTIVE version per process key). Versions auto-increment per key.
• Instances that are already running are pinned to the definition they started on, so publishing a new version never disrupts an in-flight operator.

The handheld runtime

The runtime is client-driven. On the handheld:

• The operator menu (the big-tile PWA menu) lists the active configurable processes as tiles, alongside the curated built-in screens.
• Tapping a tile runs it at /process/:key. The client walks the screens locally and evaluates branch conditions and step skip conditions with a safe TypeScript interpreter (no round-trip per screen).
• It posts to the server only at task steps (checkpoints). Checkpoints are offline-queued: a screen flow keeps working through a Wi-Fi blip, and the run holds at a task until connectivity returns.
• Checkpoints are idempotent per (instance, step), so a device swap or a retry resumes cleanly without re-running a task's side effects.

Running a process needs PROCESS_DESIGN_VIEW (granted to all shipped roles).

Curated tasks, not arbitrary code

A process cannot run arbitrary Java. Task steps choose from a curated server-side task library, a fixed registry with no API to author new task types. Each task calls an existing WCS endpoint and forwards the operator's identity (X-Auth-*), so the same RBAC and warehouse scope apply as if the operator called it directly:

Task	Calls
inventory.move	POST /api/flow/moves
slotting.putaway	POST /api/slotting/decant/putaway
picking.confirm	POST /api/orders/pick-tasks/{id}/confirm
inventory.lookup	GET /api/inventory/availability
txlog.post	POST /api/txlog/events
host.confirm (Phase 2)	POST /api/host/inventory/adjustments
inventory.adjust (Phase 2)	POST /api/txlog/events (a StockAdjusted event)
counting.capture (Phase 2)	POST /api/counting/tasks/{taskId}/lines/{lineId}/station-count
order.lookup (Phase 2)	GET /api/orders/{id}

A failing task surfaces the error and does not advance the instance. (AI-assist and a sandboxed script step are future, controlled escape hatches described in the spec; they are Phase 3, not part of Phase 1 or Phase 2.)

Instance monitoring (Phase 2)

A read-only desktop Process instances screen (Engineering, ADMIN / SUPERVISOR, route /process-instances) lists process instances newest-first with a detail pane (the data object, the current step, and the step trail). It is backed by GET /api/process-designer/instances?processKey=&status=&warehouseId=&limit= (summaries) plus the existing GET /api/process-designer/instances/{id} (detail).

Sample process

The service seeds an ACTIVE Stock Check process out of the box: scan location → scan SKU → count → txlog.post records a StockCounted event → acknowledge. It is a worked example of screens + a curated task in one flow.

Internationalisation

The designer and runtime are translated for German, French, Spanish, and Chinese (see Internationalisation).

See Mobile Process Designer for the full design-detail reference (model, screen-step config, API surface), Services for the service summary, Security for the identity-forwarding model, and Transport Overview / Slotting and Replenishment for the endpoints the curated tasks drive.