Bind an event to a workflow from its Start node, with a live mapping preview #429

Closed
opened 2026-10-27 13:36:17 +00:00 by sam · 0 comments
Owner

Purpose

Connecting an event source to a workflow is the core "define and connect" act of archie as a living ecosystem, and today it means leaving the workflow for the Events page and assembling a source, a mapping and a binding there. The operator must be able to bind an event to a workflow from the workflow itself: pick a source, map its payload onto the workflow's declared inputs with a live preview, and save, all inside the Start node's settings panel.

Today

  • The Start node's settings panel (WorkflowSettings.vue) lists triggers and links "Bind an event" to /events?tab=bindings.
  • Building blocks exist on archie-ui's API: GET/POST /api/sources, GET/POST /api/mappings, POST /api/mappings/preview (renders a mapping against a captured payload), GET/POST/PUT/DELETE /api/bindings, POST /api/bindings/{id}/approve. Bindings tie matcher.source, a mapping_id and a workflow (internal/domain/binding/binding.go). The Events page (ui/src/events/, ui/src/bindings/, ui/src/mappings/) has working forms and readers for these; reuse them.
  • Captured events (GET /api/captures) give real payloads to preview against.
  • A workflow's declared inputs (name, type, required) are what a mapping must produce.

Build

  1. "Bind an event" opens an in-panel flow: choose a source (or create one); pick a recent captured payload from it; map payload fields to each declared input (one row per input, required ones marked), with the preview endpoint showing the resolved values and type errors live; save creates the mapping and binding.
  2. Existing bindings to this workflow appear in the Starts-when list and open the same flow for editing; a binding needing approval says so and offers Approve.
  3. The canvas Start node reflects the new trigger immediately.

Context every agent needs

  • The Workflows page (ui/src/workflows/WorkflowsPage.vue, WorkflowEditor.vue) is archie-core's main operator surface: a Vue Flow canvas (WorkflowCanvas.vue, nodes in StepNode.vue, layout in workflow-graph.ts) that both edits a workflow definition and watches its runs. Edits are edits to the YAML document (workflow-edit.ts), so the canvas and the YAML tab never disagree. Read WORKFLOWS.md (repo root) for the workflow language.
  • The watched run comes from useWorkflowRuns (workflow-runs.ts): GET /api/tasks filtered by workflow, and GET /api/tasks/{id}/attempts for its recorded steps (stage rows: name, status ok|failed|interrupted|running, duration_ms, error). A step is recorded under its id, else its type. Live refresh is useLiveResource("tasks", ...) over the SSE stream.
  • Slide-in panels over the right edge of the canvas (StepEditor.vue, WorkflowSettings.vue) are the pattern for details and editing. Do not add a permanent side panel.
  • UI bar the maintainer has set (memory: canvas UI taste): direct manipulation (right-click menus, inline + points, panels that open on demand), no instructional filler text, the field that matters first, help text on hover, nothing that makes the page scroll when the canvas could pan. Drive every change in a headless browser (Playwright with the system Chrome works; stub /api/** with page.route) and look at screenshots at 1920x947 before calling it done.
  • AGENTS.md rules apply: cheapest change first, services own contracts (the dashboard reaches other services only through archie-ui's HTTP API and their gRPC contracts), no new binaries, regenerate and commit ui/dist with the change, task check gates the commit, tests only for the seams AGENTS.md lists.

Acceptance criteria

  • From a workflow's Start node an operator can create a working binding (source + mapping + binding) without visiting the Events page, previewing against a real captured payload.
  • A mapping that leaves a required input unset or mistyped cannot be saved, and says which input.
  • Existing bindings are editable from the same place; approval is offered when required.
  • Uses only existing archie-ui endpoints (or the smallest additions to them). task check passes; screenshots reviewed.

Close reason

Bind flow in the Start node's settings panel: source (or new), example capture, per-input path or fixed value with live preview, save blocked naming the input; edits and approval from Starts when; uses existing endpoints only.


Imported from beads archie-core-t19m.7 · GitHub #1404 · type feature · priority P1 · created 2026-10-05 · closed 2026-10-05

## Purpose Connecting an event source to a workflow is the core "define and connect" act of archie as a living ecosystem, and today it means leaving the workflow for the Events page and assembling a source, a mapping and a binding there. The operator must be able to bind an event to a workflow from the workflow itself: pick a source, map its payload onto the workflow's declared inputs with a live preview, and save, all inside the Start node's settings panel. ## Today - The Start node's settings panel (`WorkflowSettings.vue`) lists triggers and links "Bind an event" to `/events?tab=bindings`. - Building blocks exist on archie-ui's API: `GET/POST /api/sources`, `GET/POST /api/mappings`, `POST /api/mappings/preview` (renders a mapping against a captured payload), `GET/POST/PUT/DELETE /api/bindings`, `POST /api/bindings/{id}/approve`. Bindings tie `matcher.source`, a `mapping_id` and a `workflow` (`internal/domain/binding/binding.go`). The Events page (`ui/src/events/`, `ui/src/bindings/`, `ui/src/mappings/`) has working forms and readers for these; reuse them. - Captured events (`GET /api/captures`) give real payloads to preview against. - A workflow's declared inputs (name, type, required) are what a mapping must produce. ## Build 1. "Bind an event" opens an in-panel flow: choose a source (or create one); pick a recent captured payload from it; map payload fields to each declared input (one row per input, required ones marked), with the preview endpoint showing the resolved values and type errors live; save creates the mapping and binding. 2. Existing bindings to this workflow appear in the Starts-when list and open the same flow for editing; a binding needing approval says so and offers Approve. 3. The canvas Start node reflects the new trigger immediately. ## Context every agent needs - The Workflows page (`ui/src/workflows/WorkflowsPage.vue`, `WorkflowEditor.vue`) is archie-core's main operator surface: a Vue Flow canvas (`WorkflowCanvas.vue`, nodes in `StepNode.vue`, layout in `workflow-graph.ts`) that both edits a workflow definition and watches its runs. Edits are edits to the YAML document (`workflow-edit.ts`), so the canvas and the YAML tab never disagree. Read `WORKFLOWS.md` (repo root) for the workflow language. - The watched run comes from `useWorkflowRuns` (`workflow-runs.ts`): `GET /api/tasks` filtered by workflow, and `GET /api/tasks/{id}/attempts` for its recorded steps (stage rows: name, status ok|failed|interrupted|running, duration_ms, error). A step is recorded under its `id`, else its type. Live refresh is `useLiveResource("tasks", ...)` over the SSE stream. - Slide-in panels over the right edge of the canvas (`StepEditor.vue`, `WorkflowSettings.vue`) are the pattern for details and editing. Do not add a permanent side panel. - UI bar the maintainer has set (memory: canvas UI taste): direct manipulation (right-click menus, inline + points, panels that open on demand), no instructional filler text, the field that matters first, help text on hover, nothing that makes the page scroll when the canvas could pan. Drive every change in a headless browser (Playwright with the system Chrome works; stub `/api/**` with `page.route`) and look at screenshots at 1920x947 before calling it done. - AGENTS.md rules apply: cheapest change first, services own contracts (the dashboard reaches other services only through archie-ui's HTTP API and their gRPC contracts), no new binaries, regenerate and commit `ui/dist` with the change, `task check` gates the commit, tests only for the seams AGENTS.md lists. ### Acceptance criteria - From a workflow's Start node an operator can create a working binding (source + mapping + binding) without visiting the Events page, previewing against a real captured payload. - A mapping that leaves a required input unset or mistyped cannot be saved, and says which input. - Existing bindings are editable from the same place; approval is offered when required. - Uses only existing archie-ui endpoints (or the smallest additions to them). `task check` passes; screenshots reviewed. ### Close reason Bind flow in the Start node's settings panel: source (or new), example capture, per-input path or fixed value with live preview, save blocked naming the input; edits and approval from Starts when; uses existing endpoints only. --- _Imported from beads `archie-core-t19m.7` · GitHub #1404 · type feature · priority P1 · created 2026-10-05 · closed 2026-10-05_
sam added the highfeature labels 2026-10-27 13:36:17 +00:00
sam self-assigned this 2026-10-27 13:36:17 +00:00
sam closed this issue 2026-10-27 13:36:17 +00:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: sam/archie#429