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

PRD — Workflow V2 External Schedules

• Slug: workflow-v2-external-schedules
• Date: 2026-03-08
• Status: Draft

Summary

Add a dedicated schedules system for Workflow V2 in Enterprise Edition. Schedules will be managed outside the workflow definition on a new Automation Hub schedules screen, and each schedule will store its own timing and static payload. A workflow may have many schedules, each schedule follows the workflow’s latest published version, and saved schedule payloads must validate against the workflow’s pinned payload schema.

Problem

The current time-trigger work places schedule configuration inside the workflow definition and starts runs with a fixed clock payload contract. That model does not support the actual operator need: define multiple reusable schedules for the same workflow and attach static business payload data to each one.

Without external schedules:

• one workflow cannot easily support multiple scheduled variants
• schedule timing and schedule input are coupled to the workflow draft instead of an operational schedule object
• operators cannot manage schedules globally
• the system cannot validate and persist a schedule’s real payload independently from the workflow editor

Goals

• Add a first-class schedule entity for Workflow V2, owned outside the workflow definition.
• Allow many schedules per workflow.
• Let each schedule define:
  • required name
  • one-time or recurring timing
  • saved static payload
  • enabled/paused lifecycle state
• Add a global schedules screen in Automation Hub with create, edit, pause/resume, and delete flows.
• Remove inline time-trigger authoring from the workflow editor.
• Keep event-triggered workflows working as they do today.
• Require pinned payload schemas for scheduled workflows in v1.
• Validate schedule payloads on create/edit and again when a new workflow version is published.
• Make schedules follow the latest published workflow version automatically.

Non-goals

• CE support.
• Fan-out schedules over domain records.
• Per-schedule version pinning in v1.
• Supporting schedules for inferred-schema workflows.
• Adding seconds to cron syntax.
• Duplicating full schedule CRUD inside the workflow editor.
• Broader production-readiness work such as metrics, observability platforms, or feature-flag rollout.

Users and Primary Flows

1. Automation manager creates a reusable schedule

• User opens Automation Hub and navigates to Schedules.
• User creates a schedule for an existing workflow.
• User chooses one-time or recurring timing.
• User enters a static payload using form mode or JSON mode.
• System validates the payload against the workflow’s pinned payload schema.
• User saves and enables the schedule.

2. Automation manager maintains many schedules for one workflow

• User views all schedules filtered to a workflow.
• User distinguishes them by required schedule name.
• User edits timing or payload without editing the workflow definition.
• User pauses, resumes, or deletes schedules independently.

3. Automation manager publishes a new workflow version

• User publishes a new version of a workflow with existing schedules.
• System revalidates every schedule payload against the newly published version’s pinned payload schema.
• Valid schedules rebind to the new version.
• Invalid schedules are preserved but disabled/marked failed with a visible validation error.

4. Scheduled execution starts a workflow run

• At fire time, the runner loads the schedule record.
• System launches the latest published workflow version bound to that schedule.
• The run input uses the schedule’s saved payload, not a synthetic clock contract.
• Run provenance still includes schedule metadata so operators can see which schedule fired.

UX / UI Notes

• Add a new Schedules entry under the Automation Hub parent menu.
• The schedules screen is the source of truth for schedule CRUD.
• Show a global list with filters for workflow, trigger type, status, and search.
• Columns should include:
  • schedule name
  • workflow name
  • trigger type
  • next fire / run-at
  • last fire
  • status
  • last error
• The schedule dialog should support:
  • workflow picker
  • required schedule name
  • trigger type
  • one-time runAt or recurring cron + timezone
  • payload editor with form/json modes
  • inline validation errors
• Workflow editor trigger selector should be reduced to:
  • No trigger
  • Event
• For workflows using no trigger, manual run remains allowed.
• For workflows using event trigger, existing event configuration and mapping UX remain.
• Add a workflow-context link into the schedules screen, prefiltered to the current workflow.

Requirements

Functional Requirements

• Introduce a workflow schedule model separate from workflow definitions.
• A workflow can own many schedules.
• Each schedule must belong to one workflow and tenant.
• Each schedule must have a required user-defined name.
• Each schedule must support either:
  • one-time timing with runAt
  • recurring timing with 5-field cron and timezone
• Each schedule must store a static payload JSON document.
• A schedule may only be created for a workflow that has:
  • a published version
  • a pinned payload schema
• Schedule payload must validate against the workflow payload schema before save.
• Schedule payload must be revalidated when a new workflow version is published.
• Schedules follow the latest published version automatically.
• If a schedule payload is invalid for the latest published version:
  • preserve the schedule record
  • prevent firing
  • surface a validation error in the schedules UI
• Scheduled workflow runs must use the saved schedule payload as workflow_runs.input_json.
• Scheduled workflow runs must still store schedule provenance metadata.
• Workflow definitions must no longer use inline schedule or recurring trigger types for authoring in this feature path.
• Workflow editor publish and run behavior for No trigger and Event must keep working.
• Users must be able to edit, pause/resume, and delete existing schedules.

Non-functional Requirements

• Reuse the existing job-runner abstraction for one-time and recurring registration.
• Keep schedule registration and DB persistence coherent from the user’s point of view.
• Preserve tenant isolation for schedule data and launches.
• Support DB-backed integration coverage for schedule CRUD, validation, and runner registration.
• Keep the implementation EE-only.

Data / API / Integrations

• Add or revise a workflow schedule persistence model under shared/workflow/persistence and its EE migration.
• Change the schedule table from one-schedule-per-workflow to many-schedules-per-workflow.
• Add schedule fields at minimum:
  • id
  • tenant_id
  • workflow_id
  • workflow_version
  • name
  • trigger_type
  • run_at
  • cron
  • timezone
  • payload_json
  • enabled
  • lifecycle/job-runner metadata already needed for registration tracking
• Add workflow schedule server actions for:
  • list
  • get
  • create
  • update
  • pause/resume
  • delete
• Update publish logic so schedule rebinding and payload revalidation happen whenever the latest published version changes.
• Reuse the existing workflow run schema-fetching and form/json payload editing patterns from the manual run dialog where possible.
• Scheduled job handlers must load the schedule record and launch with payload_json.
• Run metadata should include schedule context such as schedule id, schedule name, and trigger timing info.

Security / Permissions

• Only users with workflow management permissions may create, edit, pause, resume, or delete schedules.
• Schedule CRUD must remain tenant-scoped.
• Saved schedule payloads must be treated like workflow inputs and pass through existing redaction/display rules where applicable.
• Event-trigger permissions and behavior are unchanged.

Observability

• Use existing workflow run and schedule state fields rather than introducing new observability infrastructure.
• Schedules UI must expose enough state to diagnose why a schedule is not firing:
  • enabled/disabled
  • last error
  • last fire
  • next fire or run-at
• Invalid schedules after publish must show schema validation failure details.

Rollout / Migration

• This is a follow-on EE redesign for workflow time-trigger functionality.
• Existing inline workflow time triggers should be migrated off the workflow definition model and into schedule records.
• The old one-schedule-per-workflow table shape must be migrated to support many schedules per workflow.
• Existing event-triggered and no-trigger workflows remain valid.
• Existing inline time-trigger UI in the workflow editor should be removed once the schedules UI is in place.

Open Questions

• None currently. The v1 product decisions are:
  • many schedules per workflow
  • pinned-schema workflows only
  • global schedules screen under Automation Hub
  • schedules follow latest published version
  • required schedule names

Acceptance Criteria (Definition of Done)

• Automation Hub contains a Schedules destination with a global schedule list.
• Users can create one-time and recurring schedules for eligible workflows.
• Each schedule stores and validates a static payload against the workflow payload schema.
• Users can edit, pause/resume, and delete schedules.
• A workflow can have many schedules.
• Workflow editor no longer exposes inline one-time/recurring trigger authoring.
• Workflow editor still supports No trigger and Event trigger flows.
• Manual runs still work for no-trigger workflows.
• Publishing a new workflow version revalidates and rebinds schedules to the latest published version.
• Invalid schedules after publish are preserved, visible, and prevented from firing.
• Scheduled runs use the saved schedule payload as workflow input.
• DB-backed integration tests cover schedule persistence and validation behavior.