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

Scratchpad — Workflow Client Actions

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

What This Is

Working notes for adding missing Client module workflow actions to Workflow Runtime V2.

Decisions

• (2026-04-25) Draft action ids use clients.create, clients.update, clients.archive, clients.delete, clients.duplicate, clients.add_tag, clients.assign_to_ticket, clients.add_note, and clients.add_interaction. Rationale: keeps all requested actions in the Client module and allows current catalog prefix grouping to work automatically.
• (2026-04-25) Resolved: use clients.update as the implementation id for EDIT client, with UI label "Edit Client". Rationale: action ids are durable runtime/API-style contracts while UI labels can match user-facing wording.
• (2026-04-25) Resolved: clients.add_note appends to the client notes document, not the generic CRM activity note/interactions path. Rationale: crm.create_activity_note already exists and uses interactions; the requested action is explicitly for the Client module, and "add" should not replace existing notes.
• (2026-04-25) Resolved: clients.delete is validated hard delete and requires confirm: true; clients.archive is added now as a separate archive/deactivate action. Rationale: delete and archive are materially different operations and should not be overloaded, and hard delete should require explicit destructive-action confirmation.

Discoveries / Constraints

• (2026-04-25) Existing client workflow actions are in shared/workflow/runtime/actions/businessOperations/clients.ts and currently register only clients.find and clients.search.
• (2026-04-25) Business operations registration path is already wired: shared/workflow/runtime/actions/registerBusinessOperationsActions.ts calls registerClientActions().
• (2026-04-25) The designer catalog already maps clients.* actions into the built-in Client group via shared/workflow/runtime/designer/actionCatalog.ts; no new catalog group should be needed.
• (2026-04-25) Existing helper patterns are in shared/workflow/runtime/actions/businessOperations/shared.ts: withTenantTransaction, requirePermission, writeRunAudit, throwActionError, rethrowAsStandardError, actionProvidedKey, uuidSchema, and isoDateTimeSchema.
• (2026-04-25) shared/models/clientModel.ts has shared create/update/get helpers, but server/src/lib/api/services/ClientService.ts has richer delete behavior, tag handling, inactive-client side effects, and workflow event publishing.
• (2026-04-25) packages/clients/src/actions/clientNoteActions.ts shows current client notes document behavior using clients.notes_document_id, createBlockDocument, and updateBlockContent.
• (2026-04-25) packages/clients/src/actions/interactionActions.ts and packages/clients/src/models/interactions.ts show current interaction creation/default-status/event behavior.
• (2026-04-25) Existing crm.create_activity_note creates an interactions row for target types including client; this may overlap conceptually with clients.add_note unless the latter is explicitly defined as client notes-document behavior.
• (2026-04-25) tickets.link_entities does not currently support linking clients to tickets; clients.assign_to_ticket should likely update tickets.client_id directly rather than using the generic ticket link table.
• (2026-04-25) No existing duplicate-client implementation was found in quick code search; duplicate semantics need scope confirmation.

Commands / Runbooks

• (2026-04-25) Context reads/searches used while drafting:
  • find ee/docs/plans -maxdepth 2 -type f | sort | tail -80
  • rg -n "register.*Actions|clients.find|clients.search|actionCatalog|x-workflow-picker-kind" shared ee server -g'*.ts' -g'*.tsx'
  • rg -n "class ClientModel|ClientModel|createClient|updateClient|deleteClient|interaction|tag_mappings" server/src shared packages -g'*.ts' -g'*.tsx'
  • rg -n "Duplicate Client|duplicateClient|client.*duplicate" packages/clients server/src -g'*.ts' -g'*.tsx'

Links / References

• shared/workflow/runtime/actions/businessOperations/clients.ts
• shared/workflow/runtime/actions/businessOperations/tickets.ts
• shared/workflow/runtime/actions/businessOperations/crm.ts
• shared/workflow/runtime/actions/businessOperations/shared.ts
• shared/workflow/runtime/actions/registerBusinessOperationsActions.ts
• shared/workflow/runtime/designer/actionCatalog.ts
• shared/models/clientModel.ts
• server/src/lib/api/services/ClientService.ts
• packages/clients/src/actions/clientNoteActions.ts
• packages/clients/src/actions/interactionActions.ts
• packages/clients/src/models/interactions.ts
• shared/workflow/runtime/actions/__tests__/registerTicketActionPickerMetadata.test.ts
• server/src/test/unit/workflowTicketAssignmentModelRuntime.test.ts

Open Questions

• Resolved: EDIT client action id is clients.update, with UI label "Edit Client".
• Resolved: clients.add_note appends to the client notes document; it does not replace notes and does not create an activity note interaction.
• Resolved: clients.duplicate copies safe core profile fields, copies tags by default, supports optional copy_locations, and leaves contacts/notes out of v1.
• Resolved: clients.delete is validated hard delete with required confirm: true; add clients.archive now for archive/inactivate semantics.
• Resolved: clients.assign_to_ticket preserves omitted contact/location fields; explicit null clears them, and non-null provided values must belong to the selected client.
• Resolved: clients.add_interaction uses the workflow actor as user_id in v1. Future versions may add a permission-gated user override after target-user validation and audit semantics are designed.

Implementation Log

• (2026-04-25) Implemented Client runtime action expansion in shared/workflow/runtime/actions/businessOperations/clients.ts:

  • Added and registered all requested mutating actions: clients.create, clients.update, clients.archive, clients.delete, clients.duplicate, clients.add_tag, clients.assign_to_ticket, clients.add_note, clients.add_interaction.
  • Added picker metadata helper usage for client/ticket/contact/location fields in new action schemas.
  • Added idempotency metadata (actionProvided) for create/duplicate/add_tag/add_note/add_interaction.
  • Added audit logging (writeRunAudit) across mutating handlers.
  • Added standardized error classification pathways via throwActionError and rethrowAsStandardError in mutation handlers.

• (2026-04-25) Implemented create/update/archive/delete semantics:

  • clients.create: tenant-scoped create, optional location bootstrap from address/phone/email inputs, optional initial tags, and client summary output.
  • clients.update: non-empty patch, changed-field reporting, tenant-scoped mutation, and inactive-side-effect deactivation for contacts/client users.
  • clients.archive: idempotent inactive transition with no-op behavior when already inactive.
  • clients.delete: confirm: true guard, default-client protection, explicit on_not_found behavior, dependency-validated deletion path via deleteEntityWithValidation, and cleanup of client-owned artifacts.

• (2026-04-25) Implemented duplicate/tag/ticket-assignment/notes/interactions:

  • clients.duplicate: safe profile duplication with required new client name, copy_tags default true, and opt-in copy_locations.
  • clients.add_tag: tag definition upsert + idempotent tag mappings with added/existing counts and summaries.
  • clients.assign_to_ticket: validates ticket/client existence, validates provided contact/location belongs to selected client, preserves omitted contact/location, and supports explicit null clear semantics.
  • clients.add_note: append-only note block behavior on client notes document with create-if-missing path.
  • clients.add_interaction: validates optional contact/ticket relationships, defaults interaction status when omitted, and always uses workflow actor as user_id.

• (2026-04-25) Added workflow event publication parity in runtime action handlers where feasible:

  • CLIENT_CREATED on create.
  • CLIENT_UPDATED on update when effective updated fields exist.
  • CLIENT_ARCHIVED on first archive transition.
  • NOTE_CREATED when add-note creates a new notes document.
  • INTERACTION_LOGGED on add-interaction.
  • Event publishing is implemented as best-effort lazy import (publishWorkflowDomainEvent) to keep shared runtime tests stable when event-bus module resolution is unavailable in test-only contexts.

• (2026-04-25) Added unit coverage for registration/catalog/picker metadata:

  • shared/workflow/runtime/actions/__tests__/registerClientActionsMetadata.test.ts
  • shared/workflow/runtime/__tests__/workflowDesignerClientCatalogRuntime.test.ts
  • Coverage scope:
    • action registration IDs/labels/side-effect/idempotency metadata (T001)
    • Client group catalog exposure from runtime registrations (T002)
    • picker metadata on assign/note/interaction schemas (T003)

Verification

• (2026-04-25) Build/compile validation:

  • npm run -s build:shared

• (2026-04-25) Targeted unit tests (shared runtime root):

  • npx vitest run --root shared workflow/runtime/actions/__tests__/registerClientActionsMetadata.test.ts workflow/runtime/__tests__/workflowDesignerClientCatalogRuntime.test.ts

• (2026-04-25) Follow-up hardening: switched workflow-event publishing in runtime client actions to lazy dynamic import helper (publishWorkflowDomainEvent) to avoid shared-root test module-resolution failures while preserving runtime publication behavior.

• (2026-04-25) Follow-up hardening: standardized not-found/internal error signaling in helper paths (ensureClientExists, ensureTicketExists, default interaction status lookup) to use throwActionError categories/codes directly.

Implementation Log — 2026-04-25 (Checkpoint 2)

• Expanded DB-backed workflow client action coverage in shared/workflow/runtime/actions/__tests__/businessOperations.clients.db.test.ts to cover:
  • T004 create + tags + action-provided idempotency-key fallback behavior
  • T005 update + cross-tenant not-found
  • T006 delete guardrails (confirm, default-client guard, dependency conflict)
  • T007 duplicate copy semantics (tags by default, optional locations, contacts excluded)
  • T008 add_tag idempotent no-duplicate behavior
  • T009 assign_to_ticket preserve/clear semantics
  • T010 assign_to_ticket relationship validation for contact/location
  • T011 add_note create-if-missing + append semantics
  • T012 add_interaction default status + relationship validation + actor ownership
  • T013 permission-denied coverage for all mutating client actions
  • T015 archive semantics + associated contact/client-user deactivation and idempotent second run
• Left T014 pending because it requires runtime-level action.call smoke execution with saveAs and downstream expression usage (separate harness from direct action handler DB tests).
• Marked F024 implemented because DB-backed mutation + guard coverage is now added across representative success/failure paths.

Implementation Log — 2026-04-25 (Checkpoint 2, code fix)

• Updated ensureClientTagMappings in shared/workflow/runtime/actions/businessOperations/clients.ts to avoid using insert-error control flow for duplicate mappings/definitions in the same transaction.
• Rationale: catching 23505 inside a PostgreSQL transaction still leaves the transaction aborted; subsequent audit writes fail with "current transaction is aborted".
• New behavior: pre-check existing mappings first, insert only when missing, and classify duplicates as existing without relying on failed inserts.

Commands / Verification — 2026-04-25 (Checkpoint 2)

• npx vitest run --root shared workflow/runtime/actions/__tests__/businessOperations.clients.db.test.ts
  • Result: passing (10 tests).
• npx vitest run --root shared workflow/runtime/actions/__tests__/registerClientActionsMetadata.test.ts workflow/runtime/__tests__/workflowDesignerClientCatalogRuntime.test.ts
  • Result: passing (3 tests).
• npm run -s build:shared
  • Result: passing.
• Added runtime smoke coverage for T014 with shared/workflow/runtime/nodes/__tests__/actionCallClientSaveAsRuntime.test.ts.
  • Uses real action.call and transform.assign node handlers.
  • Invokes representative clients.create action id (handler stubbed in-test for deterministic runtime behavior).
  • Verifies saveAs output becomes available under vars.<saveAs> and is consumed by downstream expression assignments.
• Verification:
  • npx vitest run --root shared workflow/runtime/nodes/__tests__/actionCallClientSaveAsRuntime.test.ts workflow/runtime/actions/__tests__/businessOperations.clients.db.test.ts