PSA/ee/docs/plans/2026-04-25-workflow-scheduling-actions/PRD.md

PRD: Workflow Scheduling Actions

Status

Draft created 2026-04-25 after source investigation. Scope needs product confirmation before implementation.

Problem Statement

Workflow v2 currently exposes only one scheduling write action, scheduling.assign_user, and it is a create-oriented helper. Dispatchers and workflow authors need first-party actions that match the scheduling lifecycle language they use every day: find an appointment, reschedule it, reassign it, cancel it, or complete it.

Without these actions, workflow builders either cannot automate common dispatcher outcomes or must rely on generic table patches that bypass conflict handling, technician eligibility checks, recurrence semantics, audit records, and workflow event emission.

User Value

• Dispatchers can automate appointment lifecycle changes using action names that match their operating model.
• Workflow builders get safe, typed scheduling actions in the designer catalog instead of generic DB mutation workarounds.
• Downstream workflows can react to canonical APPOINTMENT_* events after schedule changes.
• Engineers can keep scheduling mutation behavior centralized around existing schedule tables, recurrence helpers, and event schemas.

Goals

1. Add first-party workflow actions under shared/workflow/runtime/actions/businessOperations/scheduling.ts:
   • scheduling.find_entry (read)
   • scheduling.search_entries (read)
   • scheduling.reschedule (write)
   • scheduling.reassign (write)
   • scheduling.cancel (write)
   • scheduling.complete (write)
2. Preserve existing scheduling.assign_user behavior unless a bug is directly blocking this scope.
3. Reuse the existing workflow action registration/catalog pipeline; no new designer grouping work should be required because the scheduling.* prefix already maps to the Scheduling group.
4. Use existing schedule persistence concepts:
   • schedule_entries
   • schedule_entry_assignees
   • schedule_conflicts
   • IEditScope recurrence scopes: single, future, all
5. Emit canonical workflow domain events for appointment lifecycle changes:
   • APPOINTMENT_RESCHEDULED
   • APPOINTMENT_ASSIGNED
   • APPOINTMENT_CANCELED
   • APPOINTMENT_COMPLETED
6. Enforce tenant scoping and existing MSP schedule permissions through the workflow action actor model.
7. Provide typed action outputs that can be saved with saveAs and consumed by downstream workflow steps.

Non-Goals

• Do not redesign the schedule entry schema or recurrence model.
• Do not replace the existing Scheduling UI/server actions.
• Do not add a new generic patch action for schedule entries.
• Do not implement APPOINTMENT_NO_SHOW action in this pass unless explicitly added to scope.
• Do not introduce a new workflow catalog group or designer component beyond existing schema-driven forms.
• Do not add notification/email template behavior beyond workflow event emission.
• Do not implement broad observability/metrics/feature flags unless a test or runtime dependency requires it.

Target Users / Personas

• MSP dispatchers who want workflow automations to move, assign, cancel, or complete appointments.
• Workflow builders/admins configuring business-process automation in the workflow designer.
• Technicians and service managers affected by schedule changes.
• Engineers maintaining workflow action contracts and scheduling integrations.

Primary Flows

Flow 1 — Find then reschedule an appointment

1. A workflow trigger provides an appointment/schedule entry reference, or a workflow searches by ticket/time window.
2. The workflow calls scheduling.find_entry or scheduling.search_entries.
3. The workflow calls scheduling.reschedule with a new time window and conflict mode.
4. The action validates permissions, loads the entry, checks conflicts, applies recurrence scope, updates the schedule entry, audits the workflow mutation, emits APPOINTMENT_RESCHEDULED, and returns the updated entry summary.

Flow 2 — Reassign technician(s)

1. A workflow receives a condition such as preferred technician unavailable or escalation required.
2. The workflow calls scheduling.reassign with one or more new technician user ids.
3. The action validates technician eligibility, checks assignment no-op behavior, updates schedule_entry_assignees, audits the mutation, emits APPOINTMENT_ASSIGNED for newly assigned technician(s), and returns previous/new assignees.

Flow 3 — Cancel a recurring appointment occurrence or series

1. A workflow identifies an appointment that should be canceled.
2. The workflow calls scheduling.cancel with recurrence_scope (single, future, or all) plus optional reason/note.
3. The action marks the relevant occurrence/scope as canceled rather than deleting it, audits the mutation, emits APPOINTMENT_CANCELED, and returns the canceled entry summary.

Flow 4 — Complete appointment

1. A workflow determines work is complete.
2. The workflow calls scheduling.complete with optional outcome notes.
3. The action sets completed status, audits the mutation, emits APPOINTMENT_COMPLETED, and returns completion metadata.

UX / UI Notes

• The existing designer catalog groups actions by module prefix. New scheduling.* action ids should automatically appear under the existing Scheduling group in shared/workflow/runtime/designer/actionCatalog.ts.
• Input schemas should use descriptive Zod .describe() strings because the workflow designer derives action forms from JSON Schema.
• Schemas should mirror the newer Client action patterns: use withWorkflowJsonSchemaMetadata picker hints where existing picker kinds are available, and add metadata/catalog tests that convert Zod schemas through zodToWorkflowJsonSchema.
• Use user picker metadata for technician/user id fields. There is not currently a known schedule-entry picker kind, so schedule-entry reference fields should ship as text/UUID-like fields with descriptions; picker support can be a follow-up.
• Output schemas should expose stable fields for downstream step pickers: entry id, assigned user ids, previous/new time, status, conflict metadata, recurrence scope, and emitted event type.

Data Model / API / Integration Notes

Current source baseline

• Current workflow action file: shared/workflow/runtime/actions/businessOperations/scheduling.ts
  • Only registers scheduling.assign_user.
  • Creates rows directly in schedule_entries, schedule_entry_assignees, and optionally schedule_conflicts.
  • Performs permission checks via requirePermission(ctx, tx, { resource: 'user_schedule', action: ... }).
  • Resolves workflow actor from workflow_runs / workflow definition metadata in withTenantTransaction().
• Existing Scheduling server actions live in packages/scheduling/src/actions/scheduleActions.ts.
  • They publish SCHEDULE_ENTRY_* event-bus events and APPOINTMENT_* workflow events.
  • They depend on withAuth/current session and are not directly suitable for workflow runtime handlers.
• Existing schedule model: packages/scheduling/src/models/scheduleEntry.ts.
  • Supports create/update/delete with recurrence scope behavior.
  • update() can extract a single recurring virtual instance, split future series, or update all occurrences.
• Existing event builders: shared/workflow/streams/domainEventBuilders/appointmentEventBuilders.ts.
  • Provides buildAppointmentRescheduledPayload, buildAppointmentAssignedPayload, buildAppointmentCanceledPayload, buildAppointmentCompletedPayload, plus status helpers.
• Newer Client workflow actions added a useful runtime-action pattern in shared/workflow/runtime/actions/businessOperations/clients.ts:
  • action-local picker metadata helper;
  • DB-backed direct action tests under shared/workflow/runtime/actions/__tests__/;
  • runtime catalog grouping tests under shared/workflow/runtime/__tests__/;
  • best-effort lazy publishWorkflowEvent import helper so shared-root tests do not require event-bus module resolution. Scheduling actions should follow these patterns unless a scheduling-specific reason says otherwise.
• Main now tenant-scopes workflow_definitions through tenant_id (server/migrations/20260425200000_add_tenant_id_to_workflow_definitions.cjs). The shared workflow action helper resolveRunActorUserId() should be reviewed/updated during implementation so actor resolution joins workflow_definitions by both workflow_id and the run tenant, not only by workflow_id.
• Existing event schemas: shared/workflow/runtime/schemas/schedulingEventSchemas.ts and packages/event-schemas/src/schemas/domain/schedulingEventSchemas.ts.
  • Already define the six appointment event payloads referenced in the request.

Proposed action contracts

scheduling.find_entry v1

Read side action that loads one schedule entry by entry_id in the current tenant.

Inputs:

• entry_id: non-empty schedule entry reference string. It may be a concrete UUID or an existing virtual recurring occurrence id of the form <masterEntryId>_<timestamp>.
• include_private_details: optional boolean, default false; if false and the actor is not assigned, private entries are redacted.

Outputs:

• found: boolean
• entry: normalized schedule-entry object or null

scheduling.search_entries v1

Read side action for workflow lookups.

Inputs:

• window.start / window.end: optional ISO datetimes, at least one search criterion required.
• assigned_user_ids: optional UUID array.
• work_item: optional { type, id } for ticket/project task/appointment request/ad hoc filters.
• status: optional status filter array.
• query: optional title/notes search text.
• limit: bounded integer defaulting to a safe value.

Outputs:

• entries: normalized entry summaries.
• count: number returned.

scheduling.reschedule v1

Write action that changes an entry's start/end time.

Inputs:

• entry_id: non-empty schedule entry reference string. It may be a concrete UUID or an existing virtual recurring occurrence id of the form <masterEntryId>_<timestamp>.
• window.start, window.end, optional timezone.
• conflict_mode: fail | shift | override, default fail.
• recurrence_scope: single | future | all, default single.
• optional reason, note.

Behavior:

• Requires user_schedule:update.
• Validates start < end.
• Loads the entry and current assignees.
• Detects conflicts for assigned users excluding the target entry/series and ignoring canceled/completed/no-show entries.
• fail: reject with CONFLICT.
• shift: move the requested window to the earliest non-conflicting slot after detected conflicts, preserving duration.
• override: update anyway and record unresolved schedule_conflicts rows.
• Applies recurrence scope using existing recurrence semantics where possible.
• Emits APPOINTMENT_RESCHEDULED when the entry is an appointment-like entry (ticket or appointment_request).

Outputs:

• entry_id, updated_entry_id, previous_start, previous_end, new_start, new_end, assigned_user_ids, conflict_mode, conflicts_detected, recurrence_scope, event_type.

scheduling.reassign v1

Write action that replaces or adds assigned technicians.

Inputs:

• entry_id: non-empty schedule entry reference string. It may be a concrete UUID or an existing virtual recurring occurrence id of the form <masterEntryId>_<timestamp>.
• assigned_user_ids: non-empty unique UUID array.
• mode: replace | add, default replace.
• recurrence_scope: single | future | all, default single.
• no_op_if_already_assigned: boolean default true.
• optional reason, comment.

Behavior:

• Requires user_schedule:update.
• Validates each target user exists, is active/internal where applicable, and is eligible for technician scheduling. Current assign_user checks the Technician role; use the same rule for v1 unless product chooses a different eligibility model.
• If no-op is enabled and the computed assignment set matches current assignment, return success with changed: false and do not emit APPOINTMENT_ASSIGNED.
• Updates schedule_entry_assignees through recurrence-aware update behavior.
• Emits APPOINTMENT_ASSIGNED once for a one-to-one replacement, or once per newly assigned user for multi-assignee changes because the existing event schema has a single newAssigneeId.

Outputs:

• entry_id, updated_entry_id, previous_assigned_user_ids, assigned_user_ids, changed, recurrence_scope, events_emitted.

scheduling.cancel v1

Write action that marks an entry canceled.

Inputs:

• entry_id: non-empty schedule entry reference string. It may be a concrete UUID or an existing virtual recurring occurrence id of the form <masterEntryId>_<timestamp>.
• recurrence_scope: single | future | all, default single.
• optional reason, note.

Behavior:

• Requires user_schedule:update or user_schedule:delete (open question: choose one).
• Updates status to the canonical canceled spelling used by appointment event helpers (cancelled or canceled; current helper accepts both).
• Preserves the row/series rather than deleting it.
• Appends reason/note to existing notes or stores in audit details, without requiring a schema migration.
• Emits APPOINTMENT_CANCELED for appointment-like entries.

Outputs:

• entry_id, updated_entry_id, status, recurrence_scope, reason, event_type.

scheduling.complete v1

Write action that marks an entry completed.

Inputs:

• entry_id: non-empty schedule entry reference string. It may be a concrete UUID or an existing virtual recurring occurrence id of the form <masterEntryId>_<timestamp>.
• optional recurrence_scope, default single for recurring compatibility.
• optional outcome, note.

Behavior:

• Requires user_schedule:update.
• Updates status to completed.
• Stores outcome/note in schedule notes or audit details.
• Emits APPOINTMENT_COMPLETED for appointment-like entries.

Outputs:

• entry_id, updated_entry_id, status, completed_at, outcome, event_type.

Recommended Technical Approach

Option A — Extend workflow scheduling action file with local helpers (recommended)

Implement all new action definitions in shared/workflow/runtime/actions/businessOperations/scheduling.ts, adding private helpers for entry loading, conflict detection, technician eligibility, recurrence updates, audit, output normalization, and event publishing.

Pros:

• Keeps the workflow action catalog simple and colocated with existing business-operation actions.
• Avoids calling withAuth server actions from workflow runtime.
• Minimizes package-boundary changes.

Cons:

• Duplicates some logic currently present in packages/scheduling/src/actions/scheduleActions.ts.

Option B — Extract package-level scheduling domain service, then call it from UI/server actions and workflow actions

Move shared mutation/event logic into a reusable scheduling service package function that accepts tenant/user/transaction context.

Pros:

• Best long-term reuse and consistency.
• Reduces drift between UI mutations and workflow mutations.

Cons:

• Larger refactor and higher risk for this focused action-library improvement.
• More package dependency and test updates.

Option C — Call existing Scheduling server actions from workflow action handlers

Use addScheduleEntry/updateScheduleEntry/deleteScheduleEntry from packages/scheduling/src/actions/scheduleActions.ts directly.

Pros:

• Reuses existing event emission.

Cons:

• Not appropriate because those actions are withAuth/session-oriented and workflow runtime uses a run actor, tenant id, and explicit knex context.

Recommendation: use Option A for this pass, while shaping helpers so they can be extracted into Option B later if scheduling action surface continues to grow.

Permissions / Security

• Read actions require user_schedule:read.
• Write actions require user_schedule:update, except cancel may require user_schedule:delete if product wants cancellation to be treated as destructive. This is an open question.
• All queries must use the current workflow tenant from ActionContext.tenantId and set tenant RLS through withTenantTransaction().
• Private schedule entry behavior should match existing Scheduling UI semantics: assigned users can see details; unassigned actors get redacted details unless they have update-level scheduling permission and product confirms full visibility.
• Workflow actor is resolved from run/workflow metadata by existing withTenantTransaction() helper; no end-user session should be required.

Error Handling

• Invalid inputs return standard workflow action errors through throwActionError().
• Missing entry/user/work item returns NOT_FOUND.
• Invalid time windows return VALIDATION_ERROR.
• Insufficient permissions return PERMISSION_DENIED.
• Conflict fail mode returns CONFLICT with conflict details safe for workflow display.
• Event publishing behavior is confirmed fail-soft/logged. Mirror the Client workflow action pattern by using a best-effort lazy import helper for publishWorkflowEvent; action persistence/audit remains the source of truth if event publication is unavailable or fails.

Risks and Constraints

• Existing scheduling.assign_user writes directly to schedule tables and only emits audit, not APPOINTMENT_CREATED; adding lifecycle event emission may create asymmetry unless separately addressed.
• Existing schedule recurrence update logic lives in packages/scheduling/src/models/scheduleEntry.ts and is marked // @ts-nocheck; use it carefully and cover with DB-backed tests.
• Existing appointment event schema supports single assignee ids. Multi-technician reassignment must emit multiple APPOINTMENT_ASSIGNED events or limit v1 to one technician.
• schedule_entries.status is free text and existing code accepts multiple spellings/cases for canceled/completed/no-show. The actions should choose canonical lowercase statuses and rely on event helpers' tolerant readers.
• Conflict detection must exclude the target entry and should ignore canceled/completed entries to avoid false positives.
• Virtual recurring entry ids use an underscore suffix in the existing model. Action schemas for entry references must therefore accept non-empty strings rather than strict UUIDs, while output fields for concrete updated_entry_id can remain UUID-validated when applicable.
• package-lock.json is already modified in this worktree and was not changed by this plan.

Rollout / Migration Notes

• No database migration is expected for the first implementation pass.
• The actions register through registerSchedulingActions() and should appear automatically in the designer catalog after runtime initialization.
• If picker metadata for schedule entries is missing, the first rollout can use described text input for entry references and add picker support later.
• Because main now includes tenant-owned workflow definitions, implementation should include a small shared-helper guard/update for workflow action actor resolution before relying on schedule write permission checks.
• Existing workflows are unaffected because no existing action ids are removed or versioned.

Acceptance Criteria / Definition of Done

1. scheduling.find_entry and scheduling.search_entries are registered as non-side-effectful v1 actions and appear in the designer Scheduling group.
2. scheduling.reschedule, scheduling.reassign, scheduling.cancel, and scheduling.complete are registered as side-effectful v1 actions and appear in the designer Scheduling group.
3. Each action has Zod input/output schemas with useful descriptions and stable downstream output fields.
4. Read actions are tenant-scoped, permission-checked, and return normalized schedule entry data with assigned user ids.
5. Reschedule validates windows, handles conflict modes, supports recurrence scope, writes audit, and emits APPOINTMENT_RESCHEDULED for appointment-like entries.
6. Reassign validates technician eligibility, supports no-op behavior, updates assignees, writes audit, and emits APPOINTMENT_ASSIGNED according to the confirmed multi-assignee policy.
7. Cancel marks the selected scope canceled, preserves rows, writes audit, and emits APPOINTMENT_CANCELED.
8. Complete marks the selected scope completed, writes audit, and emits APPOINTMENT_COMPLETED.
9. DB-backed integration tests cover at least one happy path and one guard/failure path for scheduling writes.
10. Action registry/designer catalog tests confirm all new action ids are present and grouped under Scheduling.
11. Existing scheduling recurrence integration tests remain passing.

Confirmed Scope Decisions

Confirmed by user on 2026-04-25:

1. scheduling.reassign v1 supports multiple technicians and emits one APPOINTMENT_ASSIGNED per newly assigned user.
2. scheduling.cancel requires user_schedule:update because it marks status canceled rather than deleting rows.
3. Workflow action event publishing follows the existing Scheduling action pattern: fail-soft/log rather than rollback/fail the workflow action.
4. Private entries are redacted unless the actor is assigned or has user_schedule:update.
5. Leave scheduling.assign_user event emission unchanged in this pass unless implementation discovers it blocks consistency.