Mobile Process Designer

Mobile Process Designer

Phase 1 is now built. The user-facing guide lives at Process Designer; this page is the design-detail reference. One correction from the original draft: the implemented service uses the base path /api/process-designer/** (the Flowable process-engine owns /api/process/**), so the API paths below read /api/process-designer/....

The mobile process designer lets a non-developer build, version, and publish configurable handheld operator processes (goods-in, packing, stock-check, ad-hoc moves) without writing code. A process is a JSON definition of ordered screens and tasks; the PWA operator shell fetches the active definition and runs it on the handheld.

Spec: docs/process-designer-spec.md — authoritative detail on the model, API, and designer UI.

Status: Phase 1 built (service process-designer :8097 + the designer UI and client-driven handheld runtime). See Process Designer and Roadmap and Status.

Concepts

Concept	Meaning
Process key	Stable identifier for a process type, e.g. goods-in, packing. The operator menu shows the active version per key.
Process definition	An immutable, versioned flow: ordered steps + transitions + the data-object schema. Status: DRAFT, ACTIVE, or ARCHIVED. Exactly one ACTIVE per key at any time.
Step	A node in the flow — a screen step (renders a handheld screen, captures input) or a task step (runs server-side work).
Transition	A directed edge between steps; may be unconditional or guarded by a condition over the data object for branching.
Data object	The typed key/value context for one running instance; screens write to it, {{placeholder}} text and conditions read from it.
Instance	One run of a process by an operator. Pinned to the definition version it started on.

Screen step types

All screens are glove-friendly, high-contrast, and support keyboard-wedge barcode scan capture via scanBinding. Common config fields: header, detail (both support {{placeholder}} interpolation), writeTo (data-object variable), and per-type validation.

Type	Captures	Notes
textInput	string	required, regex, maxLength, mustEqual validation; scan binding
numberInput	number	required, min, max, integerOnly, mustEqual
dateInput	ISO date	required, date range bounds; default = today
acknowledge	nothing	confirmLabel; optional required checkbox
questionYesNo	boolean	drives transitions via the data object
questionChoice	string	configurable answer options; choice drives transitions

Task steps (server-side work)

Task steps are server checkpoints that call existing audited services. Three tiers:

1 — Curated task library (Phase 1, default path)

Pre-built parameterized task types; the designer maps data-object variables to inputs/outputs. RBAC and warehouse scope from the operator's identity are forwarded automatically.

Task type	Calls
inventory.move	POST /api/flow/moves
slotting.putaway	POST /api/slotting/decant/putaway
picking.confirm	POST /api/orders/pick-tasks/{lineId}/confirm
inventory.lookup	GET /api/inventory/availability
txlog.post	POST /api/txlog/events

New task types are added in code and land via the normal PR/CI pipeline.

2 — Sandboxed script (Phase 3, controlled escape hatch)

A sandboxed Groovy/GraalVM snippet with a whitelisted API surface and CPU/memory/time limits. Never free-form Java compiled into the running JVM.

3 — AI task-assist (Phase 3, design-time only)

At design time, describe what a task should do; the assistant maps to existing curated task types or drafts a snippet for developer review and merge via PR/CI. AI-generated code is never auto-deployed to a running server.

Branching

when conditions on transitions are a restricted grammar — comparisons (==, !=, <, <=, >, >=) and and/or/not over data-object variables and literals. Evaluated by a small interpreter; no eval, no host access.

Versioning

• Draft → publish sets the version ACTIVE and archives the prior one.
• Rollback = re-publish a prior version (creates a new pointer).
• In-flight pinning: running instances keep the version they started on; publishing never mutates live instances.

Offline execution

The handheld PWA is the runtime. Execution is client-driven:

• On process start the handheld fetches the active definition (cached by the service worker).
• Screen steps run entirely client-side — no server round-trip per screen.
• Task steps are server checkpoints: the client posts {stepId, data}; the server runs the curated task and returns the updated data object + next step.
• While offline, task calls queue (the existing offline queue); screen-only stretches keep working.
• Instance state is checkpointed server-side at each task step — resume after device swap/reload.

The designer (WYSIWYG, desktop)

A three-pane desktop screen (Engineering section, gated by the process-design screen permission):

Pane	Content
Left — flow list	Ordered steps with type icons; branches shown as indented sub-paths. Drag to reorder; add a step from the palette.
Centre — live handheld preview	The selected step rendered in a phone frame using the same components the real handheld runtime uses, with {{placeholder}} resolved against sample data. Edits update the preview instantly.
Right — properties	Per-step config: header/detail with a placeholder picker, writeTo, validation builder, scan-binding toggle; task type picker + variable mapping; question answer/transition editor.

Additional tools: a data-object panel to define typed variables; simulate/test mode to step through the flow with fake input before publishing (task steps are dry-run); and validate + publish which blocks publication until all unreachable steps, dangling transitions, and unknown placeholders are resolved.

API surface

Served by the new process-designer service (port 8097), under the /api/process-designer base path:

• GET /api/process-designer/defs?status= — list definitions
• GET /api/process-designer/defs/{key}/{version} — get one version's full model JSON
• GET /api/process-designer/defs/{key}/active — active definition for a process key
• POST /api/process-designer/defs — create a draft
• PUT /api/process-designer/defs/{key}/{version} — edit a draft (409 if not DRAFT)
• POST /api/process-designer/defs/{key}/{version}/publish — publish (validates, activates, archives prior; 422 with problem list on failure)
• POST /api/process-designer/defs/{key}/{version}/archive
• GET /api/process-designer/processes — distinct process keys with their active version title/icon (used by the operator menu)
• POST /api/process-designer/instances {processKey} — start an instance (returns instance + active def)
• POST /api/process-designer/instances/{id}/checkpoint {stepId, data} — run a task step (idempotent per instance+step)
• GET /api/process-designer/instances/{id} — resume

Security

• No designer-authored Java executes in-process.
• Task steps run with the operator's forwarded identity + warehouse scope; RBAC from existing services applies.
• when conditions and {{placeholders}} are parsed/whitelisted — never eval'd.
• Publishing a definition is an audited, permissioned action (requires process-design permission).

See Services and Security for the identity-forwarding and RBAC model.