Notifications & Human-in-the-Loop

​

Notification Lifecycle

┌──────────────┐     ┌───────────────────┐     ┌────────────────────┐
│  Flow Engine  │────▶│  Human Input Node  │────▶│  Create Notification│
│  (executing)  │     │  (pauses flow)     │     │  Records + Broker   │
└──────────────┘     └───────────────────┘     └────────────────────┘
                                                         │
                     ┌───────────────────────────────────┤
                     ▼                                   ▼
              ┌─────────────┐                   ┌──────────────────┐
              │  In-App      │                   │  External Channel │
              │  Notification │                   │  (Teams/Slack/   │
              │  Center       │                   │   Email)          │
              └──────┬──────┘                   └────────┬─────────┘
                     │                                    │
                     ▼                                    ▼
              ┌─────────────┐                   ┌──────────────────┐
              │  User fills   │                   │  User responds    │
              │  VariableFill │                   │  via native UI    │
              │  Dialog       │                   │  (card/modal/link)│
              └──────┬──────┘                   └────────┬─────────┘
                     │                                    │
                     └───────────────┬────────────────────┘
                                     ▼
                          ┌──────────────────┐
                          │  humanInputBroker │
                          │  .submitResponse()│
                          └────────┬─────────┘
                                   ▼
                          ┌──────────────────┐
                          │  Flow resumes     │
                          │  with response    │
                          └──────────────────┘

​

Step-by-Step Flow

1. Flow reaches a Human Input node — The flow orchestrator encounters a node of type human and reads its configuration (IHumanConfig): input type, prompt text, assignees, timeout, and options.
2. Assignees are resolved — Static assignees (from config) or dynamic assignees (from a flow variable) are resolved via assigneeresolver.ts. Groups are expanded into individual users via Microsoft Graph.
3. Ephemeral prompt template is created — For text, approval, and choice input types, an ephemeral prompt template is stored in the prompts Cosmos DB container with variableSpecs describing the form fields. This template has a TTL and is auto-cleaned. The assignee emails are added to the prompt’s users ACL so recipients can access it.
4. Notification records are created — A UserNotification document is written to the usernotifications Cosmos DB container for each assignee. Each record includes:
   • executionId, flowId, nodeId — to route the response back to the correct flow
   • prompt — the rendered prompt text
   • inputType — text, approval, choice, or form
   • options — available choices (for approval/choice types)
   • promptTemplateId — reference to the ephemeral prompt template
   • chatId — the source chat ID so the recipient can view the original conversation
   • chatContext — a summary of recent chat messages (last 10, truncated to 500 chars each) so the reviewer has context about what they’re approving or responding to
   • expiresAt — when the notification times out
   • status — pending, completed, or expired
5. Broker registers a pending request — The humanInputBroker creates a HumanInputRequestDoc in the humaninput container and holds an in-memory Promise that the flow orchestrator awaits.
6. SSE event is emitted — A human_input_required event is sent to the originating client via the SSE stream, enabling the inline HumanInputPrompt component to render immediately if the user is the assignee.
7. External channels are notified — If configured in Admin → Notification Providers ([#/admin/notifications], setting key notificationProviders), notifications are also sent via Teams (Adaptive Card), Slack (Block Kit), and/or email with actionable response UIs.
8. User responds — The response comes through one of four channels (web client, Teams, Slack, email) and reaches humanInputBroker.submitResponse(), which validates the assignee, stores the response, and resolves the waiting Promise.
9. Flow resumes — The orchestrator receives the response payload and continues execution with the human’s input injected into the execution context.

​

In-App Notification Center

• Tabbed view — Separate tabs for Pending, Completed, and Expired notifications with unread counts
• Status indicators — Color-coded chips and icons for each notification state
• Time remaining — Human-readable countdown (e.g., “2 hours 30 minutes”) for pending notifications
• Chat context — Expandable section showing recent chat messages from the conversation that triggered the notification, so reviewers understand what they’re responding to
• Open Chat link — Direct navigation to the source chat (when chatId is available)
• VariableFillDialog — Clicking “Respond” fetches the ephemeral prompt template and opens a form with the appropriate input controls (text area, dropdown, etc.)
• Fallback rendering — If the ephemeral prompt template has expired or is unavailable, the UI synthesizes a fallback template from the notification’s inputType and options

​

Chat Context in Notifications

​

Notification Data Model

​

Human Input Broker

• Multi-instance safe — Request state is persisted in Cosmos DB with a polling fallback (2s interval) so responses submitted on one server instance are detected by the instance holding the waiting Promise
• Assignee validation — Responses are validated against the assignee list by matching userId (GUID), email, or UPN
• Duplicate prevention — Each user can only submit one response per request
• Assignee strategy — Supports any (first response completes) or all (waits for every assignee)
• Timeout handling — Requests expire after the configured timeout and the flow receives an error
• TTL cleanup — Request documents have a per-item _ttl for automatic Cosmos DB cleanup

​

API Endpoints

​

Notification Provider Compatibility

​

Variable Type Support Matrix

​

autoSubmitOnSelect

• Set the flag on any buttons-variant select where the choice itself is the entire interaction (e.g. “Continue / Ask a Question” branch pages in training flows).
• The flag is carried through server-side ephemeral form template generation (ephemeralformutils.ts) and is preserved in the variableSpec delivered to the client.
• Single-option forms already fire a “trivial form fast path,” but setting autoSubmitOnSelect: true is recommended for explicitness and future-proofing.

​

Platform-Specific Limitations

• All supported inputs render inline in the card — single-step interaction.
• Grouped options (ISelectOptionGroup) and option metadata (descriptions, icons, disabled states) are flattened to simple label/value pairs.
• Dynamic optionsSource (e.g., populate from AI Models list) is not resolved at render time.
• Client-side validation rules (regex, min/max) are not enforced; validation occurs server-side on submit.

• Only a single select (≤5 options) or boolean variable renders as inline buttons for one-tap response.
• All other prompts require a two-step flow: user clicks “Open Form” → Slack modal opens with input fields. This is an inherent Slack platform limitation.
• Slack’s datepicker element exists in message blocks but is not available inside modal input blocks, so date falls back to text.
• static_select / multi_static_select are capped at 100 options per element.
• Same grouped options, dynamic source, and validation limitations as Teams.

• Sends an HTML email with a response link — all form interaction happens in the web client after clicking through. No inline form rendering.

Design guidance: For prompts that will be delivered via Teams or Slack, prefer text, select, boolean, and number variable types for the best cross-platform experience. Avoid file, user, hierarchy, and table types unless the prompt will only be answered in the web client.

​

Response Flow

​

Authentication & Security

• Teams & Slack — Token is consumed (invalidated) before the broker call. If the broker call fails after consumption, the user cannot retry.
• Email — Token is consumed after successful broker submission. If submission fails, the user can retry with the same link.
• Web Client — Does not use secure tokens; relies on the authenticated session and passes executionId + nodeId directly.

Security note: The email channel is intentionally public to support users responding from devices where they are not logged into the web app. The trade-off is that forwarding the email link effectively delegates response access. The mitigations (unguessable token, one-time use, expiry) make this acceptable for most workflows, but avoid routing high-security prompts exclusively through email.

​

Assignments

​

Lifecycle

pending ─▶ in_progress ─┬─▶ completed   (criterion satisfied)
                        ├─▶ failed      (criterion unmet; no retries left)
                        ├─▶ cancelled   (creator/admin revoked)
                        ├─▶ rejected    (assignee declined — opt-in)
                        ├─▶ delegated   (assignee handed off — opt-in)
                        └─▶ expired     (auto by sweep past expiresAt)

​

Completion Criteria

​

Delegation & Rejection

• Delegation — When allowDelegation is true, the assignee can hand off to another user. Spawns a successor assignment; original transitions to DELEGATED. Chains are supported; loops are prevented.
• Rejection — When allowRejection is true, the assignee can decline with an optional reason. Status transitions to REJECTED and the creator is notified.

​

Recurring Assignments

​

UI Surfaces

​

Security