Implement Cornerstone, Consio, and Bufdir adapters
epic-external-system-integration-configuration-core-services-task-008 — Implement the remaining three REST adapters: CornerstoneAdapter (LMS/HR system), ConsioAdapter (membership management), and BufdirAdapter (government reporting API). Each must conform to the uniform adapter interface with system-specific authentication, payload format, error handling, and capability declarations. Bufdir adapter must support the one-click reporting requirement from all organizations.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 2 - 518 tasks
Can start after Tier 1 completes
Handles integration between different epics or system components. Requires coordination across multiple development streams.
Implementation Notes
Implement all three adapters inside Supabase Edge Functions (Deno). Start with BufdirAdapter as it is the highest business value (all four organisations depend on it). BufdirAdapter implementation key points: read the bufdir_column_schema from the database to determine which columns to include in the report and their mapping — this makes the adapter configurable as Bufdir changes their schema. The one-click requirement means the adapter must internally aggregate all relevant activity records for the report period without user intervention — implement a ReportAggregator helper that queries activities, filters by period, and produces the report rows.
Write audit log BEFORE submission attempt so partial failures are captured. For ConsioAdapter: membership management APIs often have complex ID schemes — store the external Consio member ID in the contact record (as a metadata field) after first sync to enable subsequent updates. For CornerstoneAdapter: focus only on the capabilities HLF needs — check with the team whether this is read-only HR sync or bidirectional LMS data. Implementing all three in one task is ambitious at 18 hours — consider timebox per adapter: Bufdir 8h, Consio 5h, Cornerstone 5h.
If Bufdir runs over, descope Cornerstone to a follow-up task since it has lower priority than Bufdir.
Testing Requirements
Unit tests (Deno test) for all three adapters: authentication flow (mocked HTTP), payload serialization to each system's expected format, error normalization for system-specific error shapes, retry logic. BufdirAdapter specific tests: bufdir_column_schema mapping to report payload, audit log entry creation on success and failure, multi-organisation report isolation (verify org A credentials cannot submit for org B). ConsioAdapter tests: membership create vs update routing logic. CornerstoneAdapter tests: pagination handling across multiple pages.
Integration tests: BufdirAdapter end-to-end submission to Bufdir sandbox or mock server. Test coverage target: 85% per adapter. Use recorded HTTP fixtures in CI to avoid live external dependencies.
Each of the five external systems (Xledger, Dynamics, Cornerstone, Consio, Bufdir) has a different authentication flow, field schema, and error format. Forcing them into a uniform adapter interface may require compromises that result in leaky abstractions or make the adapter contract too complex to maintain.
Mitigation & Contingency
Mitigation: Design the IntegrationAdapter interface with a loose invoke() payload rather than a typed one, allowing each adapter to declare its own input/output schema. Use integration type metadata in the registry to document per-adapter quirks. Build Xledger first as the most documented API, then adapt the interface based on learnings.
Contingency: If the uniform interface cannot accommodate all five systems, split into two interface tiers: a simple polling/export adapter and a richer bidirectional adapter, with the registry declaring which tier each system implements.
Development and testing of the Cornerstone and Consio adapters depends on NHF providing sandbox API access. If credentials or documentation are delayed, these adapters cannot be validated, blocking the epic's acceptance criteria.
Mitigation & Contingency
Mitigation: Implement Xledger and Dynamics adapters first (better-documented, sandbox available). Create a mock adapter for Cornerstone/Consio using recorded API responses for CI testing. Proactively request sandbox access from NHF at project kickoff.
Contingency: Ship the epic with Cornerstone/Consio adapters in a 'stub' state (connectivity test returns a simulated success, invoke() is not production-wired) and gate the NHF integration behind a feature flag until real API access is obtained.
Real-world field mappings may include nested transformations, conditional logic, and data type coercions (e.g., Norwegian date formats, currency rounding rules) that the Field Mapping Resolver's initial design does not accommodate, requiring scope expansion mid-epic.
Mitigation & Contingency
Mitigation: Gather actual field mapping examples from Blindeforbundet (Xledger) and HLF (Dynamics) before designing the resolver. Identify the most complex transformation required and ensure the resolver design handles it. Limit Phase 1 to direct field renaming and format conversion only.
Contingency: If complex transformations are required, implement a simple expression evaluator (e.g., JSONata or a custom mini-DSL) as an extension point in the resolver, delivering basic mappings first and complex ones in a follow-up task.