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

PRD — Workflow Project Actions

• Slug: workflow-project-actions
• Date: 2026-04-27
• Status: Approved

Summary

Add workflow business-operation actions for core project-management entities: projects, project phases, and project tasks. The action set should let workflow authors find/search project entities, update names and descriptions through generic update actions, move/assign/duplicate/delete tasks, delete phases/projects using existing domain semantics, link tickets to tasks, and attach tags to projects or tasks.

The plan prioritizes fidelity with existing workflow action patterns and existing project UI/domain behavior. It should extend the current workflow action registry rather than introduce a new action framework.

Problem

Workflows can currently create project tasks through projects.create_task, but they cannot perform common follow-up operations on project work: locating an existing project/task/phase, moving a task across phase/status/project boundaries, updating names/descriptions, assigning task users, duplicating work, deleting project entities, linking tickets, or tagging project work.

This forces users to leave workflow automation for routine project maintenance, or to use lower-fidelity workarounds such as direct IDs and manual updates outside the workflow designer.

Goals

• Add workflow actions for finding and searching projects, phases, and tasks.
• Add generic update actions for projects, phases, and tasks that cover rename and description-edit use cases.
• Add a dedicated task assignment action that matches the tickets.assign pattern where practical.
• Add task move and duplicate actions that mirror existing project UI/domain behavior.
• Add delete actions for tasks, phases, and projects that mirror existing project UI/domain deletion behavior.
• Add ticket-to-task link action that maintains both project-side and ticket-side link tables.
• Add project/task tag actions that mirror existing contacts.add_tag behavior.
• Add workflow designer picker support for project, phase, task, and project-task-status/status-mapping fields.
• Keep tag entry as free-text arrays, matching existing tag workflow actions.

Non-goals

• Do not add separate narrow rename_* or edit_*_description actions; use generic update actions.
• Do not invent new delete cascade or archive semantics; mirror current project UI/domain behavior.
• Do not introduce tag pickers in this plan.
• Do not add team assignment for project tasks unless existing project task domain support is first-class; the planned assignment model is primary user plus additional users.
• Do not change workflow runtime mapping semantics or persisted workflow step shape.
• Do not replace existing projects.create_task; extend the project workflow action module around it.

Users and Primary Flows

Users

• Workflow authors building project automations.
• MSP operators automating ticket-to-project task handoff.
• Project managers using workflows to keep project work aligned with tickets, tags, assignments, and statuses.

Primary flows

• A workflow receives a ticket or client event, finds a project/task/phase, and updates task details.
• A workflow searches tasks by project/phase/status/title and branches based on whether matching work exists.
• A workflow moves a task to a target phase/status or into another project while preserving existing domain behavior.
• A workflow assigns a task to a primary user and additional users.
• A workflow duplicates a task into another phase with selected related data copied.
• A workflow deletes a task, phase, or project using the same guardrails as the UI.
• A workflow links an existing ticket to an existing project task.
• A workflow adds tags to a project or task idempotently.

UX / UI Notes

• New actions should appear in the Business Operations category with labels consistent with existing workflow actions.
• Fixed-value inputs should be ergonomic for ID-heavy fields:
  • project picker for project IDs
  • phase picker scoped by project where applicable
  • task picker scoped by project/phase where applicable
  • project-task-status/status-mapping picker scoped by project/phase where applicable
• Picker dependencies should use workflow schema editor metadata so dependent fields explain what must be selected first.
• Tag inputs remain free-text string arrays, as in contacts.add_tag.
• Generic update actions should be clear in the palette, e.g. “Update Project”, “Update Project Phase”, “Update Project Task”. They should not create separate palette entries for rename or description editing.

Requirements

Functional Requirements

Find and search actions

• Add projects.find for exact project lookup.
  • Should follow clients.find / tickets.find style.
  • Should support on_not_found: 'return_null' | 'error'.
  • Candidate lookup keys: project_id, exact project name, and any existing external reference field if the project domain has one.
• Add projects.search for project search.
  • Should follow clients.search style: query, filters, page, page_size, array output, first result, and total.
• Add projects.find_phase for exact phase lookup.
  • Should support phase_id and optionally project-scoped exact phase name.
  • Should support on_not_found.
• Add projects.search_phases for phase search/listing.
  • Should support project scope and query/filter/pagination where useful.
• Add projects.find_task for exact task lookup.
  • Should support task_id and optionally project/phase-scoped exact task name.
  • Should support on_not_found.
• Add projects.search_tasks for task search/listing.
  • Should support filters for project, phase, status/status mapping, assignee, tags, and query against task name/description where practical.
  • Should return array output, first result, page metadata, and total.

Generic update actions

• Add projects.update to update project fields needed by this plan, including project name and description.
• Add projects.update_phase to update phase fields needed by this plan, including phase name and description.
• Add projects.update_task to update task fields needed by this plan, including task name/title and description.
• Generic update actions must reject empty patches.
• Generic update actions must validate target existence and permissions.
• Generic update actions must write workflow run audit entries.

Task move action

• Add projects.move_task.
• It must mirror existing moveTaskToPhase behavior:
  • validate source task and target phase
  • support optional target status mapping
  • support cross-project moves through target phase/project context
  • remap status mappings when no explicit target status is provided
  • regenerate WBS/order key as current domain logic does
  • update project ticket links to the target project/phase
  • support optional before/after positioning if practical

Task assignment action

• Add projects.assign_task.
• It must be a dedicated action, not folded into projects.update_task.
• It should mirror tickets.assign where practical:
  • primary user assignment
  • additional user assignments
  • optional reason/comment if consistent with existing task audit/comment behavior
  • no_op_if_already_assigned defaulting to true
  • output current assignment and updated timestamp
• Primary assignee maps to project_tasks.assigned_to.
• Additional users map to existing task resource/additional assignment records.

Task duplicate action

• Add projects.duplicate_task.
• It must mirror existing duplicateTaskToPhase behavior:
  • duplicate task into a target phase
  • support optional target status mapping
  • append the existing copy suffix behavior unless a custom target name is included in scope during implementation
  • reset actual hours as existing domain behavior does
  • optionally copy primary assignee, additional assignees, checklist, and ticket links
  • preserve authorization checks for source project/task and linked tickets

Delete actions

• Add projects.delete_task.
  • Must mirror existing task delete UI behavior.
  • Must refuse delete when associated time entries exist.
  • Must clean up ticket links and checklist items as current UI behavior does.
• Add projects.delete_phase.
  • Must mirror existing phase delete UI/domain behavior.
• Add projects.delete for project deletion.
  • Must mirror existing project delete UI/domain behavior using existing validation where possible.
  • Must preserve existing cleanup of project tags, task tags, project ticket links, email reply tokens, and project deletion validation.

Ticket-to-task link action

• Add projects.link_ticket_to_task.
• It must validate ticket, task, phase, and project context.
• It must maintain both:
  • project_ticket_links
  • ticket_entity_links with entity_type: 'project_task', entity_id: task_id, link_type: 'project_task', and project/phase metadata
• It should be idempotent or conflict-safe where duplicate link constraints exist.
• It must write a workflow run audit entry.

Tag actions

• Add projects.add_tag for project tags.
• Add projects.add_task_tag for project task tags.
• Both must mirror contacts.add_tag behavior:
  • input target ID, tags: string[], optional idempotency_key
  • action-provided idempotency
  • create missing tag definitions with generated colors
  • insert tag mappings idempotently
  • return added, existing, added_count, existing_count
  • write workflow run audit entries

Workflow designer picker support

• Add fixed-value picker support for:
  • project
  • project phase
  • project task
  • project task status/status mapping
• Use dependency metadata for scoped pickers, e.g. phase depends on project, task can depend on project/phase, status mapping can depend on project/phase.
• Do not add tag picker support in this plan.

Non-functional Requirements

• Actions must follow existing action registry conventions: Zod input/output schemas, sideEffectful, idempotency metadata where applicable, UI labels/descriptions, permission checks, tenant-scoped transactions, standardized errors, and audit logging.
• Find/search action naming and behavior should match existing clients.find, clients.search, contacts.find, contacts.search, and tickets.find patterns.
• Mutating actions should reuse or faithfully replicate existing project domain behavior rather than direct table updates when domain behavior is non-trivial.
• New picker metadata should use the current workflow schema editor model and remain compatible with existing fixed/reference source-mode behavior.

Data / API / Integrations

Primary server files expected to be involved:

• shared/workflow/runtime/actions/businessOperations/projects.ts
• shared/workflow/runtime/actions/registerBusinessOperationsActions.ts if registration shape changes
• workflow schema metadata helpers if new picker resource names are needed
• workflow designer fixed picker components and resource registries for project/phase/task/status pickers
• existing project domain action/model/service files as reference for behavior:
  • packages/projects/src/actions/projectActions.ts
  • packages/projects/src/actions/projectTaskActions.ts
  • server/src/lib/api/services/ProjectService.ts

Existing tables likely involved:

• projects
• project_phases
• project_tasks
• project_status_mappings
• project_ticket_links
• ticket_entity_links
• tag_definitions
• tag_mappings
• task_checklist_items
• task resource/additional assignment tables used by current project task actions
• time_entries for delete guards

Security / Permissions

• Read actions require project read permission and must honor existing project authorization narrowing where applicable.
• Project/phase/task updates, moves, assignment changes, duplicate operations, tag additions, and ticket links require appropriate project update/create/delete permissions consistent with existing UI actions.
• Ticket linking must also validate ticket read access where existing UI behavior does.
• Project deletion must preserve existing validation and authorization semantics.
• All queries and mutations must remain tenant-scoped.

Observability

• Mutating actions must write workflow run audit entries with action id, action version, target IDs, changed fields/counts, and no-op state where applicable.
• Read/search actions should log duration and high-level filter/result counts consistent with existing workflow action logging patterns.

Rollout / Migration

• No database migration is expected unless implementation discovers missing constraints or metadata needed for idempotent links.
• Existing workflows and projects.create_task remain compatible.
• New picker resources should be additive.
• If picker support is incomplete, schemas should still allow reference-mode and pasted UUID usage; however, the plan’s target UX includes project/phase/task/status fixed-value pickers.

Risks

• Project UI/domain logic is richer than the current workflow projects.create_task direct-table implementation; implementation must avoid bypassing important behavior for move, duplicate, and delete.
• Status mapping behavior is phase/project-aware and easy to get wrong for cross-project moves.
• Delete behavior can have high blast radius; project deletion must reuse existing validation semantics.
• Task assignment has primary and additional-user behavior; no-op comparison must account for both.
• Maintaining both project-side and ticket-side task links may expose existing data inconsistencies or duplicate constraints.
• Picker dependencies may require new client-side resource loaders for project-specific entities.

Open Questions

• Exact output field shape for project, phase, and task summary schemas.
• Whether projects.update_task should allow status changes, or whether all status/phase/project relocation must go through projects.move_task only. Current PRD bias: use projects.move_task for relocation/status mapping changes.
• Whether projects.duplicate_task should allow a custom copied task title in addition to existing (Copy) suffix behavior.
• Whether task assignment should include an optional task comment, and if so which existing task comment model should be used.

Acceptance Criteria (Definition of Done)

• Workflow registry includes project find/search actions for projects, phases, and tasks.
• Workflow registry includes generic update actions for projects, phases, and tasks that cover rename and description edits.
• Workflow registry includes task move, assign, duplicate, and delete actions.
• Workflow registry includes phase and project delete actions.
• Workflow registry includes ticket-to-task link action that writes both link representations.
• Workflow registry includes project and task tag actions matching contacts.add_tag behavior.
• New action input schemas expose picker metadata for project, phase, task, and project-task-status/status-mapping fields where applicable.
• Workflow designer fixed-value mode can select project, phase, task, and status/status-mapping values with dependency-aware behavior.
• Mutating actions enforce tenant scoping, permissions, validation, standardized errors, idempotency where applicable, and run audit logging.
• Tests cover representative happy paths and high-risk guard cases for read/search, update, move, assign, duplicate, delete, link, tag, and picker metadata behavior.