PSA/ee/docs/plans/2025-12-28-workflow-event-catalog/PRD.md

Workflow Event Catalog v2 (Automation Hub)

Date	2025-12-28
Status	Draft
Owner	Workflow Overhaul

1. Summary

Add a new Workflow Event Catalog (v2) screen in Automation Hub aligned with workflow runtime v2:

• Events are catalog entries (system + tenant) with a payload_schema_ref (schema registry key).
• Workflows attach to events via workflow v2 triggers (workflow_definitions.trigger.eventName), not legacy v1 trigger/attachment tables.

The screen lists all workflow-relevant events grouped by application modules (tickets, billing, CRM, email, etc.). Each event has:

• A schema (via payload_schema_ref / schema registry) used as the basis of workflow triggers.
• A simulate flow to emit a synthetic event (and optionally start workflows) for testing.
• A metrics + audit trail view to understand volume and recent occurrences.
• An attach flow to create a new workflow preconfigured with the event trigger and open the designer.
• A detach flow to remove event triggers from workflows currently attached to the event.

The UI is card-first (grid/list toggle) similar to the provided mockup: searchable catalog, per-event quick metrics on each card, and primary actions (Simulate, Metrics, Attach).

This PRD is aligned with the “stable workflow payload + trigger mapping” behavior:

• Workflows keep a stable payloadSchemaRef.
• Event trigger schemas may change, and trigger mappings (event.payload → workflow payload) reconcile changes.

2. Goals

1. Discoverability: Users can browse/search events and understand what data each event carries.
2. Testability: Users can simulate an event with a schema-driven builder and observe workflows started (or errors).
3. Observability: Users can see high-level metrics and a recent audit trail of runtime events.
4. Fast authoring: Users can attach an event to a brand-new workflow and land in the designer with the correct trigger and schema defaults.
5. Governance: Users can see what workflows are currently attached to an event and can detach them.

3. Non-goals (for this change set)

• Editing/authoring event schemas from the UI (catalog is curated by system + tenant admins).
• Full event “replay” tooling beyond manual simulation.
• Cross-tenant global analytics dashboards.
• A compatibility layer with legacy workflow-runtime v1 triggers/attachments.

4. Users & Permissions

4.1 Roles

• Workflow read: Can view catalog, schemas, attached workflows, metrics, and recent events.
• Workflow manage: Can simulate events; can create workflows from events; can detach workflows (via publishing a new version without a trigger).
• Workflow admin: Required to detach/edit system workflows (or any workflow marked is_system).

4.2 Security constraints

• Simulated event submission should be tenant-scoped and audited.
• Event audit trail should redact sensitive payload fields consistently with run/event redaction rules.
• Detach operations should not silently change published workflows; it must be an explicit publish of a new version (or a safe equivalent).

5. UX / UI Notes

5.1 Page layout (Automation Hub → Events Catalog)

Top header

• Title: “Workflow Event Catalog”
• Subtitle: “Explore, manage, and design workflows for system events and triggers.”
• Right-side controls:
  • System Status pill (Operational / Degraded / Down) (v1 can be hardcoded Operational)
  • Primary CTA: “Define Custom Event” (tenant-only)

Filters row

• Search input (name, event_type, description; supports deep-link query ?eventType=...)
• Category dropdown (All categories)
• Status dropdown (Active / Draft / Beta / Deprecated; semantics depend on catalog entry)
• Source toggle (All / System / Tenant)
• View toggle (Grid / List)

Grid/List

• Each event card shows:
  • Icon (category-based)
  • Name + event_type
  • Status badge (Active/Beta/Draft/Deprecated)
  • Short description (2–3 lines)
  • Quick metrics (last 7 days by default):
    • executions (event count)
    • success rate (runs started from events; definition below)
    • avg latency (event→run completion or run duration; definition below)
  • Buttons:
    • Simulate
    • Metrics
    • Attach (icon button)

Pagination

• Default page size 24 in grid, 50 in list (configurable later)
• Shows “Showing X to Y of Z results”

5.2 Event details drawer/panel

Selecting a card opens a details drawer:

• Full description + metadata
• Schema preview + “View full schema”
• Attached workflows section:
  • list of published workflows whose trigger matches this event type
  • per workflow: name, version, status, paused/system badges
  • actions: “Open in designer”, “Detach”

5.2 Simulate event dialog

Dialog shows:

• Event name/type and schemaRef.
• Builder modes:
  • Form (schema-driven)
  • JSON (raw)
• Optional fields:
  • correlation key (for event waits)
  • payload schemaRef override (advanced; defaults to catalog schemaRef)
• Submit action:
  • Calls event ingestion action (v2): submitWorkflowEventAction
  • Shows result summary: event id, matched wait/run (if any), started run ids.

5.3 Metrics + audit

Within an event “Metrics” panel:

• Date range picker (default last 7 days).
• Summary:
  • total events
  • matched/unmatched/error counts
• “Volume over time” (daily buckets; later can be hourly).
• “Recent events” table (last N) with status, correlationKey, createdAt, processedAt.
• “Open event details” (deep link to workflow event list filtered by event name/type).

Definitions (v1)

• Executions: count of workflow_runtime_events for that event_name in range.
• Success rate: among workflow runs started from those events, percent with status = SUCCEEDED. (If run linkage is unavailable, v1 can omit success rate or compute from runs where event_type = event_name.)
• Avg latency: average run duration (completed_at - started_at) for runs started from these events.

5.4 Attach workflow (create new)

From an event row:

• Attach → New workflow
  • creates a draft workflow definition with:
    • trigger.type = "event"
    • trigger.eventName = <event_type>
    • payloadSchemaRef = <event.payload_schema_ref> if present, else an explicit “unknown” placeholder requiring selection
    • optional: set trigger.sourcePayloadSchemaRef from catalog schemaRef
  • navigates to the workflow designer with this workflow selected.

5.5 Detach workflow

From an event’s “attached workflows” list:

• Detach confirms intent.
• Detach operation:
  • creates a new draft version based on latest published
  • removes trigger (or sets it to null)
  • publishes the new version
  • audit logs the detach action (who/when/from what event type)

6. Data / API / Integrations

6.1 Existing data sources

• Event catalog tables:
  • event_catalog (tenant)
  • system_event_catalog (system)
• Workflow runtime v2:
  • workflow_definitions (trigger stored on definition)
  • workflow_runtime_events (audit trail)
  • workflow_runs (provenance, status)

6.2 New/updated server actions (v2)

Proposed server actions:

1. List events (existing)
   • getEventCatalogEntries
2. List attached workflows for event type
   • query workflow_definitions where trigger->>'eventName' = <event_type> and status='published'
3. Create workflow from event
   • wraps createWorkflowDefinitionAction with prefilled trigger/schema
4. Detach workflow from event
   • wraps:
     • load latest published definition
     • create new version with trigger removed
     • publish
5. Event metrics
   • queries workflow_runtime_events aggregates by day + summary counts
6. Simulate event
   • wraps submitWorkflowEventAction and surfaces started runs/waits.

6.4 Custom events (tenant)

Allow tenant users to define custom events:

• create/update/delete entries in event_catalog (tenant table)
• choose category, name, event_type, description
• set payload_schema_ref (preferred) or inline payload_schema (advanced/legacy)

6.3 Auditing

All simulate/attach/detach operations should emit audit entries, consistent with other workflow runtime actions.

7. Risks / Open Questions

• We must avoid mixing legacy “workflow-trigger-actions / workflow-event-attachment-actions” with v2 triggers in the same UI; this screen is v2-only.
• “Detach” implies publishing a new workflow version. We need to ensure the UX and permission checks align with publish permissions.
• Metrics volume could be large; aggregate queries should be indexed and bounded by time ranges.

8. Acceptance Criteria / Definition of Done

• Event catalog lists tenant + system events with category filtering and search.
• Selecting an event shows schema preview and attached workflows.
• Simulate event dialog emits an event via v2 ingestion and shows resulting started runs.
• Metrics panel shows counts and recent events for the selected event and time range.
• Attach → New workflow creates a draft workflow with the correct trigger and schema defaults and opens the designer.
• Detach removes trigger by publishing a new version and is audited; system workflows require admin.