HIL Presentation Contract v1.3
Human-In-The-Loop
Envelope Standard
A unified, channel-agnostic contract for suspending and resuming workflow execution via human interaction — across Web, Slack, Email, Mobile, and API channels.
The Two-Envelope Pattern
sequenceDiagram
participant S as BizFirst Server
participant W as Web / Slack / Email
participant U as Actor (User)
Note over S: Phase 1 — Suspension
S->>W: HilPresentationRequestEnvelope
Note over W: Renders UI from Presentations[]
Shows per-step or envelope Actions[] W->>U: Form / Chat prompt / Approval panel Note over U: Actor reviews context data
fills form / replies / approves U->>W: Clicks action button Note over W: Phase 2 — Response W->>S: HilPresentationReplyEnvelope Note over S: Routes on Decision field
Reads Payload.DataSteps[] or Payload.Data{}
Shows per-step or envelope Actions[] W->>U: Form / Chat prompt / Approval panel Note over U: Actor reviews context data
fills form / replies / approves U->>W: Clicks action button Note over W: Phase 2 — Response W->>S: HilPresentationReplyEnvelope Note over S: Routes on Decision field
Reads Payload.DataSteps[] or Payload.Data{}
Pages
Request Envelope
Server → Browser. Session, Assignees, Channels, Presentations (with per-step Actions[]), envelope-level Actions, ReplyOptions, CustomData.
HilPresentationRequestEnvelope v1.3Reply Envelope
Browser → Server. Responders, Decision, ActionName, Payload.DataSteps[], Payload.Data{}, full audit trail.
HilPresentationReplyEnvelope v1.3Flow & Mapping
Request→Reply symmetric field mapping. Action resolution rule. UI rendering walkthrough. Node executor integration.
Symmetric mappingWire Examples
Complete JSON pairs: Approval, Multi-step Form (per-step actions), Chat/Slack. Request + reply side by side.
JSON examplesKey Design Principles
| Principle | How it is applied |
|---|---|
| Zero-config defaults | ReplyOptions.EnableSteppedDataReturn = true, EnableFlatDataReturn = true — both payload shapes populated without any setup. |
| Per-step action resolution | If Presentation.Actions is non-empty, those buttons are shown for that step. Otherwise the envelope-level Actions[] is used. Multi-step flows get different buttons per step; single-step flows need no step-level actions. |
| Channel-agnostic | Same envelope dispatched to Web, Slack, Email, Mobile simultaneously via Channels[]. |
| Decision vs ActionName | Decision = standard routing token for output ports. ActionName = domain-specific button name echoed from the UI. |
| CorrelationID tracing | Server assigns CorrelationID (GUID); client echoes it unchanged. Enables distributed tracing and deduplication. |
| Multi-step sequential | Presentations[] processed in Order sequence. All step data returned in one reply via DataSteps[]. |
| Naming standard | All abbreviations ALL CAPS per Rule_011-M: EngageSessionID, CorrelationID, ReplyToID, WorkflowID. |
HIL Node Types
| Node | HilType | PresentationType | Default Decision | Phase |
|---|---|---|---|---|
approval | approval | approval | approved / rejected / escalated / abstained | Mid-workflow |
form | form | form | submitted / cancelled | Mid-workflow |
form-trigger | form | form | submitted / cancelled | Entry trigger |
chat | chat | chat | approved / rejected / replied | Mid-workflow |
chat-trigger | chat | chat | replied | Entry trigger |
chat-receive | chat | chat | replied | Passive listener |