PSA/ee/docs/plans/2026-03-08-workflow-v2-external-schedules/SCRATCHPAD.md

Scratchpad — Workflow V2 External Schedules

• Plan slug: workflow-v2-external-schedules
• Created: 2026-03-08

What This Is

Keep a lightweight, continuously-updated log of discoveries and decisions made while planning and implementing the external schedules redesign for Workflow V2.

Decisions

• (2026-03-08) Schedules move out of workflow definitions and become first-class tenant-owned records.
• (2026-03-08) A workflow can have many schedules.
• (2026-03-08) Schedules are managed from a global Automation Hub schedules screen.
• (2026-03-08) Add a menu entry under the Automation Hub parent menu for schedules.
• (2026-03-08) Only workflows with pinned payload schemas are schedulable in v1.
• (2026-03-08) Schedules follow the latest published workflow version automatically.
• (2026-03-08) Schedule names are required.
• (2026-03-08) Workflow editor trigger options should become No trigger and Event; one-time and recurring trigger authoring moves out of the editor.
• (2026-03-08) Schedule payload authoring should reuse the existing schema-driven form/json patterns from the run dialog instead of creating a new payload editor from scratch.
• (2026-03-08) External schedule server actions should register only payload schemas, not the full workflow runtime, so schedule validation does not drag in unrelated action/node dependencies during request handling or test startup.
• (2026-03-08) The publish path must only invoke legacy inline schedule sync when either the old or new workflow definition uses an inline time trigger; otherwise it will accidentally disable external schedules on non-time-trigger workflows.
• (2026-03-08) Scheduled execution should pass tenant_workflow_schedule.payload_json straight through as workflow run input and move timing details into trigger_metadata_json; the old synthetic clock contract is now provenance-only data.
• (2026-03-08) The schedules list does not need debounced search in v1; immediate server-backed filtering keeps the URL state simple and avoids timer complexity in the new client surface.

Discoveries / Constraints

• (2026-03-08) The current schedule table was introduced as tenant_workflow_schedule and still enforces unique(workflow_id), which blocks many schedules per workflow. Key file: ee/server/migrations/20260307200000_create_workflow_schedule_tables.cjs.
• (2026-03-08) The current schedule persistence model has no name or payload_json field. Key file: shared/workflow/persistence/workflowScheduleStateModel.ts.
• (2026-03-08) Workflow editor currently still contains inline time-trigger controls for one-time and recurring scheduling. Key file: ee/server/src/components/workflow-designer/WorkflowDesigner.tsx.
• (2026-03-08) Existing scheduled-run handlers already load schedule records and launch runs through a shared launcher, so reusing schedule-owned payloads should fit the current runtime seam. Key files: server/src/lib/jobs/handlers/workflowScheduledRunHandlers.ts, server/src/lib/workflow-runtime-v2/workflowRunLauncher.ts.
• (2026-03-08) The manual run dialog already has both schema-driven form mode and JSON mode plus client-side schema validation, and it is the best reuse candidate for schedule payload authoring. Key file: ee/server/src/components/workflow-designer/WorkflowRunDialog.tsx.
• (2026-03-08) Automation Hub currently has tabs for Template Library, Workflows, Events Catalog, and Logs & History. Schedules can slot into that existing tab model without inventing a separate top-level area. Key file: packages/workflows/src/components/automation-hub/AutomationHub.tsx.
• (2026-03-08) The prior 2026-03-07 plan describes the inline time-trigger approach and is already marked implemented, so this redesign needs its own plan folder instead of overwriting that historical plan.
• (2026-03-08) Importing @shared/workflow/runtime from the new schedule actions eagerly loads workflow runtime initialization exports, which in turn pull unrelated email/storage dependencies into Vitest resolution. Direct imports from the schema registry and schema modules avoid that coupling. Key files: packages/workflows/src/actions/workflow-schedule-v2-actions.ts, shared/workflow/runtime/index.ts.
• (2026-03-08) The new backend checkpoint covers persistence, migration, CRUD actions, validation guards, permission checks, and tenant-scoped list/get flows, but not publish-time rebinding/revalidation or runner launch payload changes yet. Keep F005 and F016-F020 false until that lifecycle work lands.
• (2026-03-08) The EE server DB-backed harness started hitting KnexTimeoutError during database recreation after multiple suite runs against the shared local Postgres container. For the publish lifecycle slice, unit coverage around the publish action and schedule lifecycle was faster and more reliable than retrying the saturated DB harness.
• (2026-03-08) The initial schedules dialog payload-mode implementation had two self-referential sync bugs: form mode kept reparsing payloadText into fresh objects, and JSON mode kept rewriting formValue from unchanged text. Converting mode switches into explicit handlers removed those loops and stabilized the full schedules UI suite. Key file: packages/workflows/src/components/automation-hub/WorkflowScheduleDialog.tsx.
• (2026-03-08) The workflow-designer cleanup compiles, but local verification is currently infrastructure-bound rather than code-bound: the Playwright workflow stack is taking a long time to bootstrap its dedicated dev server on port 3300, and the migrated DB integration suite is still susceptible to KnexTimeoutError pool starvation against the shared local Postgres container.
• (2026-03-08) The remaining unchecked tests were already implemented before closeout: the Playwright file ee/server/src/__tests__/integration/workflow-designer-time-triggers.playwright.test.ts covers T047-T051, and the DB action integration file ee/server/src/__tests__/integration/workflow-external-schedules.actions.integration.test.ts covers T052, T053, T055, and T056.
• (2026-03-08) A targeted rerun of workflow-external-schedules.actions.integration.test.ts still hit KnexTimeoutError while recreating test_database, confirming the previously observed shared-Postgres pool-starvation issue rather than exposing a schedule assertion failure.
• (2026-03-08) A targeted Playwright rerun with PLAYWRIGHT_BASE_URL=http://localhost:3401 PW_WEBSERVER=false PW_REUSE=true got past the old port-3300 mismatch and into Playwright global setup, then stalled while bringing up the test MinIO/dependency stack. That keeps workflow-editor verification infrastructure-bound, not code-bound.

Implementation Log

• (2026-03-08) Completed F001 by keeping this redesign in its own plan folder under ee/docs/plans/2026-03-08-workflow-v2-external-schedules/, preserving the prior 2026-03-07 inline-trigger plan as historical context.
• (2026-03-08) Completed F002-F004 by adding a migration to remove the legacy one-schedule-per-workflow constraint and by extending tenant_workflow_schedule with required name and persisted payload_json. Key files: ee/server/migrations/20260308130000_expand_workflow_schedule_for_external_schedules.cjs, shared/workflow/persistence/workflowScheduleStateModel.ts.
• (2026-03-08) Completed F006-F015 by adding external schedule persistence helpers, lifecycle wrappers, zod action schemas, and tenant-scoped server actions for list/get/create/update/pause/resume/delete with published-version, pinned-schema, and payload validation guards. Key files: server/src/lib/workflow-runtime-v2/workflowScheduleLifecycle.ts, packages/workflows/src/actions/workflow-schedule-v2-schemas.ts, packages/workflows/src/actions/workflow-schedule-v2-actions.ts.
• (2026-03-08) Completed F036 in the action layer by requiring workflow read permission for list/get and workflow manage permission for create/update/pause/resume/delete, plus explicit tenant checks before reading or mutating schedule records.
• (2026-03-08) Completed T001-T020 and T054 with new DB-backed migration and action integration suites covering migration safety, persisted name and payload_json, create/edit flows for one-time and recurring schedules, pause/resume/delete, published-version and pinned-schema guards, payload validation failures, and tenant-scoped global listing. Key files: ee/server/src/__tests__/integration/workflow-external-schedules.migration.integration.test.ts, ee/server/src/__tests__/integration/workflow-external-schedules.actions.integration.test.ts.
• (2026-03-08) Completed F005 and F016-F018 by adding publish-time external schedule revalidation that updates workflow_version for valid schedules, preserves invalid schedules with status=failed and validation errors, and avoids running the legacy inline schedule sync for non-time-trigger workflows. Key files: packages/workflows/src/actions/workflow-runtime-v2-actions.ts, server/src/lib/workflow-runtime-v2/workflowScheduleLifecycle.ts.
• (2026-03-08) Completed T021-T024 with unit coverage on publishWorkflowDefinitionAction, using in-memory persistence mocks to verify valid-only rebinding, mixed validity handling, and per-schedule revalidation across all attached schedules. Key file: server/src/test/unit/workflowExternalSchedulesPublishLifecycle.unit.test.ts.
• (2026-03-08) Completed F019-F020 by updating the scheduled run handlers to send saved schedule payload JSON into launchPublishedWorkflowRun while preserving schedule/timing provenance in trigger metadata. Key file: server/src/lib/jobs/handlers/workflowScheduledRunHandlers.ts.
• (2026-03-08) Completed T025-T028 with unit coverage proving one-time and recurring schedules now launch with saved payload input, provenance metadata is retained, and invalid payloads at fire time are recorded as schedule errors without pretending the launch succeeded. Key file: server/src/test/unit/workflowScheduledRunHandlers.unit.test.ts.
• (2026-03-08) Completed F021-F027 and F030 by adding a Schedules tab to Automation Hub, wiring a server-backed schedules list with workflow/trigger/status filters, row-level edit/pause/resume/delete actions, and a create/edit dialog with workflow selection, one-time runAt, recurring cron + timezone, and inline payload validation. Key files: packages/workflows/src/components/automation-hub/AutomationHub.tsx, packages/workflows/src/components/automation-hub/Schedules.tsx, packages/workflows/src/components/automation-hub/WorkflowScheduleDialog.tsx, packages/workflows/src/actions/index.ts.
• (2026-03-08) Completed T029-T033 with client-side Vitest coverage for the new Automation Hub schedules tab, list columns, and workflow/trigger/status filters. Key files: packages/workflows/src/components/automation-hub/AutomationHub.schedules.test.tsx, packages/workflows/src/components/automation-hub/Schedules.test.tsx.
• (2026-03-08) Completed F028-F029 by finishing the reusable payload editor in the schedule dialog: schema-driven form mode now exposes labeled controls, JSON mode switches explicitly instead of looping state, and both modes operate against the workflow schema loaded from getWorkflowSchemaAction. Key file: packages/workflows/src/components/automation-hub/WorkflowScheduleDialog.tsx.
• (2026-03-08) Completed T034-T046 with a now-stable full schedules UI suite covering text search, edit/pause/resume/delete row actions, dialog required fields, one-time and recurring timing controls, schema-driven form fields, JSON editing, invalid payload blocking, and inferred-schema eligibility messaging. Key files: packages/workflows/src/components/automation-hub/Schedules.test.tsx, packages/workflows/src/components/automation-hub/AutomationHub.schedules.test.tsx.
• (2026-03-08) Completed F031-F035 by reducing the workflow-editor trigger selector to No trigger and Event, removing the inline one-time/recurring configuration panels, keeping the existing manual run and event configuration paths intact, and adding a workflow-context Schedules button that routes to tab=schedules&scheduleWorkflowId=<workflowId>. Key files: ee/server/src/components/workflow-designer/WorkflowDesigner.tsx, ee/server/src/__tests__/page-objects/WorkflowDesignerPage.ts, ee/server/src/__tests__/integration/workflow-designer-time-triggers.playwright.test.ts.
• (2026-03-08) Completed T047-T051 by confirming the existing Playwright workflow-designer coverage file contains the trigger selector, removed inline panels, manual run, event mapping, and workflow-context schedules-link assertions required by the plan. Key file: ee/server/src/__tests__/integration/workflow-designer-time-triggers.playwright.test.ts.
• (2026-03-08) Completed T052-T053 and T055-T056 by confirming the DB-backed action integration suite already covers workflow-manage permission failures plus recurring-schedule persistence and invalid-payload rollback against the migrated table shape. Key file: ee/server/src/__tests__/integration/workflow-external-schedules.actions.integration.test.ts.

Commands / Runbooks

• (2026-03-08) Inspect current schedule lifecycle:
  • sed -n '1,220p' server/src/lib/workflow-runtime-v2/workflowScheduleLifecycle.ts
• (2026-03-08) Inspect current scheduled-run handler behavior:
  • sed -n '1,220p' server/src/lib/jobs/handlers/workflowScheduledRunHandlers.ts
• (2026-03-08) Inspect current workflow editor trigger UI:
  • sed -n '3715,4065p' ee/server/src/components/workflow-designer/WorkflowDesigner.tsx
• (2026-03-08) Inspect current run dialog payload editor:
  • sed -n '1,260p' ee/server/src/components/workflow-designer/WorkflowRunDialog.tsx
• (2026-03-08) Inspect current schedule persistence model:
  • sed -n '1,220p' shared/workflow/persistence/workflowScheduleStateModel.ts
• (2026-03-08) Inspect current Automation Hub navigation:
  • sed -n '1,260p' packages/workflows/src/components/automation-hub/AutomationHub.tsx
• (2026-03-08) Verify TypeScript after the backend slice:
  • npx tsc -p ee/server/tsconfig.json --noEmit
• (2026-03-08) Verify the new external schedule integration suites against the local Postgres container:
  • DB_HOST=localhost DB_PORT=55433 DB_PASSWORD_ADMIN=postpass123 DB_PASSWORD_SERVER=postpass123 npx vitest run --config vitest.config.ts src/__tests__/integration/workflow-external-schedules.migration.integration.test.ts src/__tests__/integration/workflow-external-schedules.actions.integration.test.ts
• (2026-03-08) Verify publish-time external schedule rebinding logic with the server unit harness:
  • cd server && npx vitest run src/test/unit/workflowExternalSchedulesPublishLifecycle.unit.test.ts
• (2026-03-08) Verify scheduled-run payload handoff and provenance behavior:
  • cd server && npx vitest run src/test/unit/workflowScheduledRunHandlers.unit.test.ts
• (2026-03-08) Verify the new schedules tab route state:
  • cd server && npx vitest run ../packages/workflows/src/components/automation-hub/AutomationHub.schedules.test.tsx --coverage=false
• (2026-03-08) Verify exact schedules list UI cases without the broad shuffled suite:
  • cd server && npx vitest run ../packages/workflows/src/components/automation-hub/Schedules.test.tsx -t "shows schedule name, workflow, trigger type, timing, status, and error columns" --coverage=false
  • cd server && npx vitest run ../packages/workflows/src/components/automation-hub/Schedules.test.tsx -t "filters the schedules list by status" --coverage=false
• (2026-03-08) Verify the full schedules UI suite after payload-mode state fixes:
  • cd server && npx vitest run ../packages/workflows/src/components/automation-hub/Schedules.test.tsx --coverage=false
  • cd server && npx vitest run ../packages/workflows/src/components/automation-hub/AutomationHub.schedules.test.tsx --coverage=false
• (2026-03-08) Verify the workflow-editor cleanup compiles cleanly:
  • cd ee/server && npx tsc -p tsconfig.json --noEmit
• (2026-03-08) Attempt to verify the workflow-editor Playwright slice:
  • cd ee/server && PW_REUSE=true npx playwright test src/__tests__/integration/workflow-designer-time-triggers.playwright.test.ts --headed
• (2026-03-08) Attempt to verify the remaining migrated DB integration coverage:
  • cd ee/server && DB_HOST=localhost DB_PORT=55433 DB_PASSWORD_ADMIN=postpass123 DB_PASSWORD_SERVER=postpass123 npx vitest run src/__tests__/integration/workflow-external-schedules.actions.integration.test.ts
• (2026-03-08) Retry the workflow-editor Playwright file against the already running local server instead of waiting on the default 3300 dev port:
  • cd ee/server && PLAYWRIGHT_BASE_URL=http://localhost:3401 PW_WEBSERVER=false PW_REUSE=true npx playwright test src/__tests__/integration/workflow-designer-time-triggers.playwright.test.ts --headed

Links / References

• Prior inline time-trigger plan: ee/docs/plans/2026-03-07-workflow-v2-time-based-clock-triggers/
• Schedule migration: ee/server/migrations/20260307200000_create_workflow_schedule_tables.cjs
• External schedule expansion migration: ee/server/migrations/20260308130000_expand_workflow_schedule_for_external_schedules.cjs
• Schedule persistence model: shared/workflow/persistence/workflowScheduleStateModel.ts
• External schedule action schemas: packages/workflows/src/actions/workflow-schedule-v2-schemas.ts
• External schedule actions: packages/workflows/src/actions/workflow-schedule-v2-actions.ts
• Publish action: packages/workflows/src/actions/workflow-runtime-v2-actions.ts
• Workflow editor: ee/server/src/components/workflow-designer/WorkflowDesigner.tsx
• Workflow run dialog: ee/server/src/components/workflow-designer/WorkflowRunDialog.tsx
• Schedule lifecycle: server/src/lib/workflow-runtime-v2/workflowScheduleLifecycle.ts
• Scheduled run handlers: server/src/lib/jobs/handlers/workflowScheduledRunHandlers.ts
• Publish lifecycle unit test: server/src/test/unit/workflowExternalSchedulesPublishLifecycle.unit.test.ts
• Scheduled run handler unit test: server/src/test/unit/workflowScheduledRunHandlers.unit.test.ts
• Automation Hub tabs: packages/workflows/src/components/automation-hub/AutomationHub.tsx
• Schedules list UI: packages/workflows/src/components/automation-hub/Schedules.tsx
• Schedule dialog UI: packages/workflows/src/components/automation-hub/WorkflowScheduleDialog.tsx
• Automation Hub schedules tab test: packages/workflows/src/components/automation-hub/AutomationHub.schedules.test.tsx
• Schedules UI test: packages/workflows/src/components/automation-hub/Schedules.test.tsx

Open Questions

• None currently. Product decisions were resolved during planning.