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

# PRD — CRM Workflow Actions

- Slug: `workflow-crm-actions`
- Date: `2026-04-25`
- Status: Draft

## Summary

Expand the Workflow Runtime V2 CRM action module beyond its single existing action, `crm.create_activity_note`, so workflow authors can query and update CRM activities, schedule follow-up activities, and automate quote sending from workflow logic.

This plan treats the user-proposed CRM action list as a phased roadmap. The first implementation pass focuses on the four highest-value actions:

1. `crm.find_activities`
2. `crm.update_activity`
3. `crm.schedule_activity`
4. `crm.send_quote`

The remaining recommended actions are documented as follow-on scope so their naming, dependencies, and overlap with newly merged Client workflow actions are explicit before implementation begins.

## Problem

The CRM workflow module is sparse. Today it registers exactly one action in `shared/workflow/runtime/actions/businessOperations/crm.ts`:

- `crm.create_activity_note`

That leaves workflow authors unable to automate common CRM loops:

- Look up recent sales/account interactions before choosing an onboarding path.
- Update an activity after a ticket, quote, or project milestone changes.
- Schedule a follow-up call or meeting after work is completed.
- Send a prepared quote when a workflow reaches a business-ready state.

By comparison, Tickets and Clients now have much richer workflow action coverage. Recent main-branch updates added extensive Client workflow actions and established implementation conventions that CRM should follow.

## Goals

- Add first-pass CRM workflow actions for activity lookup, activity update, follow-up scheduling, and quote sending.
- Keep actions grouped under the existing Workflow Designer CRM tile via `crm.*` action IDs.
- Preserve current shared workflow runtime architecture: Zod schemas, registry registration, `action.call`, tenant transaction helpers, permission checks, audit logs, and schema-derived designer forms.
- Reuse existing data models/services where safe, but do not import server-only `withAuth` actions into shared runtime code.
- Follow recent main-branch workflow-action conventions:
  - picker metadata with `withWorkflowJsonSchemaMetadata`
  - lazy workflow event publisher imports from shared runtime action handlers
  - deterministic event idempotency keys
  - DB-backed shared-root action tests
- Clearly separate CRM activity/interactions from Client-module notes/interactions that now exist in `clients.*` workflow actions.

## Non-goals

- Replacing `crm.create_activity_note` or changing its persisted contract.
- Implementing every recommended CRM action in the first pass.
- Building new Workflow Designer UI controls beyond existing schema metadata and picker conventions.
- Calling Next.js server actions or `withAuth` action wrappers directly from shared workflow runtime code.
- Reworking quote lifecycle, quote PDF rendering, email templates, or approval logic outside the workflow-action wrappers.
- Duplicating `clients.add_note` or `clients.add_interaction` semantics under CRM without a clear CRM-wide abstraction.
- Adding new event schemas unless implementation discovers a hard gap that cannot be solved with existing CRM/tag/quote events.

## Users and Primary Flows

### Users

- MSP admin building workflow automations.
- Account manager or dispatcher whose CRM follow-up tasks are triggered by tickets, projects, or quote state.
- Internal Alga PSA engineer extending Workflow Runtime V2 business operations.

### Primary flows

1. **Find recent CRM activity before branching**
   - Workflow receives a client/contact/ticket event.
   - Workflow runs `crm.find_activities` with client/contact/date/type/status filters.
   - Workflow branches based on whether there were recent sales, QBR, onboarding, or support interactions.

2. **Update an existing CRM activity**
   - Workflow has an interaction ID from a trigger or prior lookup.
   - Workflow runs `crm.update_activity` to update status, notes, tags, visibility, or outcome-related fields.
   - The action returns before/after summaries and changed fields.

3. **Schedule a follow-up activity**
   - Workflow closes a ticket or completes onboarding.
   - Workflow runs `crm.schedule_activity` to create a future-dated interaction linked to a client/contact/ticket.
   - The activity appears as a CRM interaction/follow-up record and emits interaction logging events where appropriate.

4. **Send a quote from workflow**
   - Workflow identifies an existing quote that is ready to send.
   - Workflow runs `crm.send_quote` with optional recipients, subject, and message.
   - Existing quote send logic publishes the quote to the portal, stores/generates PDF best-effort, and sends email best-effort.

## UX / UI Notes

- New actions should appear under the existing Workflow Designer CRM group. No catalog seed change should be needed because `crm.*` action IDs map to the built-in CRM group.
- First-pass labels:
  - `crm.find_activities` → Find CRM Activities
  - `crm.update_activity` → Update CRM Activity
  - `crm.schedule_activity` → Schedule CRM Activity
  - `crm.send_quote` → Send Quote
- Schema descriptions should use MSP language: activity, interaction, follow-up, client, contact, quote.
- Picker-backed fields should use current metadata conventions where supported:
  - `client_id` → `client`
  - `contact_id` → `contact` with `client_id` dependency when applicable
  - `ticket_id` → `ticket`
  - `user_id`/owner fields → `user`
  - `quote_id` can remain UUID in v1 unless a quote picker already exists or is introduced separately
  - interaction type/status can remain UUID fields in v1 unless a supported picker kind exists
- Output schemas should be rich enough for downstream branches: found counts, activity summaries, quote status, email sent flag where available, and changed fields.

## Requirements

### Functional Requirements — First Pass

#### `crm.find_activities`

- Register action ID `crm.find_activities`, version `1`.
- Side-effect-free.
- Inputs:
  - optional `client_id`
  - optional `contact_id`
  - optional `ticket_id`
  - optional `user_id`
  - optional `type_id`
  - optional `status_id`
  - optional `date_from`
  - optional `date_to`
  - optional `limit` defaulted and capped
  - optional `on_empty`: `return_empty` or `error`
- Require at least one meaningful filter or date range to avoid unbounded CRM scans.
- Enforce `client:read`, `contact:read`, or a CRM/read-equivalent permission decision documented before implementation. If no CRM-specific permission exists, use the safest existing resource permission based on supplied filters.
- Return:
  - `activities`: array of normalized activity summaries
  - `count`
  - `matched_filters`
- Summaries should include interaction ID, type, status, client/contact/ticket IDs and names where available, title, notes preview, interaction date, start/end time, user ID/name, visibility, category, and tags where available.

#### `crm.update_activity`

- Register action ID `crm.update_activity`, version `1`.
- Inputs:
  - `activity_id`
  - `patch` object for editable fields:
    - `title`
    - `notes`
    - `status_id`
    - `visibility`
    - `category`
    - `tags`
    - `interaction_date`
    - `start_time`
    - `end_time`
    - `duration`
    - optionally `type_id` if changing type is product-safe
  - optional `reason`
- Reject empty patches.
- Validate activity exists in tenant.
- Validate status IDs are tenant statuses with `status_type = 'interaction'`.
- Validate interaction type IDs against tenant `interaction_types` or `system_interaction_types`.
- Preserve immutable fields such as `tenant`, `interaction_id`, and workflow actor attribution unless explicitly designed otherwise.
- Write run audit with before/after summary and changed fields.
- Return before/after summaries and changed fields.

#### `crm.schedule_activity`

- Register action ID `crm.schedule_activity`, version `1`.
- Inputs:
  - `client_id` or `contact_id` (at least one required; resolve client from contact when omitted)
  - optional `ticket_id`
  - `type_id`
  - `title`
  - optional `notes`
  - optional `status_id` (default to tenant default interaction status)
  - `start_time`
  - optional `end_time`
  - optional `duration`
  - optional `visibility`
  - optional `category`
  - optional `tags`
  - optional `assigned_user_id`/`owner_user_id`; default workflow actor in v1
  - optional `idempotency_key`
- Validate linked client/contact/ticket relationships.
- Validate `start_time <= end_time` when both are supplied.
- If duration is omitted and start/end are supplied, derive duration consistently with current interaction behavior.
- If status is omitted, use the tenant default `interaction` status or fail with a clear setup error if missing.
- Insert into `interactions` as a future-dated interaction/follow-up.
- Emit `INTERACTION_LOGGED` using existing payload builders through a lazy event publisher helper and deterministic idempotency key.
- Write run audit.
- Return created activity summary.

#### `crm.send_quote`

- Register action ID `crm.send_quote`, version `1`.
- Inputs:
  - `quote_id`
  - optional `email_addresses`
  - optional `subject`
  - optional `message`
  - optional `no_op_if_already_sent` default `true`
- Validate quote exists in tenant and is not a template.
- Enforce billing update/read authorization equivalent to existing quote send behavior.
- Respect existing approval settings and quote status rules:
  - if approval is required, only approved quotes can be sent
  - otherwise only draft or approved quotes can be sent
- Prefer shared-safe reuse of underlying billing quote send services/models. Do not import `withAuth` server action wrappers directly into shared runtime. If direct package import is unsafe, extract a shared-safe quote send helper first.
- Preserve existing send behavior: transition quote to `sent`, set `sent_at`, store quote PDF best-effort, send quote email best-effort, record quote activity.
- Return quote summary plus send metadata such as previous status, new status, sent timestamp, recipients, email_sent, and message ID where available.
- Write run audit with quote ID, previous/new status, and email metadata.

### Functional Requirements — Roadmap / Follow-on Scope

These are explicitly useful but not required for the first implementation pass unless scope is expanded.

- `crm.create_interaction_type`: create tenant-specific CRM activity types such as QBR, Site Visit, or Upsell Call.
- `crm.update_activity_status`: dedicated status-transition wrapper around `crm.update_activity` for simple “mark completed/closed” workflows.
- `crm.create_quote`: create a quote from workflow, including template-based creation where safe.
- `crm.convert_quote`: convert quote to draft contract, invoice, or both using existing quote conversion services.
- `crm.find_quotes`: search quotes by client, status, date range, template flag, and pagination options.
- `crm.submit_quote_for_approval`: move eligible draft quotes into quote approval flow.
- `crm.tag_entity`: apply tags to client, contact, or interaction using existing tag definitions/mappings and TAG events.
- `crm.create_client_note`: only if a CRM-wide note action is still needed after the newly merged `clients.add_note` action; otherwise prefer Client/Contact module note actions.

### Cross-cutting Requirements

- Register all first-pass actions in `shared/workflow/runtime/actions/businessOperations/crm.ts` via existing `registerCrmActions()` and `registerBusinessOperationsActionsV2()` wiring.
- Use `withTenantTransaction`, `requirePermission`, `writeRunAudit`, `throwActionError`, and `rethrowAsStandardError` from `businessOperations/shared.ts`.
- Use `withWorkflowJsonSchemaMetadata` from `shared/workflow/runtime/jsonSchemaMetadata.ts` for supported picker fields.
- Use action-provided idempotency for create/send operations where retry duplicates are possible; use engine-provided idempotency for reads and deterministic updates.
- Use lazy dynamic import for workflow event publication from shared runtime action handlers, mirroring the new Client workflow actions.
- Use deterministic event idempotency keys for emitted workflow events.
- Keep implementation additive and backward compatible with existing workflows.

## Data / API / Integrations

### Current workflow files

- `shared/workflow/runtime/actions/businessOperations/crm.ts`
- `shared/workflow/runtime/actions/businessOperations/clients.ts`
- `shared/workflow/runtime/actions/businessOperations/tickets.ts`
- `shared/workflow/runtime/actions/registerBusinessOperationsActions.ts`
- `shared/workflow/runtime/designer/actionCatalog.ts`
- `shared/workflow/runtime/jsonSchemaMetadata.ts`
- `shared/workflow/runtime/actions/businessOperations/shared.ts`

### Existing CRM/client files and patterns

- `packages/clients/src/actions/interactionActions.ts`
  - `getInteractionsForEntity`
  - `getRecentInteractions`
  - `updateInteraction`
  - `addInteraction`
- `packages/clients/src/models/interactions.ts`
  - `getForEntity`
  - `getRecentInteractions`
  - `updateInteraction`
  - `getById`
- `packages/clients/src/actions/interactionTypeActions.ts`
  - `createInteractionType`
- `shared/workflow/streams/domainEventBuilders/crmInteractionNoteEventBuilders.ts`
  - `buildInteractionLoggedPayload`
  - `buildNoteCreatedPayload`

### Existing quote files and patterns

- `packages/billing/src/actions/quoteActions.ts`
  - `createQuote`
  - `sendQuote`
  - `submitQuoteForApproval`
  - `convertQuoteToContract`
  - `convertQuoteToInvoice`
  - `convertQuoteToBoth`
- `packages/billing/src/models/quote.ts`
  - `getById`
  - `getByNumber`
  - `listByTenant`
  - `listByClient`
- `packages/billing/src/services/quoteConversionService.ts`
  - `convertQuoteToDraftContract`
  - `convertQuoteToDraftInvoice`
  - `convertQuoteToDraftContractAndInvoice`

### Existing tag/event files

- `packages/tags/src/actions/tagActions.ts`
- `shared/workflow/streams/domainEventBuilders/tagEventBuilders.ts`
- `shared/workflow/runtime/schemas/crmEventSchemas.ts`

### Existing tables likely touched

- `interactions`
- `interaction_types`
- `system_interaction_types`
- `statuses` where `status_type = 'interaction'`
- `clients`
- `contacts`
- `tickets`
- `quotes`
- quote activity/document/email-related tables used by existing quote send behavior
- `audit_logs`

## Security / Permissions

- All queries and mutations must filter by tenant.
- Activity reads must require a safe read permission. Exact permission mapping must be documented before implementation if no CRM-specific permission exists.
- Activity updates and scheduling must require update/create permissions for the relevant CRM resource or safest existing client/contact permission.
- Quote send must require the same effective billing read/update authorization as existing quote send behavior, including authorization-kernel checks where applicable.
- Workflow actor should remain the actor for audit/event attribution unless a future action version explicitly supports permission-gated actor override.
- Do not allow workflow inputs to set `tenant`, `interaction_id`, quote ownership, or other system-managed fields.

## Observability

- Write `audit_logs` rows with `writeRunAudit` for all side-effectful actions.
- Include action ID/version, target IDs, changed fields, before/after status where relevant, and event/send metadata.
- Use existing workflow event builders and lazy publication helpers for `INTERACTION_LOGGED` where new interactions are created.
- Do not add new metrics in this plan.

## Rollout / Migration

- No database migration is expected for the first pass.
- Runtime/catalog additions are additive and should not break existing workflow definitions.
- Existing `crm.create_activity_note` remains available and unchanged.
- Designer catalog should expose the new CRM actions automatically after runtime initialization.
- If implementation discovers missing status/type constraints or missing quote-safe helper boundaries, update the plan before adding migrations or package refactors.

## Open Questions

1. What is the correct permission resource/action for CRM interactions? Candidate mappings: `client:read/update`, `contact:read/update`, or a CRM/activity-specific permission if one exists.
2. Should `crm.update_activity` emit a workflow event? There is `INTERACTION_LOGGED` for creation, but no obvious `INTERACTION_UPDATED` schema in current CRM event schemas.
3. Should `crm.schedule_activity` be considered a normal `INTERACTION_LOGGED` event even when the interaction date is in the future?
4. Is quote send safe to extract into a shared helper callable from `shared/workflow/runtime`, or should the workflow action perform equivalent persistence while avoiding server-only action imports?
5. Should `crm.send_quote` no-op for already sent quotes, or should it support resend semantics in a later `crm.resend_quote` action?
6. Should `crm.create_client_note` be dropped from the CRM roadmap because `clients.add_note` now exists, or retained as a cross-entity CRM note wrapper?

## Acceptance Criteria (Definition of Done)

- Runtime initialization registers `crm.find_activities`, `crm.update_activity`, `crm.schedule_activity`, and `crm.send_quote` at version `1`.
- Designer catalog shows the new actions under the CRM group with meaningful labels, descriptions, input schemas, output schemas, and supported picker metadata.
- `crm.find_activities` returns tenant-scoped filtered interaction summaries and rejects unsafe unbounded queries.
- `crm.update_activity` validates editable fields, status/type IDs, and tenant ownership, then returns before/after summaries and changed fields.
- `crm.schedule_activity` creates a future-dated interaction linked to valid client/contact/ticket records, audits the change, and emits `INTERACTION_LOGGED` through the shared-runtime-safe event publishing pattern.
- `crm.send_quote` sends/publishes an eligible quote using existing quote send semantics or a shared-safe extraction of that logic, audits the result, and returns send metadata.
- All side-effectful actions enforce permissions and write run audit rows.
- DB-backed tests cover representative success and guard/failure paths for activity update/schedule and quote send eligibility.
- Unit tests cover action registration, designer CRM grouping, picker metadata, and event payload compatibility.
- No existing workflow runtime, Client workflow action, Ticket workflow action, or CRM activity note tests regress.