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

# PRD — CRM Workflow Follow-up Actions

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

## Summary

Add the remaining CRM workflow actions after the first-pass CRM plan (`workflow-crm-actions`) lands. This follow-up plan covers interaction taxonomy, simple activity status transitions, quote creation/search/conversion/approval, and CRM activity tagging.

Planned actions:

1. `crm.create_interaction_type`
2. `crm.update_activity_status`
3. `crm.create_quote`
4. `crm.add_quote_item`
5. `crm.create_quote_from_template`
6. `crm.find_quotes`
7. `crm.submit_quote_for_approval`
8. `crm.convert_quote`
9. `crm.tag_activity`

Explicitly out of scope: `crm.create_client_note`. Use `clients.add_note` for client notes and add a future `contacts.add_note` action under the Contact module if contact note automation is needed.

This plan intentionally builds on discoveries from the recent workflow updates and the first CRM plan: shared runtime actions must not import `withAuth` server action wrappers directly, picker metadata should follow current Workflow Designer conventions, event publication should use lazy shared-runtime-safe helpers, and DB-backed tests should validate real migrated schema behavior.

## Problem

The first-pass CRM plan unlocks activity lookup/update/scheduling and quote sending, but it leaves several high-value CRM automation gaps:

- MSPs cannot create their own CRM activity taxonomy from workflows.
- Workflows need a simple “mark this activity completed/closed/won” action without constructing a full patch object.
- Quote automation remains incomplete without create/search/item/approval/conversion actions.
- CRM activity tagging is not available for interactions/activities.

These gaps matter because MSP automations often span support, account management, and billing: identify a client state, tag/account-classify it, create or submit a quote, and convert accepted quote value along the way.

## Goals

- Complete the next CRM workflow action layer after first-pass activity and send-quote support.
- Keep action IDs under `crm.*` so the existing Designer CRM group continues to work.
- Provide quote pipeline actions that are safe, permission-checked, and consistent with existing quote lifecycle rules.
- Provide CRM taxonomy and status helpers that simplify common workflow authoring.
- Provide a dedicated tag action for CRM activities/interactions.
- Keep note creation on module-specific actions: existing `clients.add_note` and a future `contacts.add_note` if needed.
- Reuse existing model/service behavior where safe, extracting shared-safe helpers where necessary.

## Non-goals

- Replacing first-pass CRM actions (`crm.find_activities`, `crm.update_activity`, `crm.schedule_activity`, `crm.send_quote`).
- Replacing Client module workflow actions such as `clients.add_note` or `clients.add_interaction`.
- Adding a CRM-scoped client/contact note wrapper; note automation should use module-specific actions (`clients.add_note`, future `contacts.add_note`).
- Replacing quote UI/API behavior or adding new quote lifecycle states.
- Introducing a generic arbitrary-table patch action.
- Calling `withAuth` server actions directly from `shared/workflow/runtime`.
- Building new Workflow Designer controls beyond metadata-driven picker support.
- Adding broad quote item editing beyond the create-quote input scope described here.

## Prerequisites / Dependencies

- First-pass CRM plan should be implemented or at least its shared helper decisions should be resolved:
  - lazy workflow event publisher helper for CRM actions
  - CRM permission mapping
  - quote shared-helper/package-boundary approach
  - common CRM activity summary schemas
- Recent Client workflow action patterns remain the model for picker metadata, event publication, idempotency, and DB-backed tests.
- Quote actions must respect existing quote status transitions from `packages/billing/src/schemas/quoteSchemas.ts`.

## Users and Primary Flows

### Users

- MSP admin building cross-functional workflows.
- Account manager automating CRM follow-ups and QBR/upsell workflows.
- Sales/finance operator automating quote pipeline steps.
- Internal Alga PSA engineer maintaining Workflow Runtime V2 business operations.

### Primary flows

1. **Create CRM taxonomy automatically**
   - Workflow detects a new MSP process or onboarding template.
   - Workflow creates a custom interaction type such as `QBR`, `Site Visit`, or `Upsell Call` if it does not exist.

2. **Mark an activity status without a full patch**
   - Workflow finds or creates an activity.
   - Workflow runs `crm.update_activity_status` with a target status ID or status name.
   - The action validates the interaction status and returns the previous/current status.

3. **Create and build a quote**
   - Workflow creates a quote header for a client/contact after a qualifying ticket or opportunity event.
   - Workflow either creates a blank quote header with `crm.create_quote` and adds items with `crm.add_quote_item`, or creates a populated quote from a template with `crm.create_quote_from_template`.
   - Workflow optionally submits the quote for approval when tenant settings or business rules require it.

4. **Find quotes before branching**
   - Workflow checks whether the client already has open quotes.
   - If none exist, it creates one; if one exists, it updates/sends/submits it through existing CRM quote actions.

5. **Convert an accepted quote**
   - Workflow receives a quote accepted event or polls/fetches accepted quote state.
   - Workflow converts quote content to a draft contract, draft invoice, or both based on selected items.

6. **Tag CRM activities**
   - Workflow applies tags like `Needs QBR`, `Upsell Candidate`, or `Onboarding Risk` to interactions/activities.
   - Client and contact tagging stay in their own module actions.
   - Tag definition creation and tag application events are emitted consistently.

## UX / UI Notes

- All actions should appear under the existing Workflow Designer CRM group via the `crm.*` prefix.
- Suggested labels:
  - `crm.create_interaction_type` → Create Activity Type
  - `crm.update_activity_status` → Update Activity Status
  - `crm.create_quote` → Create Quote
  - `crm.add_quote_item` → Add Quote Item
  - `crm.create_quote_from_template` → Create Quote from Template
  - `crm.find_quotes` → Find Quotes
  - `crm.submit_quote_for_approval` → Submit Quote for Approval
  - `crm.convert_quote` → Convert Quote
  - `crm.tag_activity` → Tag CRM Activity
- Use picker metadata where supported:
  - `client_id` → `client`
  - `contact_id` → `contact`, dependent on `client_id` where appropriate
  - `ticket_id` → `ticket`
  - `user_id` → `user`
  - `quote_id`, `interaction_id`, `interaction_type_id`, and `interaction_status_id` remain UUID fields in v1 unless picker support already exists or is separately introduced.
- Quote action outputs should include enough summary fields for branching: quote ID, number, status, client ID, totals, conversion target IDs, and approval/send state.

## Requirements

### `crm.create_interaction_type`

- Register action ID `crm.create_interaction_type`, version `1`.
- Inputs:
  - `type_name`
  - optional `icon`
  - optional `display_order`
  - optional `idempotency_key`
  - optional `if_exists`: `return_existing` or `error` (default `return_existing`)
- Validate non-empty type name and reasonable length.
- Enforce tenant uniqueness by normalized type name where possible.
- If `display_order` is omitted, assign next display order using existing `interaction_types` max order behavior.
- Set `created_by` to workflow actor.
- Require `settings:update` because activity types are tenant CRM taxonomy/configuration.
- Return interaction type summary and `created` boolean.
- Use action-provided idempotency.
- Write run audit.

### `crm.update_activity_status`

- Register action ID `crm.update_activity_status`, version `1`.
- Inputs:
  - `activity_id`
  - either `status_id` or `status_name`
  - optional `reason`
  - optional `no_op_if_already_status` default `true`
- Validate activity exists in tenant.
- Resolve/validate target status from `statuses` where `status_type = 'interaction'`.
- If already in target status and no-op is true, return no-op without duplicate audit/event noise.
- Update only `status_id` and timestamp/audit metadata as available.
- Return activity ID, previous/current status IDs/names, `no_op`, and updated activity summary.
- Implement as a dedicated wrapper around the same safe update path used by `crm.update_activity`.

### `crm.create_quote`

- Register action ID `crm.create_quote`, version `1`.
- Scope v1 to quote header creation only. Quote item creation is handled by `crm.add_quote_item`.
- Inputs should support a constrained, workflow-friendly subset of quote header creation:
  - `client_id`
  - optional `contact_id`
  - `title`
  - optional `description`
  - `quote_date`
  - `valid_until`
  - optional `po_number`
  - optional `internal_notes`
  - optional `client_notes`
  - optional `terms_and_conditions`
  - optional `currency_code` default `USD`
  - optional `idempotency_key`
- Validate non-template quotes require client ID.
- Validate `valid_until >= quote_date`.
- Validate contact belongs to client when provided.
- Use existing quote model/schema behavior where package-boundary safe.
- Return quote summary.
- Require billing create authorization and quote read authorization decisions equivalent to existing quote actions.
- Use action-provided idempotency and run audit.

### `crm.add_quote_item`

- Register action ID `crm.add_quote_item`, version `1`.
- Inputs:
  - `quote_id`
  - `description`
  - `quantity`
  - optional `unit_price`
  - optional `unit_of_measure`
  - optional `display_order`
  - optional `phase`
  - optional `is_optional` default `false`
  - optional `is_selected` default `true`
  - optional `is_recurring` default `false`
  - optional `billing_frequency`
  - optional `billing_method`: `fixed`, `hourly`, or `usage`
  - optional `is_discount` default `false`
  - optional `discount_type`: `percentage` or `fixed`
  - optional `discount_percentage`
  - optional `applies_to_item_id`
  - optional `applies_to_service_id`
  - optional `is_taxable` default `true`
  - optional `tax_region`
  - optional `tax_rate`
  - optional `location_id`
  - optional `cost`
  - optional `cost_currency`
  - optional `idempotency_key`
- Validate quote exists in tenant and is editable.
- Reject adding items to quote templates in v1 unless template support is explicitly resolved later.
- Validate line item fields using existing quote item schema rules where package-boundary safe:
  - recurring items require billing frequency.
  - discount items require discount type.
  - percentage discounts require discount percentage.
- Assign `display_order` deterministically when omitted.
- Persist item through shared-safe quote item model/helper behavior.
- Recalculate quote financials after insertion.
- Return quote item summary plus refreshed quote summary/totals.
- Require billing update/read authorization equivalent to existing quote item behavior.
- Use action-provided idempotency and run audit.

### `crm.create_quote_from_template`

- Register action ID `crm.create_quote_from_template`, version `1`.
- Inputs:
  - `template_id`
  - `client_id`
  - optional `contact_id`
  - optional `title` override
  - optional `quote_date` override
  - optional `valid_until` override
  - optional `po_number`
  - optional `internal_notes` override/append decision if supported safely
  - optional `client_notes` override/append decision if supported safely
  - optional `currency_code` override if supported safely
  - optional `idempotency_key`
- Validate `template_id` points to a tenant quote template (`is_template = true`).
- Validate target client exists and contact belongs to that client when supplied.
- Reuse/extract shared-safe behavior from existing quote template creation logic; do not import `withAuth` server action wrappers directly into shared runtime.
- Copy safe template header fields and template items to the new quote.
- Apply supplied overrides after template defaults.
- Recalculate quote financials after copying items.
- Return created quote summary and created item summaries.
- Require billing create/read authorization equivalent to existing quote template creation behavior.
- Use action-provided idempotency and run audit.

### `crm.find_quotes`

- Register action ID `crm.find_quotes`, version `1`.
- Side-effect-free.
- Inputs:
  - optional `quote_id`
  - optional `quote_number`
  - optional `client_id`
  - optional `status`
  - optional `date_from`
  - optional `date_to`
  - optional `is_template` default `false`
  - pagination and sorting fields aligned with `Quote.listByTenant`
  - optional `on_empty`: `return_empty` or `error`
- Require at least one meaningful filter or an explicit bounded date range unless a small page size is enforced.
- Enforce billing read authorization and quote authorization-kernel filtering equivalent to existing quote list/read behavior.
- Return paginated quote summaries and first quote.

### `crm.submit_quote_for_approval`

- Register action ID `crm.submit_quote_for_approval`, version `1`.
- Inputs:
  - `quote_id`
  - optional `comment` or `reason`
  - optional `no_op_if_already_pending` default `true`
- Validate quote exists, is readable/updatable by workflow actor, is not a template, and is in draft status unless no-op applies.
- Transition status to `pending_approval` using existing quote status rules.
- Record quote activity if existing behavior does or if a shared helper is extracted.
- Return quote summary, previous status, new status, and no-op flag.
- Write run audit.

### `crm.convert_quote`

- Register action ID `crm.convert_quote`, version `1`.
- Inputs:
  - `quote_id`
  - `target`: `contract`, `invoice`, or `contract_and_invoice`
  - optional `no_op_if_already_converted` default `true`
- Validate quote exists, is not a template, and is eligible for conversion.
- Enforce billing create + update authorization equivalent to existing conversion actions.
- Reuse shared-safe conversion services:
  - `convertQuoteToDraftContract`
  - `convertQuoteToDraftInvoice`
  - `convertQuoteToDraftContractAndInvoice`
- Validate selected quote items support the requested target and return clear errors from conversion service as workflow action errors.
- Return quote summary plus created contract ID and/or invoice ID.
- Write run audit.

### `crm.tag_activity`

- Register action ID `crm.tag_activity`, version `1`.
- Scope v1 to interactions/activities only. Client and contact tagging stay in their own module actions.
- Inputs:
  - `activity_id`
  - `tags`: non-empty array of tag text values
  - optional `if_exists`: `no_op` or `error` (default `no_op`)
  - optional `idempotency_key`
- Validate target interaction/activity exists in tenant.
- Validate tag text using current tag validation rules.
- Create missing tag definitions and insert missing tag mappings idempotently.
- Require CRM interaction/activity update permission and tag create permission when creating new tag definitions, matching existing tag behavior where possible.
- Emit `TAG_DEFINITION_CREATED` for newly created definitions and `TAG_APPLIED` for newly applied mappings through lazy event publishing with deterministic keys.
- Return added/existing tag summaries and counts.
- Use action-provided idempotency and run audit.

### Explicitly dropped: `crm.create_client_note`

- Do not implement `crm.create_client_note` in this follow-up plan.
- Use `clients.add_note` for client note automation.
- Add a future `contacts.add_note` Contact-module action if workflows need contact note automation.
- Rationale: module-specific note actions keep ownership clearer and avoid duplicating the newly merged Client workflow note behavior under CRM.

### Cross-cutting Requirements

- Implement in `shared/workflow/runtime/actions/businessOperations/crm.ts` or extracted shared-safe helper modules.
- Do not directly import `packages/*/src/actions/*` server action wrappers into shared runtime action code.
- Use `withTenantTransaction`, `requirePermission`, `writeRunAudit`, `throwActionError`, and `rethrowAsStandardError`.
- Use `withWorkflowJsonSchemaMetadata` for picker-backed fields.
- Use deterministic idempotency and no-op behavior for retry-sensitive mutations.
- Keep all actions tenant-scoped and actor-attributed.
- Preserve `crm.create_activity_note` and first-pass CRM actions.

## Data / API / Integrations

### Key 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/businessOperations/shared.ts`
- `shared/workflow/runtime/jsonSchemaMetadata.ts`
- `packages/clients/src/actions/interactionTypeActions.ts`
- `packages/clients/src/actions/clientNoteActions.ts` (reference only; CRM note wrapper dropped)
- `packages/clients/src/actions/contact-actions/contactNoteActions.ts` (reference for future `contacts.add_note`, not this plan)
- `packages/tags/src/actions/tagActions.ts`
- `packages/billing/src/actions/quoteActions.ts`
- `packages/billing/src/models/quote.ts`
- `packages/billing/src/models/quoteItem.ts`
- `packages/billing/src/actions/quoteActions.ts` (`createQuoteFromTemplate` as behavior reference; do not import wrapper directly)
- `packages/billing/src/schemas/quoteSchemas.ts`
- `packages/billing/src/services/quoteConversionService.ts`
- `shared/workflow/streams/domainEventBuilders/tagEventBuilders.ts`
- `shared/workflow/streams/domainEventBuilders/crmInteractionNoteEventBuilders.ts`

### Tables likely touched

- `interaction_types`
- `interactions`
- `statuses`
- `quotes`
- `quote_items`
- `quote_activities`
- quote conversion target tables for contracts/invoices
- `tag_definitions`
- `tag_mappings`
- `clients`
- `contacts`
- `audit_logs`

## Security / Permissions

- `crm.create_interaction_type` requires `settings:update` because activity types are tenant CRM taxonomy/configuration.
- Resolve and document CRM interaction mutation permission for `crm.update_activity_status`.
- Quote actions, including `crm.add_quote_item`, must enforce billing create/read/update and quote authorization-kernel decisions equivalent to existing quote actions.
- `crm.tag_activity` must enforce CRM interaction/activity update permission and tag create permission when creating new definitions.
- Workflow actor remains the created_by/performed_by/audit actor unless a future version explicitly supports override.

## Observability

- Write run audit for all side-effectful actions.
- Emit existing events where supported:
  - `TAG_DEFINITION_CREATED`
  - `TAG_APPLIED`
- Quote pipeline actions should emit quote-specific workflow events only when matching `QUOTE_*` event schemas/builders already exist. If no matching quote event contract exists, remain audit-only plus existing quote activity records.
- Do not invent new `QUOTE_*` or `INTERACTION_UPDATED` events in this plan; new event contracts require a separate event-schema plan.
- Capture no-op outcomes in action outputs and audit where useful.

## Rollout / Migration

- No database migration is expected by default.
- All actions are additive.
- If quote helper extraction changes package exports, keep it backward compatible and covered by existing quote tests.
- `crm.create_client_note` is dropped in favor of module-specific actions; no migration or runtime registration is needed for it.

## Open Questions

All planning decisions for this follow-up scope are resolved. Implementation may still discover package-boundary details that need scratchpad updates.

## Acceptance Criteria (Definition of Done)

- Runtime initialization registers the selected follow-up actions at version `1`.
- Designer catalog shows the selected actions under CRM with labels, schema metadata, and output schemas.
- Interaction type creation is idempotent and permission-checked.
- Activity status update provides a simple validated transition/no-op wrapper.
- Quote create/add-item/template/find/submit/convert actions respect quote lifecycle, billing permissions, and authorization-kernel behavior.
- Quote pipeline actions emit only already-defined quote workflow events; when no matching quote event schema/builder exists, they remain audit-only plus quote activity records.
- CRM activity tagging creates definitions/mappings idempotently for interactions and emits tag events for new changes.
- `crm.create_client_note` remains absent; client note automation uses `clients.add_note`, and contact note automation is deferred to a future Contact-module action.
- DB-backed tests cover representative happy paths and high-risk guard cases.
- Existing first-pass CRM, Client, Ticket, and quote tests do not regress.