Implement Dynamics portal REST adapter
epic-external-system-integration-configuration-core-services-task-007 — Implement the DynamicsAdapter for Microsoft Dynamics portal integration used by HLF. Handles Azure AD / OAuth2 authentication, Dynamics OData endpoint construction, batch operation support, field mapping to Dynamics entity schema, and error normalization. Must coordinate with HLF's existing Dynamics portal project to avoid overlap.
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 inside a Supabase Edge Function (Deno). The most complex aspect is the Azure AD PKCE flow — implement as a two-phase process: (1) authorization URL generation returned to the UI wizard for user redirect, (2) token exchange in a callback Edge Function endpoint. Store the resulting refresh token in the credential vault. For OData, use Deno fetch with explicit Accept: application/json and OData-Version: 4.0 headers.
Dynamics OData batch requests require careful multipart/mixed body construction — implement a DynamicsBatchBuilder helper class that accepts an array of operations and produces the correct boundary-delimited body. Key coordination risk: HLF has an existing 'min side' Dynamics portal project. Before finalising field mappings, confirm with HLF which Dynamics entities and fields are owned by which system. Enforce this in the adapter via a strict field allowlist — the adapter should throw if asked to write to a non-allowed field.
This prevents accidental overlap. For error handling, Dynamics OData errors are returned in a specific JSON envelope (error.code, error.message, error.innererror) — parse this structure in the error normalizer. 412 Precondition Failed means an ETag conflict; surface this as a retryable=false conflict error requiring manual resolution.
Testing Requirements
Unit tests (Deno test): Azure AD token acquisition and refresh flow (mocked), OData URL construction for all supported entity types, batch changeset serialization to multipart/mixed format, field mapping from internal certification model to Dynamics schema, error normalization for OData error response shapes. Integration tests: full Azure AD PKCE flow against test tenant, read certification records from Dynamics sandbox, write sync metadata, ETag concurrency conflict handling. Coordination test: verify adapter scope does not write to entities owned by HLF's 'min side' portal (use field allowlist assertion). Test coverage target: 90% on adapter business logic.
Record HTTP fixtures for unit tests to avoid live Azure dependencies in CI.
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.