Reporting Period
Data Entity
Description
Defines time-bounded windows within which an organization's activity data is aggregated for Bufdir grant reporting and internal statistics. Each period has a type (annual, quarterly, custom), a lifecycle status, and a submission deadline. Reporting periods are the primary axis along which Bufdir reports are generated, approved, and exported.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Primary key. Surrogate UUID generated on insert. | PKrequiredunique |
organization_id |
uuid |
Foreign key to the owning organization. Each reporting period belongs to exactly one organization (tenant isolation). | required |
name |
string |
Human-readable label for the period, e.g. '2024 Annual Bufdir Report' or 'Q1 2025'. Displayed in reporting-period-selector-widget dropdowns and report headers. | required |
period_type |
enum |
Granularity of the reporting window. Drives default date range suggestions in the UI. | required |
fiscal_year |
integer |
The calendar/fiscal year this period primarily belongs to (e.g. 2024). Used for grouping and filtering in admin dashboards and Bufdir export logic. | required |
start_date |
datetime |
Inclusive start of the period (stored as date, midnight UTC). Activities with a registered date >= start_date are included in this period's aggregation. | required |
end_date |
datetime |
Inclusive end of the period (stored as date, 23:59:59 UTC). Must be after start_date. Activities with a registered date <= end_date are included. | required |
status |
enum |
Lifecycle state of the period. Controls what operations are allowed (e.g. closed periods cannot receive new activity registrations counted toward them). | required |
is_bufdir_period |
boolean |
Whether this period is designated for official Bufdir grant reporting. Bufdir periods trigger additional validation rules and unlock the Bufdir export workflow. | required |
submission_deadline |
datetime |
The date by which the Bufdir report for this period must be submitted. Used by scenario-cron-scheduler to trigger deadline reminder notifications to org admins. | - |
submitted_at |
datetime |
Timestamp when the report for this period was officially submitted to Bufdir. Null until status transitions to 'submitted'. | - |
submitted_by_user_id |
uuid |
Foreign key to the user (Org Admin or Coordinator) who performed the final submission action. Stored for audit trail. | - |
activity_count_snapshot |
integer |
Denormalized count of activities included in this period at the time of closing. Written by report-data-aggregator when period transitions to 'closed'. Prevents expensive re-aggregation during export. | - |
notes |
text |
Free-text remarks entered by the Org Admin, e.g. explanations for missing data or late submission context. Visible in the admin portal only. | - |
created_by_user_id |
uuid |
Foreign key to the user who created this period record. Required for audit trail. | required |
created_at |
datetime |
Row creation timestamp (UTC). Set by the database on insert. | required |
updated_at |
datetime |
Last modification timestamp (UTC). Updated by trigger on any column change. | required |
Database Indexes
idx_reporting_periods_org_id
Columns: organization_id
idx_reporting_periods_org_fiscal_year
Columns: organization_id, fiscal_year
idx_reporting_periods_org_status
Columns: organization_id, status
idx_reporting_periods_date_range
Columns: organization_id, start_date, end_date
idx_reporting_periods_bufdir_active
Columns: organization_id, is_bufdir_period, status
idx_reporting_periods_deadline
Columns: submission_deadline, status
Validation Rules
end_date_after_start_date
error
Validation failed
fiscal_year_matches_date_range
warning
Validation failed
name_not_empty
error
Validation failed
submission_deadline_after_end_date
error
Validation failed
submitted_at_requires_submitted_status
error
Validation failed
activity_count_snapshot_non_negative
warning
Validation failed
Business Rules
no_overlapping_bufdir_periods
An organization cannot have two Bufdir periods (is_bufdir_period = true) whose date ranges overlap. Enforced to prevent double-counting of activities in official Bufdir grant submissions.
single_active_bufdir_period_per_org
At most one period with status='active' and is_bufdir_period=true may exist per organization at any time. Creating or activating a second one requires closing the first.
closed_period_immutable_dates
Once a period reaches status='closed', 'submitted', or 'archived', start_date and end_date cannot be changed. This protects the integrity of previously generated Bufdir reports that reference the period boundaries.
submitted_requires_closed
A period can only transition to status='submitted' from status='closed'. The close step triggers activity count snapshot by report-data-aggregator before submission is allowed.
delete_only_draft
Reporting periods can only be deleted when status='draft'. Periods in any other state have associated report data and must be archived instead.
deadline_notification_trigger
When submission_deadline is set or updated, the scenario-cron-scheduler must be notified to schedule deadline reminder notifications for org admins 7 days and 1 day before the deadline.
bufdir_export_locked_to_submitted_period
The Bufdir export workflow (bufdir-export-service) may only execute against periods in status='closed' or 'submitted'. Exporting from a draft or active period is blocked to prevent incomplete data exports.