lorentz dd01e9a892 docs(12-05): complete plan — live verification approved

Developer reviewed the SC#1-SC#4 verdict block and the auto-match sample
and responded "approved" — all four success criteria pass, auto-matches
are correct, no threshold/mapping changes needed. Marks PAX8-06, PAX8-10,
PAX8-11 complete in REQUIREMENTS.md.

2026-07-11 07:03:24 -04:00

3.7 KiB

Raw Blame History

Requirements: PAX8 Integration (v2.0)

Defined: 2026-07-10 Core Value: Managers can see PAX8 subscription costs and seat counts alongside existing Autotask company data in Pulse, without manually cross-referencing PAX8's own portal. Source: .planning/seeds/SEED-002-pax8-integration.md (scoped via /gsd-explore on 2026-07-10)

v2.0 Requirements

Requirements for this milestone. Each maps to a roadmap phase.

PAX8 — Client & Auth

PAX8-01: Pulse authenticates to the PAX8 REST API (api.pax8.com/v1) via OAuth2 client-credentials, using the developer-provisioned client ID/secret
PAX8-02: isPax8Configured() helper reports whether PAX8 credentials are present, following the existing is<Name>Configured() factory pattern (lib/services/pax8-factory.ts)

PAX8 — Data Sync

PAX8-03: Pulse syncs PAX8 companies into Postgres
PAX8-04: Pulse syncs PAX8 subscriptions (product, seat count, billing term) into Postgres
PAX8-05: Pulse syncs PAX8 product catalog (SKUs, categories) into Postgres, so subscriptions are human-readable
PAX8-06: Pulse syncs PAX8 orders/invoices (historical line items) into Postgres, enabling cost reconciliation over time, not just current-state seats
PAX8-07: Sync runs on a daily schedule via the existing sync-scheduler.ts cron pattern
PAX8-08: All PAX8 sync operations are read-only — no writes back to the PAX8 API (no seat adjustments, no order placement)
PAX8-09: PAX8 integration can be toggled on/off via /admin/integrations, consistent with other integrations (integration_settings table)

PAX8 — Company Matching

PAX8-10: PAX8 companies are automatically matched to existing Autotask companies by fuzzy name similarity at sync time
PAX8-11: Unmatched or ambiguous company matches are flagged rather than silently guessed
PAX8-12: An admin can view flagged/ambiguous company matches and manually resolve them to the correct Autotask company

PAX8 — UI Surface

PAX8-13: A new /pax8 page lists PAX8 companies with their subscriptions and a cost breakdown
PAX8-14: The /pax8 page surfaces flagged/ambiguous company matches (PAX8-11) for manual resolution

Future Requirements

Write access to PAX8 (seat adjustments, order placement) — no concrete need identified yet; revisit only if reconciliation surfaces one
Domain-based or external-ID-based company matching, if research resolves RESEARCH-pax8-company-identifiers in .planning/research/questions.md and finds a more stable join key than name
General Pulse data assistant (chatbot) consuming this data — separate future milestone, see .planning/seeds/SEED-003-general-pulse-data-assistant.md

Out of Scope

Write-back to PAX8 — this integration is read-only in v2.0, matching the pattern of most existing Pulse integrations (RMM, IT Glue, Veeam)
Chatbot/NL query layer — deliberately separated into SEED-003 so this milestone stays scoped to the data sync itself

Traceability

Requirement	Phase	Status
PAX8-01	Phase 10	Complete
PAX8-02	Phase 10	Complete
PAX8-03	Phase 11	Complete
PAX8-04	Phase 11	Complete
PAX8-05	Phase 11	Complete
PAX8-08	Phase 11	Complete
PAX8-06	Phase 12	Complete
PAX8-10	Phase 12	Complete
PAX8-11	Phase 12	Complete
PAX8-07	Phase 13	Pending
PAX8-09	Phase 13	Pending
PAX8-12	Phase 14	Pending
PAX8-13	Phase 14	Pending
PAX8-14	Phase 14	Pending

Coverage: 14/14 v2.0 requirements mapped ✓

Requirements defined: 2026-07-10

3.7 KiB Raw Blame History