PSA/ee/docs/plans/2025-10-31-qbo-accounting-export-migration-plan.md

QuickBooks Online Accounting Export Migration Plan

Purpose & Goals

• Replace the bespoke QuickBooks Online (QBO) workflow automations with the shared accounting export abstraction already used by Xero (accountingExportService, adapter registry, manual batch execution).
• Keep the OAuth connection sequence (server/src/app/api/integrations/qbo/callback/route.ts) but eliminate automatic event-triggered exports in favor of operator-driven batches.
• Deliver a consistent mapping and export UX (realm-aware, multi-adapter) so finance teams manage QBO mappings alongside Xero from the accounting settings and export dashboards.
• Ensure the new flow supports multiple QBO realms per tenant, preserves audit trails, and is covered by automated tests comparable to the Xero adapter.

Current State Overview

QBO Event-Driven Sync (legacy)

• OAuth callback registers workflow event attachments for INVOICE_CREATED, INVOICE_UPDATED, CLIENT_CREATED, CLIENT_UPDATED (see server/src/app/api/integrations/qbo/callback/route.ts).
• Workflows under server/src/lib/workflows/qboInvoiceSyncWorkflow.ts and server/src/lib/workflows/qboCustomerSyncWorkflow.ts orchestrate exports via workflow actions, human-in-the-loop tasks, and direct database reads.
• Workflow-callable actions (server/src/lib/actions/qbo/qboInvoiceActions.ts, server/src/lib/actions/qbo/qboCustomerActions.ts) wrap QboClientService, but embed mapping lookups, manual retries, and sync token handling outside the accounting export abstraction.
• Event listener (callback/route.ts) creates workflow_event_attachments entries so PSA events automatically trigger the workflows. Human approvals are handled through workflow tasks instead of accounting export batches.

Accounting Export Baseline (Xero)

• Xero integration already uses the export abstraction: server/src/lib/adapters/accounting/xeroAdapter.ts for transform/deliver, server/src/lib/qbo analogue for client service, and AccountingExportService.executeBatch for orchestration.
• Export batches are created manually from the accounting exports UI (server/src/components/billing-dashboard/accounting/AccountingExportsTab.tsx), validated for mappings, and delivered via adapters.
• Mapping UI uses AccountingMappingManager with adapter-specific module factories (e.g., server/src/components/integrations/xero/xeroMappingModules.ts) and shared CRUD actions.

Gap Summary

• Duplicate export paths: invoices can flow through workflows or the canonical export batches, creating inconsistent audit trails and error handling.
• Legacy workflows bake in client mapping logic, duplicate detection, and task handling that should move into shared services (AccountingMappingResolver, CompanyAccountingSyncService).
• Event attachments assume a single realm per tenant and bypass export readiness checks. Operators cannot stage exports or view batch history when workflows run automatically.
• Qbo mapping UI exists (server/src/components/integrations/qbo/qboMappingModules.ts) but is not yet wired to the same lifecycle as Xero (realm display, validations, manual runs) while workflows still expect legacy mapping helpers.

Target Outcomes

• Manual/export screen-driven QBO deliveries using AccountingExportService and QuickBooksOnlineAdapter.
• OAuth connect/disconnect remains intact; connecting a realm exposes the mapping manager and enables manual exports.
• Removed workflow/event plumbing so PSA events no longer trigger QBO exports; any needed automation should invoke the canonical batch APIs instead.
• Documentation, tests, and operational runbooks updated to reflect the new flow and deprecation of workflow-based sync.

---

Phase 1 – Legacy Workflow Decommissioning

• Stop creating workflow event attachments during OAuth callback; update server/src/app/api/integrations/qbo/callback/route.ts to only persist credentials and emit connection telemetry.
• Remove QBO-specific workflow handlers by deleting server/src/lib/workflows/qboInvoiceSyncWorkflow.ts and server/src/lib/workflows/qboCustomerSyncWorkflow.ts.
• Detach any remaining shared workflow registrations or catalog references to the removed QBO workflows (shared/workflow/init/registerWorkflowActions.ts, shared/workflow/streams/eventBusSchema.ts, shared/workflow/types/eventCatalog.ts).
• Retire workflow action shims in server/src/lib/actions/qbo/qboInvoiceActions.ts and server/src/lib/actions/qbo/qboCustomerActions.ts; ensure no remaining workflows depend on them.
• Author a migration script to delete workflow_event_attachments rows referencing the removed workflow IDs.
• Update operator documentation to instruct cancellation of any legacy QBO workflow executions prior to deploy.
• Communicate deprecation to stakeholders; update docs/integrations/quickbooks-technical.md and internal runbooks to remove references to automatic invoice/customer workflows.

Phase 2 – Adapter & Service Parity

• Validate server/src/lib/adapters/accounting/quickBooksOnlineAdapter.ts against the latest Xero adapter patterns (mapping resolution, payment term fallbacks, tax handling, customer auto-provision) and close remaining TODOs (metadata typing, line amount types, partial retries).
• Harden QboClientService to expose the same high-level operations Xero uses (createInvoices, token refresh telemetry, rate limit handling) and ensure adapter calls go through typed methods.
• Extend AccountingExportValidation to enforce QBO-specific prerequisites (service, tax region, payment term mappings, customer realm assignment) and surface actionable error codes.
• Build integration tests mirroring Xero coverage (server/src/test/integration/accounting/*) to exercise QuickBooks transform/deliver flows, including multi-realm scenarios and sync token updates.
• Provide repository helpers for invoice export mappings (re-using or expanding fetchInvoiceMapping/upsertInvoiceMapping inside the adapter) so repeated deliveries update sync tokens reliably.

Phase 3 – Mapping & Setup UX Alignment

• Finalize server/src/components/integrations/qbo/qboMappingModules.ts to match AccountingMappingManager expectations (realm-aware load, metadata JSON editor, overrides) and remove unused bespoke components (QboMappingFormDialog, QboItemMappingTable, etc.) once parity is confirmed.
• Ensure server/src/components/settings/integrations/QboIntegrationSettings.tsx mirrors Xero’s experience: connected state displays realm ID, mapping tabs, and validation hints; disconnected state hides export controls.
• Add realm selector/feedback when tenants have multiple QBO connections, reusing context shape (realmId, realmDisplayValue) used by Xero.
• Audit shared mapping actions (server/src/lib/actions/externalMappingActions.ts, server/src/lib/actions/integrations/qboActions.ts) for permissions, caching, and error messages suitable for the new UI.
• Update Playwright stories/tests under ee/server/src/__tests__/integration to cover QBO mapping CRUD using the generic components.

Phase 4 – Export Execution Integration

• Update accounting export UI flows (server/src/components/billing-dashboard/accounting/AccountingExportsTab.tsx) to highlight QBO-specific requirements (realm selection, mapping completeness) and reuse the preview API.
• Ensure CLI/automation scripts (scripts/trigger-accounting-export.ts) support quickbooks_online by default with updated implementation notes for engineering users.

---

Dependencies & Considerations

• Accounting export tables (accounting_export_batches, accounting_export_lines, accounting_export_errors) and services must remain stable; coordinate with ongoing work tracked in 2025-10-26-accounting-export-abstraction-plan.md.
• Multi-realm credential storage (QboClientService, tenant secrets) must support selecting the correct realm per batch; ensure mapping resolver requests include target_realm.
• Ensure no other workflows rely on QBO events before deleting schema/catalog definitions.
• Staging environments need valid QBO sandbox credentials to validate adapter deliver calls end-to-end.

Risks & Mitigations

• Risk: Removing workflows before manual exports are ready could block invoice delivery.
  Mitigation: Gate removal behind feature flag, complete adapter validation and smoke tests prior to rollout.
• Risk: Token refresh differences between workflows and adapter could introduce auth regressions.
  Mitigation: Expand QboClientService unit tests and add integration coverage for token refresh flows.
• Risk: Existing workflow tasks or attachments may remain orphaned.
  Mitigation: Run migration + cleanup script and notify workflow service owners.
• Risk: Finance teams rely on auto-sync cadence.
  Mitigation: Provide scheduling via Automation Hub that uses AccountingExportService API once workflows are gone.

Open Questions

• Do any external automations (Zapier, bespoke scripts) invoke the removed workflow actions? Need inventory before deletion.
• Should we preserve parts of the human-in-the-loop conflict detection (duplicate customers) within the mapping resolver or provide a separate review queue?
• What SLA/timing expectations exist for exports now that they become manual/automation-driven rather than event triggered?
• Are additional mapping entities (classes/departments, locations) required before phasing out the workflows?