Bufdir Export Audit Log
Data Entity
Description
An append-only audit record for each Bufdir government reporting export operation, tracking initiating user, target period, pipeline status (pending, complete, failed), and generated file reference. Distinct from export_run which covers internal accounting system exports; this entity covers the regulatory Bufdir reporting pipeline.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Immutable primary key generated at record creation time. Used as the export operation's canonical reference across all pipeline stages. | PKrequiredunique |
organization_id |
uuid |
Foreign key to the Organization entity. Scopes the audit record to a single multi-tenant partner organization (NHF, Blindeforbundet, HLF, etc.). Applied as an RLS predicate on all queries. | required |
triggered_by_user_id |
uuid |
Foreign key to the Supabase auth user who initiated the export. Must be a coordinator or org admin role. Captured at the moment the export is requested and never updated. | required |
report_period_id |
uuid |
Foreign key to the Report Period entity that defines the grant cycle date range included in this export. Provides traceable reference to the exact Bufdir reporting window submitted. | required |
status |
enum |
Current pipeline status of the export operation. Transitions are one-way: pending → complete or pending → failed. Only the bufdir-export-audit-service may write this field after initial creation. | required |
export_format |
enum |
Output format selected by the user at export time. Drives which file generator (Excel/CSV/PDF) is invoked by the orchestrator. | required |
scope_level |
enum |
Organizational scope at which the export was generated. Determines which hierarchy levels of activity data are included in aggregation. | required |
scope_id |
uuid |
The specific organizational unit ID for region or local scope exports. Null for national-level exports where all units under the organization are included. | - |
file_url |
string |
Supabase Storage path or signed URL reference to the generated export file. Populated only when status transitions to 'complete'. Null while pending or after failure. | - |
file_size_bytes |
integer |
Byte size of the generated export file. Set alongside file_url on successful completion. Used for administrative reporting and download UX. | - |
activity_count |
integer |
Number of distinct activity records included in this export after deduplication. Set when status transitions to complete. Provides a quick sanity check for coordinators reviewing export history. | - |
participant_count |
integer |
Number of unique participants (contacts) covered by activities in this export. Populated on completion. Key Bufdir metric for grant reporting accountability. | - |
bufdir_submission_reference |
string |
External reference ID returned by the Bufdir API on direct submission. Null for file-based exports or when the Bufdir API integration is not yet available. Supports future direct API submission tracking. | - |
error_message |
text |
Human-readable error description captured when the pipeline fails. Null for pending or completed exports. Supports coordinator troubleshooting and developer debugging without exposing raw stack traces. | - |
error_code |
string |
Machine-readable error classification code for programmatic error handling and monitoring. Examples: AGGREGATION_FAILED, STORAGE_UPLOAD_FAILED, MAPPING_INCOMPLETE. | - |
column_schema_version |
string |
Version identifier of the Bufdir column schema (from bufdir_column_schema) used at export time. Enables future audit verification that the correct format was applied for a given grant cycle. | - |
created_at |
datetime |
UTC timestamp when the export record was first created (export initiated). Immutable after creation. Used as the primary sort key for export history display. | required |
completed_at |
datetime |
UTC timestamp when the export pipeline reached a terminal state (complete or failed). Null while status is pending. Set by bufdir-export-audit-service on status transition. | - |
Database Indexes
idx_bufdir_export_audit_log_org_created
Columns: organization_id, created_at
idx_bufdir_export_audit_log_org_status
Columns: organization_id, status
idx_bufdir_export_audit_log_report_period
Columns: organization_id, report_period_id
idx_bufdir_export_audit_log_triggered_by
Columns: triggered_by_user_id
idx_bufdir_export_audit_log_created_at
Columns: created_at
Validation Rules
id_is_valid_uuid
error
Validation failed
organization_id_not_null
error
Validation failed
triggered_by_user_id_not_null
error
Validation failed
report_period_id_not_null
error
Validation failed
status_initial_value_is_pending
error
Validation failed
export_format_is_valid_enum
error
Validation failed
scope_level_is_valid_enum
error
Validation failed
scope_id_required_for_non_national
error
Validation failed
file_url_max_length
error
Validation failed
activity_count_non_negative
warning
Validation failed
file_size_bytes_non_negative
warning
Validation failed
completed_at_not_before_created_at
error
Validation failed
error_code_max_length
error
Validation failed
Business Rules
append_only_immutability
Audit records may never be deleted. Once created, the id, organization_id, triggered_by_user_id, report_period_id, export_format, scope_level, scope_id, and created_at fields are permanently immutable. This preserves an unbroken audit chain for Bufdir grant accountability.
status_forward_only_transition
Status may only advance from 'pending' to 'complete' or 'pending' to 'failed'. Transitions from 'complete' or 'failed' to any other state are rejected. This enforces a one-way pipeline model and prevents history falsification.
file_url_requires_complete_status
file_url and file_size_bytes may only be set when status is 'complete'. Setting these fields on a 'pending' or 'failed' record is rejected.
completed_at_set_on_terminal_status
completed_at must be populated when status transitions to 'complete' or 'failed', and must remain null while status is 'pending'. The timestamp is set by the service layer, not the client.
organization_scoped_access
All reads and writes are enforced by Supabase RLS policies that restrict access to records matching the authenticated session's organization_id. Cross-organization access is blocked at the database level.
coordinator_or_admin_required_to_create
Only users with coordinator or org_admin roles may initiate a Bufdir export and thereby create an audit record. Peer mentor role access is rejected before the record is written.
error_fields_require_failed_status
error_message and error_code may only be populated when status is 'failed'. Setting them on a 'complete' record is rejected to prevent misleading audit history.
report_period_must_belong_to_organization
The report_period_id must reference a Report Period entity whose organization_id matches this record's organization_id. Cross-organization period references are rejected.
CRUD Operations
Storage Configuration
Entity Relationships
A Bufdir export audit record references the target reporting period for traceability of which grant cycle was submitted
Bufdir export audit records are scoped to an organization for regulatory accountability