Bufdir Column Mapper
Component Detail
Description
Maps the app's internal activity data model to Bufdir's required column schema. Supports per-organisation configuration to handle format differences between NHF, Blindeforbundet, and HLF. Configuration is stored in the database and can be updated without a code deployment.
bufdir-column-mapper
Summaries
The Bufdir Column Mapper is a strategic capability that allows the platform to serve three distinct partner organisations — NHF, Blindeforbundet, and HLF — each with their own Bufdir column format requirements, from a single shared codebase. By storing per-organisation column configuration in the database and supporting schema updates without code deployments, it dramatically reduces the operational cost of adapting to Bufdir format changes. Compliance updates can be applied in minutes by a non-developer administrator rather than requiring a full development sprint and deployment cycle, reducing time-to-compliance and the associated regulatory risk. This configuration-driven approach also future-proofs the platform against Bufdir schema changes that would otherwise require emergency development work across all partner organisations simultaneously.
The Bufdir Column Mapper is a high-complexity backend component with one direct dependency on `bufdir-schema-config-repository`. Its most significant delivery risk is the per-organisation configuration capture phase — exact column mappings for all three organisations (NHF, Blindeforbundet, HLF) must be documented, validated, and loaded into the database before end-to-end export testing can begin. Schedule a dedicated requirements session with stakeholders from each organisation early in the delivery cycle. The `updateColumnSchema` and `previewMapping` interfaces imply admin tooling scope that may require additional frontend work not captured in the initial export feature estimate — raise this as a scope clarification item.
Allocate explicit regression testing effort for schema update scenarios to prevent mapping regressions after live configuration changes in production.
The Bufdir Column Mapper is a high-complexity backend service dependent on `bufdir-schema-config-repository` for per-organisation schema retrieval. It exposes five interfaces: `mapActivities(rows, orgId)` for bulk transformation of `ActivityRow` records, `getColumnSchema(orgId)` to retrieve the active mapping configuration, `updateColumnSchema(orgId, schema)` for admin-driven config updates without deployment, `validateMappedRow(row)` for post-mapping schema compliance checks, and `previewMapping(sampleRows, orgId)` for configuration testing. Define `BufdirColumnSchema` as a keyed mapping object (internalField → bufdirColumnName + formatTransformer + nullDefault). Cache `getColumnSchema` results with a short TTL (60 seconds recommended) to avoid per-row database reads during bulk mapping; the `updateColumnSchema` path must atomically invalidate this cache.
Store schema versions to support audit log correlation — re-downloading a past export should reproduce the exact mapping active at that export time. Flag this versioning requirement for scope discussion, as it meaningfully increases implementation complexity.
Responsibilities
- Map internal activity fields to Bufdir column names and formats
- Apply per-organisation column configuration overrides
- Validate mapped rows against Bufdir schema requirements
- Handle missing or null values with configurable defaults
Interfaces
mapActivities(List<ActivityRow> rows, String orgId)
getColumnSchema(String orgId)
updateColumnSchema(String orgId, BufdirColumnSchema schema)
validateMappedRow(MappedRow row)
previewMapping(List<ActivityRow> sampleRows, String orgId)
Relationships
Related Data Entities (2)
Data entities managed by this component
Used Integrations (1)
External integrations and APIs this component relies on