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

Scratchpad — CRM Workflow Actions

• Plan slug: workflow-crm-actions
• Created: 2026-04-25

What This Is

Rolling notes for expanding Workflow Runtime V2 CRM actions beyond crm.create_activity_note.

Decisions

• (2026-04-25) First implementation pass is scoped to crm.find_activities, crm.update_activity, crm.schedule_activity, and crm.send_quote. Rationale: these match the user's recommended high-value first pass and unlock CRM lookup/update/follow-up/quote-send workflows without committing to the entire roadmap at once.
• (2026-04-25) Keep all first-pass actions under crm.* so existing designer catalog grouping places them under the built-in CRM group.
• (2026-04-25) Do not call withAuth Next.js server action wrappers directly from shared/workflow/runtime. Reuse underlying models/services only when package-boundary safe, or extract shared-safe helpers first.
• (2026-04-25) Mirror latest Client workflow action patterns: picker metadata via withWorkflowJsonSchemaMetadata, lazy event-bus imports, deterministic event idempotency keys, and DB-backed shared-root tests.
• (2026-04-25) Treat crm.create_client_note as roadmap-only until we decide whether newly merged clients.add_note already satisfies the intended user need.

Discoveries / Constraints

• (2026-04-25) Current CRM workflow action file is shared/workflow/runtime/actions/businessOperations/crm.ts and only registers crm.create_activity_note.
• (2026-04-25) Latest main added substantial Client workflow action coverage in shared/workflow/runtime/actions/businessOperations/clients.ts, including clients.add_note and clients.add_interaction; CRM plan must avoid duplicating those module-specific semantics by accident.
• (2026-04-25) Client workflow actions introduced a local withWorkflowPicker helper using withWorkflowJsonSchemaMetadata and x-workflow-picker-kind; CRM should use the same convention for supported fields.
• (2026-04-25) Client workflow actions publish events using a lazy dynamic import helper (publishWorkflowDomainEvent) so shared-root tests do not fail when @alga-psa/event-bus is not resolvable. CRM should copy that pattern.
• (2026-04-25) Existing interaction server actions are in packages/clients/src/actions/interactionActions.ts: addInteraction, getInteractionsForEntity, getRecentInteractions, updateInteraction, getInteractionStatuses, and deleteInteraction.
• (2026-04-25) Existing interaction model is in packages/clients/src/models/interactions.ts and supports getForEntity, getRecentInteractions, addInteraction, updateInteraction, and getById, but those model methods call createTenantKnex internally; direct use from a workflow transaction may require careful adaptation or local query implementation.
• (2026-04-25) Existing interaction type server action is createInteractionType in packages/clients/src/actions/interactionTypeActions.ts and writes to interaction_types with created_by.
• (2026-04-25) Existing quote server actions are in packages/billing/src/actions/quoteActions.ts: createQuote, sendQuote, submitQuoteForApproval, conversion wrappers, and related helpers. These are withAuth server actions and should not be imported directly into shared runtime handlers.
• (2026-04-25) Existing quote model in packages/billing/src/models/quote.ts supports getById, getByNumber, listByTenant, listByClient, create, and update/status transition behavior.
• (2026-04-25) Quote conversion services in packages/billing/src/services/quoteConversionService.ts expose convertQuoteToDraftContract, convertQuoteToDraftInvoice, and convertQuoteToDraftContractAndInvoice for later roadmap actions.
• (2026-04-25) CRM event schemas/builders currently include INTERACTION_LOGGED, NOTE_CREATED, TAG_DEFINITION_CREATED, TAG_APPLIED, and TAG_REMOVED; no obvious INTERACTION_UPDATED event was found in initial search.
• (2026-04-25) Tag event builders exist in shared/workflow/streams/domainEventBuilders/tagEventBuilders.ts; tag action implementation can follow ticket/client tag patterns later.

Commands / Runbooks

• (2026-04-25) Initial discovery commands:
  • rg -n "export async function (updateInteraction|getRecentInteractions|getInteractionsForEntity|createInteractionType)|function (updateInteraction|getRecentInteractions|getInteractionsForEntity|createInteractionType)|createInteractionType|updateInteraction|getRecentInteractions|getInteractionsForEntity" packages server shared ee -g'*.ts' | head -160
  • rg -n "createQuote|sendQuote|convertQuoteToDraft|submit.*approval|find.*Quote|Quote" packages/billing server/src ee packages -g'*.ts' | head -220
  • rg -n "TAG_APPLIED|TAG_REMOVED|TAG_DEFINITION_CREATED|buildNoteCreatedPayload|buildInteractionLoggedPayload|NOTE_CREATED|INTERACTION_LOGGED" shared packages server ee -g'*.ts' | head -180
  • rg -n "export (async function|const) (createQuote|sendQuote|submitQuote|.*approval|find|getQuote|updateQuote|convertQuote)|function (createQuote|sendQuote|submitQuote)|const (createQuote|sendQuote|submitQuote)" packages/billing/src/actions/quoteActions.ts server/src -g'*.ts' | head -160
  • rg -n "list\\(|QuoteListOptions|getAll|page|filters|status|client_id" packages/billing/src/models/quote.ts | head -180

Links / References

• 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/actions/registerBusinessOperationsActions.ts
• shared/workflow/runtime/designer/actionCatalog.ts
• shared/workflow/runtime/jsonSchemaMetadata.ts
• packages/clients/src/actions/interactionActions.ts
• packages/clients/src/models/interactions.ts
• packages/clients/src/actions/interactionTypeActions.ts
• packages/billing/src/actions/quoteActions.ts
• packages/billing/src/models/quote.ts
• packages/billing/src/services/quoteConversionService.ts
• shared/workflow/streams/domainEventBuilders/crmInteractionNoteEventBuilders.ts
• shared/workflow/streams/domainEventBuilders/tagEventBuilders.ts
• shared/workflow/runtime/schemas/crmEventSchemas.ts

Open Questions

• What permission resource/action should govern CRM interaction reads and mutations? Candidate mappings are client, contact, or an existing CRM/activity-specific permission if present.
• Should crm.update_activity emit any workflow event, or should it only audit because there is no current INTERACTION_UPDATED schema?
• Should crm.schedule_activity emit INTERACTION_LOGGED even though it creates a future-dated interaction/follow-up?
• What is the safest package boundary for quote send logic from shared workflow runtime? Can we extract reusable quote send logic from packages/billing/src/actions/quoteActions.ts, or should workflow runtime implement an equivalent helper locally?
• Should crm.send_quote no-op on already sent quotes when no_op_if_already_sent is true, or should resend be explicitly out of scope until a crm.resend_quote action exists?
• Should crm.create_client_note remain on the CRM roadmap now that clients.add_note exists?

Implementation Log (2026-04-26)

• Implemented all first-pass CRM runtime actions in shared/workflow/runtime/actions/businessOperations/crm.ts:
  • crm.find_activities
  • crm.update_activity
  • crm.schedule_activity
  • crm.send_quote
• Preserved existing crm.create_activity_note behavior and registration.
• Added shared CRM runtime helper patterns to match current V2 conventions:
  • withWorkflowPicker + withWorkflowJsonSchemaMetadata
  • lazy event publication helper for workflow domain events
  • tenant-scoped detail joins and summary normalization for interactions
  • standardized validation + throwActionError/rethrowAsStandardError error mapping

Open Question Resolutions (2026-04-26)

• Permission mapping for CRM interactions:
  • crm.find_activities now requires client:read, and additionally requires contact:read / ticket:read when those filters are supplied.
  • crm.update_activity and crm.schedule_activity require client:update; crm.schedule_activity additionally requires ticket:read when ticket_id is provided.
  • Rationale: interactions are CRM records anchored to client relationships; supplemental resource permissions are enforced when filters/links depend on those resources.
• crm.update_activity event emission:
  • Decision: do not emit a CRM update domain event in v1; rely on run audit + returned before/after diff.
  • Rationale: no INTERACTION_UPDATED schema currently exists; avoided introducing new event schema in first pass.
• Future-dated schedule event semantics:
  • Decision: crm.schedule_activity emits INTERACTION_LOGGED with scheduled interaction_date and deterministic idempotency key.
  • Rationale: creation of the interaction record is the durable event; consumers can branch on time fields.
• Quote helper boundary:
  • Decision: crm.send_quote uses shared-runtime-safe DB/model helpers and best-effort internal helpers; it does not import withAuth server action wrappers.
  • Rationale: satisfies shared runtime boundary and keeps quote send semantics in workflow runtime.
• Already-sent quote behavior:
  • Decision: crm.send_quote no-ops by default when quote is already sent (no_op_if_already_sent=true), and returns metadata with no_op=true.
  • Decision: if no_op_if_already_sent=false, action raises validation error (resend out of scope for v1 action).
• crm.create_client_note roadmap decision:
  • Decision: remains roadmap-only; no implementation added in this pass.
  • Rationale: overlaps with existing clients.add_note behavior.

Test Coverage Added (2026-04-26)

• Added runtime/unit tests:
  • shared/workflow/runtime/actions/__tests__/registerCrmActionsMetadata.test.ts
  • shared/workflow/runtime/__tests__/workflowDesignerCrmCatalogRuntime.test.ts
  • shared/workflow/runtime/nodes/__tests__/actionCallCrmSaveAsRuntime.test.ts
• Added DB-backed action tests:
  • shared/workflow/runtime/actions/__tests__/businessOperations.crm.db.test.ts
  • Covers: find/update/schedule/send success, guard/failure paths, permission denials, INTERACTION_LOGGED publish path, and crm.create_activity_note regression.

Commands / Runbooks (2026-04-26)

• Runtime/unit tests:
  • cd shared && npx vitest workflow/runtime/actions/__tests__/registerCrmActionsMetadata.test.ts workflow/runtime/__tests__/workflowDesignerCrmCatalogRuntime.test.ts workflow/runtime/nodes/__tests__/actionCallCrmSaveAsRuntime.test.ts --run
• DB-backed CRM tests:
  • cd shared && npx vitest workflow/runtime/actions/__tests__/businessOperations.crm.db.test.ts --run