PSA/ee/docs/plans/2026-04-27-workflow-time-actions/PRD.md

PRD — Workflow Time Actions

• Slug: 2026-04-27-workflow-time-actions
• Date: 2026-04-27
• Status: Draft

Summary

Add workflow actions for Alga PSA's time module so MSPs can automate core time-entry operations, time-sheet approval flows, and billing-readiness checks from Workflow Designer. The implementation should replace the current direct-write time.create_entry behavior with workflow-safe domain helpers that preserve the same business rules and side effects used by the product's time-entry UI/API paths.

The first implementation scope is option B: core time entry actions, core time sheet actions, and readiness helpers. Timer/session automation, broad custom picker work, and non-core reporting are out of scope for the initial plan unless they are required to make the core actions usable.

Problem

The workflow registry currently exposes only a minimal time.create_entry action. It inserts directly into time_entries and bypasses important time module behavior, including time-sheet association, service validation, user-timezone work-date calculation, default contract line resolution, bucket usage updates, project task actual-hours updates, resource assignment side effects, invoiced-entry guards, and change-request handling.

MSPs need workflows that can safely manipulate time records because time drives payroll review, client billing, contract bucket usage, invoice readiness, technician accountability, and approval workflows. A workflow action that bypasses canonical behavior risks inaccurate billing and inconsistent time-sheet state.

Goals

• Provide workflow actions for creating, reading, finding, updating, deleting, and changing approval state for time entries.
• Provide workflow actions for finding/creating, reading, submitting, approving, requesting changes for, reopening, and commenting on time sheets.
• Provide readiness helper actions that summarize time and identify blockers before billing or recurring invoice approval.
• Extract or introduce workflow-safe time module helpers so workflow actions share canonical business behavior instead of performing ad hoc direct database writes.
• Add workflow schema metadata so high-value fields are usable in Workflow Designer with fixed values or dynamic references.
• Preserve tenant isolation, workflow actor permissions, auditability, and existing time module invariants.

Non-goals

• No timer/session workflow actions in the initial scope (start_timer, stop_timer, active-session management). These can be phase 2.
• No new invoice-generation or invoice-approval behavior. Readiness helpers may report blockers but must not mutate invoices.
• No redesign of the time-entry UI, time-sheet UI, or billing engine.
• No rewrite of the authorization system.
• No broad reporting dashboard or analytics work.
• No client portal time-entry workflows unless they naturally work through existing tenant/permission boundaries.

Users and Primary Flows

MSP workflow builder

Builds automations in Workflow Designer using time actions, fixed pickers, and dynamic references.

Primary flows:

1. Create a billable time entry when a ticket/workflow event indicates completed work.
2. Update or reclassify time after an AI or rules-based validation step.
3. Find unsubmitted or unapproved time for a user, client, ticket, date range, service, or contract line.
4. Submit a technician's time sheet when readiness criteria pass.
5. Approve a time sheet or request changes based on workflow conditions.
6. Check billing readiness before recurring invoice approval and notify/escalate blockers.

MSP technician / service manager

Benefits from consistent downstream behavior when automations create or update time: time sheets remain accurate, services and contract lines resolve correctly, and approval/change-request flows remain traceable.

Billing/admin user

Uses readiness workflows to detect unapproved, unsubmitted, missing-service, missing-contract-line, or otherwise blocked time before billing.

UX / UI Notes

• Time actions should appear under the existing Workflow Designer Time catalog group.
• Action labels should use clear MSP language, for example:
  • Create Time Entry
  • Find Time Entries
  • Update Time Entry
  • Delete Time Entry
  • Find or Create Time Sheet
  • Submit Time Sheet
  • Approve Time Sheet
  • Request Time Sheet Changes
  • Find Time Billing Blockers
  • Summarize Time Entries
• Inputs should support dynamic references by default where appropriate.
• Fixed picker support should be added only where it materially improves core use:
  • User fields should use the existing user picker.
  • Ticket fields should use the existing ticket picker.
  • Time entry / time sheet / time period / service / contract line fields should receive picker metadata and fixed picker support if practical in phase 1; otherwise they must have clear descriptions and examples for reference-based use.
• Long comments, notes, and change reasons should render as textareas.
• Destructive actions like delete or reopen should have clear descriptions and strong validation errors.

Requirements

Functional Requirements

Workflow-safe time domain helpers

• Create shared workflow-safe helpers for time-entry and time-sheet mutations.
• Helpers must be usable from workflow actions without relying on Next.js server-action wrappers.
• Helpers must accept an explicit tenant, actor user, transaction/knex context, and validated input.
• Helpers must preserve or intentionally mirror canonical behavior from the current scheduling/API implementation.
• Helpers must throw structured, actionable errors that workflow runtime can surface as ValidationError, ActionError, or TransientError.

Time entry actions

• time.create_entry

  • Create a time entry for a user and work item.
  • Require service information when canonical time-entry rules require it.
  • Support billable and non-billable entries.
  • Support start/end or start/duration input shape if the final design keeps compatibility with existing workflows.
  • Compute work_date and work_timezone from the entry user's timezone.
  • Attach to the correct time sheet or find/create it based on work date when requested/defaulted.
  • Resolve default contract line when not explicitly provided and when canonical rules can determine it.
  • Preserve canonical side effects: bucket usage, project task actual hours, and ticket/task resource updates.
  • Return the created entry summary with IDs, duration, billable duration, work date, service, contract line, and approval status.

• time.get_entry

  • Load a single time entry by ID.
  • Return normalized details needed for downstream workflow conditions.

• time.find_entries

  • Query time entries by practical workflow filters: user, work item, client, ticket, project task, time sheet, service, contract line, approval status, billable flag, work date/date range, start/end range, invoiced flag, and limit.
  • Return a bounded list and aggregate counts/minutes.

• time.update_entry

  • Update allowed fields on non-invoiced time entries.
  • Recompute dependent fields and side effects when start/end, billable duration, service, contract line, work item, or approval-relevant data changes.
  • Preserve canonical restrictions for approved/invoiced entries.

• time.delete_entry

  • Delete a non-invoiced time entry.
  • Preserve bucket usage decrement and project task actual-hours recalculation.
  • Return deletion confirmation and selected deleted-entry summary.

• time.set_entry_approval_status

  • Set an entry approval status where allowed by permissions and state.
  • Support DRAFT, SUBMITTED, APPROVED, and CHANGES_REQUESTED.
  • Support change-request comment when moving to CHANGES_REQUESTED.

• time.request_entry_changes

  • Convenience action for requesting changes on one or more submitted entries, including change-request comments.

Time sheet actions

• time.find_or_create_timesheet

  • Find or create a time sheet for a user and time period or work date.
  • Return time sheet, period, status, and summary fields.

• time.get_timesheet

  • Return a time sheet, period, comments, and summary counts/minutes.

• time.find_timesheets

  • Query time sheets by user(s), period/date range, status, and approval scope.
  • Return bounded list and summary counts.

• time.submit_timesheet

  • Submit a draft or changes-requested time sheet using canonical submit behavior.
  • Update associated time entries to SUBMITTED.

• time.approve_timesheet

  • Approve a submitted time sheet using canonical approval behavior.
  • Update associated time entries to APPROVED.
  • Record approver metadata/comment behavior consistent with the product.

• time.request_timesheet_changes

  • Move a time sheet to CHANGES_REQUESTED with an approver comment/reason.

• time.reverse_timesheet_approval

  • Reopen an approved time sheet where allowed.
  • Block reopening when any associated entries are invoiced.

• time.add_timesheet_comment

  • Add a user or approver comment to a time sheet.

Readiness helper actions

• time.summarize_entries

  • Summarize time entries by filters and grouping options such as user, client, work item, service, contract line, status, billable flag, and date.
  • Return totals for entry count, total minutes, billable minutes, non-billable minutes, approved/submitted/draft/change-requested counts, and invoiced counts.

• time.find_billing_blockers

  • Identify time-entry blockers for billing readiness over a client/date/service/contract-line scope.
  • At minimum detect unapproved/submitted/draft/change-requested entries, missing service, missing contract line where required, invalid/zero duration, missing work item where required, and entries not attached to an expected time sheet when applicable.
  • Return blocker categories, counts, matching entry IDs, and human-readable explanations suitable for notifications.
  • Must not mutate invoices or billing documents.

• time.validate_entries

  • Validate a bounded set or query of entries against readiness rules and return pass/fail with details.
  • Useful as a lightweight condition step before submit/approve/billing workflows.

Non-functional Requirements

• Actions must be tenant-scoped and fail fast if tenant context is missing.
• Actions must be idempotency-aware where side-effectful operations can be retried by the workflow engine.
• Queries must use bounded limits to avoid unbounded workflow payloads.
• Error messages must be actionable for workflow builders.
• Helper behavior must be deterministic enough for DB-backed tests.

Data / API / Integrations

Existing data model touched

• time_entries
• time_sheets
• time_periods
• time_sheet_comments
• time_entry_change_requests
• tickets, ticket_resources
• project_tasks, task_resources, project_phases, projects
• service_catalog
• contract_lines / client contract line linkage as used by existing default contract-line resolution
• bucket usage tables/services used by current time-entry save/delete behavior
• audit_logs

Helper/service placement

The implementation should introduce helpers in a runtime-safe location that can be imported by shared/workflow/runtime/actions/businessOperations/time.ts without pulling in Next.js server-action wrappers. Candidate locations should be selected during implementation after checking package boundaries. The design intent is:

• shared helper functions for canonical time-entry create/update/delete/read/query behavior;
• shared helper functions for canonical time-sheet submit/approve/request-changes/reverse/comment behavior;
• small workflow action handlers that validate input schemas, call helpers, write workflow audit records, and return normalized outputs.

Workflow registry integration

• Register all new actions from registerTimeActions() in shared/workflow/runtime/actions/businessOperations/time.ts or adjacent files.
• Keep the designer catalog Time group intact.
• Add schema descriptions and x-workflow-editor / picker metadata through withWorkflowJsonSchemaMetadata where useful.

Versioning / compatibility

The existing time.create_entry action must not silently keep unsafe behavior. The implementation should decide whether to:

1. preserve action id/version and fix semantics, or
2. add a new version/action id and migrate/deprecate the old behavior.

This remains an open decision because it depends on whether existing workflows may already rely on the current action shape.

Security / Permissions

• Use workflow actor permissions via the same role/permission model as existing workflow business-operation actions.
• Time entry actions should require the relevant timeentry permissions (create, read, update, delete) and timesheet actions should require relevant timesheet permissions (read, submit, approve, reverse, comment/equivalent).
• Acting on behalf of another user must preserve the current delegation/manager semantics where practical.
• Approving time must enforce the existing approval constraints and must not permit self-approval if current product rules prevent it.
• Readiness helpers should require read permissions and must not expose records outside the workflow actor's permitted scope.
• All mutations must be tenant-scoped.

Observability / Auditability

• Mutating workflow actions should write workflow run audit records consistent with existing business-operation actions.
• Returned outputs should include enough IDs and status fields to support downstream workflow audit trails.
• No new metrics dashboard is required for this plan.

Rollout / Migration

• Implement actions behind normal workflow registry availability; no database migration is expected unless helper extraction requires schema support or new picker APIs require endpoints.
• Existing direct-write time.create_entry behavior should be replaced or versioned carefully.
• If service/contract/time pickers are added, ship them as additive Workflow Designer support.
• Document any behavior changes to time.create_entry, especially service requirement and time-sheet/contract-line side effects.

Open Questions

1. Should time.create_entry remain version 1 with fixed semantics, or should a version 2/new action id be introduced for compatibility?
2. Should phase 1 include fixed picker UI support for service, contract line, time entry, time sheet, and time period, or should those start as reference/manual UUID fields?
3. Should this plan include publishing/trigger improvements for time-entry submitted/approved and time-sheet submitted/approved events, or remain action-only?
4. Should bulk actions be first-class in phase 1, or should find_entries + workflow loops handle multi-entry operations?

Acceptance Criteria (Definition of Done)

• Workflow Designer exposes time actions for core time-entry, time-sheet, and readiness operations under the Time group.
• Creating/updating/deleting time through workflows uses workflow-safe helpers and preserves canonical time module behavior.
• Time-sheet submit/approve/request-changes/reverse/comment actions enforce permissions and state guards.
• Readiness helpers can identify billing blockers without mutating invoices.
• Input schemas include useful descriptions and editor metadata for fixed/reference modes.
• DB-backed tests cover representative happy paths, permission/state guards, and high-risk billing/time-sheet side effects.
• Existing tests for time entry, time sheet, billing blockers, and workflow registry continue to pass.