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 (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 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.
3. Add screens and tasks, set transitions and branch conditions, and bind screens to the data object.
4. Use Simulate to walk the flow in the preview without touching real data.
5. Validate, then Publish.

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). 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 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

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 not part of Phase 1.)

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.