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

Scratchpad — Workflow Contact Actions

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

What This Is

Working notes for adding Contact module workflow actions: create, edit, deactivate, delete, duplicate, add tag, assign to ticket, add note, add interaction, add to client, and move to client.

Decisions

• 2026-04-25: Draft plan uses one workflow action per requested operation (contacts.create, contacts.update, etc.) instead of a single mode-based generic contact mutation action. Rationale: better workflow designer UX and clearer downstream output schemas.
• 2026-04-25: Draft plan keeps actions additive under the existing contacts.* prefix so the current designer catalog grouping should place them under Contact.
• 2026-04-25: Draft plan recommends requiring a new unique email for contacts.duplicate because contact primary emails are tenant-unique.
• 2026-04-25: Draft plan treats contacts.add_to_client and contacts.move_to_client as separate author-facing actions even though both ultimately update contacts.client_id; their conflict/idempotency semantics differ.
• 2026-04-25: User approved separating contact deactivation and hard deletion into two actions instead of using a flag. contacts.deactivate should be the safe idempotent action requiring contact:update; contacts.delete should remain destructive guarded hard delete requiring contact:delete.
• 2026-04-25: After merging latest main with workflow Client actions, contact actions should mirror the new Client runtime conventions where applicable: action-provided idempotency for create/duplicate/add_tag/add_note/add_interaction; engine-provided idempotency for update/deactivate/delete/assignment; destructive delete requires confirm: true; delete supports explicit on_not_found behavior.
• 2026-04-25: Updated contacts.add_note plan to be document-backed via contacts.notes_document_id, not interaction-backed. Rationale: latest clients.add_note establishes module-specific notes as append-only notes-document behavior, while contacts.add_interaction and generic crm.create_activity_note cover interaction rows.
• 2026-04-25: User resolved remaining product questions: duplicate contact requires a new unique email; contact-to-ticket should not set ticket client unless the existing app action does; contact add-tag should match client add-tag behavior; contact create/update/deactivate should publish domain events with the same lazy best-effort pattern as Client actions.

Discoveries / Constraints

• 2026-04-25: Existing contact workflow actions live in shared/workflow/runtime/actions/businessOperations/contacts.ts and currently register contacts.find and contacts.search.
• 2026-04-25: Runtime bootstrap calls registerBusinessOperationsActionsV2(), which calls registerContactActions(), so new actions in contacts.ts should flow into the catalog automatically after runtime initialization.
• 2026-04-25: ContactModel.createContact requires both full_name and email; it validates phone numbers, additional email addresses, primary email type, duplicate email, and client existence.
• 2026-04-25: ContactModel.updateContact supports patch-like update input but has strict primary-email promotion behavior. Changing primary email requires promoting an existing/additional email path rather than blindly swapping.
• 2026-04-25: Existing contact search in workflow uses tag_definitions / tag_mappings for contact tags (tagged_type = 'contact').
• 2026-04-25: server/src/lib/api/services/ContactService.ts has a private handleTags() that references contact_tags, but rg did not find a migration creating contact_tags. Implementation should verify and likely use tag_mappings/TagModel instead.
• 2026-04-25: Existing contact delete server action in packages/clients/src/actions/contact-actions/contactActions.tsx uses deleteEntityWithValidation('contact', ...) and performs cleanup for entity tags, phone rows, comments, portal invitations, notes document content/associations, Entra reconciliation queue references, then deletes from contacts.
• 2026-04-25: Contact deletion config in packages/core/src/config/deletion/index.ts lists dependencies: tickets, interactions, document associations, portal users, survey invitations/responses, and asset associations.
• 2026-04-25: Generic CRM note workflow action crm.create_activity_note already creates rows in interactions using system Note type and supports contact targets. After reviewing new Client actions, contacts.add_note should not wrap this path; it should append to the contact notes document, leaving interaction rows to contacts.add_interaction/crm.create_activity_note.
• 2026-04-25: Existing packages/clients/src/actions/interactionActions.ts has addInteraction behavior: requires either client_id or contact_name_id, derives client from contact if needed, and uses default interaction status when omitted.
• 2026-04-25: Permission resources exist for contact:create/read/update/delete, interaction:create/read/update/delete, and tag:create/read/update/delete in migrations/seeds.
• 2026-04-25: Existing ticket workflow actions define local picker metadata helpers in tickets.ts; contact actions may need similar helpers or shared extraction to keep schemas designer-friendly.
• 2026-04-25: Latest clients.assign_to_ticket uses a direct ticket update contract with previous/current outputs and relationship validation. contacts.assign_to_ticket should follow that style rather than requiring an expected_current_contact_id guard in v1.
• 2026-04-25: Quick app-path discovery found packages/tickets/src/components/ticket/TicketDetails.tsx contact-change code calls updateTicket(ticket_id, { contact_name_id: newContactId }) only, so the workflow contact assignment plan should not auto-set tickets.client_id in v1.
• 2026-04-25: Latest clients.add_tag avoids duplicate-insert error control flow because a caught 23505 still aborts the Postgres transaction. Contact tag implementation should pre-check mappings/definitions and return existing mappings idempotently.
• 2026-04-25: Latest Client actions use best-effort lazy workflow event publication for create/update/archive/note/interaction paths. Contact implementation should either match this pattern where event builders exist or document any intentional gap.

Commands / Runbooks

• 2026-04-25: Context discovery commands used:
  • find ee/docs/plans -maxdepth 2 -type f \( -name 'PRD.md' -o -name 'features.json' -o -name 'tests.json' -o -name 'SCRATCHPAD.md' \) | head -40
  • git log --oneline -5 && git status --short
  • rg -n "class ContactModel|createContact|updateContact|deleteContact|ContactModel\." shared server packages ee -g '*.ts' -g '*.tsx' | head -200
  • rg -n "contact_name_id|contacts|interaction|tag_mappings|tag_definitions" server shared packages ee -g '*.ts' -g '*.tsx' -g '*.cjs' | head -240
  • rg -n "createTable\\('contact_tags'|contact_tags" server/migrations ee/server/migrations -g '*.cjs'

Links / References

• shared/workflow/runtime/actions/businessOperations/contacts.ts
• shared/workflow/runtime/actions/businessOperations/tickets.ts
• shared/workflow/runtime/actions/businessOperations/crm.ts
• shared/workflow/runtime/actions/businessOperations/clients.ts
• shared/workflow/runtime/actions/registerBusinessOperationsActions.ts
• shared/models/contactModel.ts
• shared/models/tagModel.ts
• server/src/lib/api/schemas/contact.ts
• server/src/lib/api/services/ContactService.ts
• packages/clients/src/actions/contact-actions/contactActions.tsx
• packages/clients/src/actions/contact-actions/contactNoteActions.ts
• packages/clients/src/actions/interactionActions.ts
• packages/core/src/config/deletion/index.ts
• docs/AI_coding_standards.md

Resolved Questions

• contacts.duplicate requires a new unique email override.
• contacts.assign_to_ticket should only set tickets.contact_name_id in v1 unless an existing app action path is found to set tickets.client_id too. Current discovery indicates the app updates only contact_name_id.
• contacts.add_tag should create missing tag definitions exactly like clients.add_tag, under the same update-style permission policy.
• Contact create/update/deactivate workflow actions should publish contact domain events using the same lazy best-effort pattern as Client actions.

Implementation Log

• 2026-04-26: Implemented full contacts.* mutation action surface in shared/workflow/runtime/actions/businessOperations/contacts.ts:
  • Added registrations/schemas/handlers for contacts.create, contacts.update, contacts.deactivate, contacts.delete, contacts.duplicate, contacts.add_tag, contacts.assign_to_ticket, contacts.add_note, contacts.add_interaction, contacts.add_to_client, contacts.move_to_client.
  • Added workflow picker metadata helper usage for contact/client/ticket IDs and compact normalized contact summary output schema reuse.
  • Added tenant-scoped helper loaders and validations for contact/client/ticket lookups with standard workflow error categories.
  • Added action-provided idempotency for create/duplicate/add_tag/add_note/add_interaction and engine-provided idempotency for update/deactivate/delete/assignment/client-move actions.
  • Added permission checks per PRD (contact:create/read/update/delete, ticket:update) before mutation paths.
  • Added workflow run audit writes for all side-effectful contact actions via writeRunAudit.
  • Added guarded hard-delete implementation using deleteEntityWithValidation plus contact-owned artifact cleanup (tag_mappings, phone/email rows, comments, portal invitations, notes documents, enterprise queue references).
  • Added best-effort lazy workflow domain event publishing for contact create/update/deactivate plus note/interaction events.
• 2026-04-26: Implemented duplicate-contact constraints/behavior:
  • Requires explicit new primary email (input.email required in schema).
  • Supports field overrides and optional tag copy via canonical tag_definitions + tag_mappings.
  • Does not copy historical relationships (tickets/interactions/notes docs/etc.).
  • Additional emails are only copied when explicitly provided as an override. Rationale: current schema enforces tenant-unique normalized additional emails, so blind copying source additional emails can violate unique constraints.
• 2026-04-26: Added tests:
  • shared/workflow/runtime/actions/__tests__/registerContactActionsMetadata.test.ts for registration/catalog labels/idempotency and picker + compact output schema checks (T001/T002).
  • shared/workflow/runtime/actions/__tests__/businessOperations.contacts.db.test.ts for DB-backed integration + permission + audit/event coverage across contacts.* mutations (T003-T015).

Verification

• 2026-04-26: Ran targeted suites with shared Vitest config:
  • pnpm vitest --config shared/vitest.config.ts shared/workflow/runtime/actions/__tests__/registerContactActionsMetadata.test.ts shared/workflow/runtime/actions/__tests__/businessOperations.contacts.db.test.ts shared/workflow/runtime/actions/__tests__/businessOperations.contacts.emailSearch.test.ts
  • Result: pass (3 files, 16 tests).

Gotchas

• 2026-04-26: tickets.client_id in current schema is non-null in this test environment, so no-client ticket scenarios are not representable in DB setup. Assignment tests validate that contacts.assign_to_ticket only updates tickets.contact_name_id and preserves existing tickets.client_id unchanged.