Assignment Threshold Config
Data Entity
Description
Stores organization-specific, versioned honorarium threshold configurations that define how many completed assignments trigger each payment tier for peer mentors within a reporting period. Supports the Norwegian peer mentor honorarium model (e.g., tier 1 at 3 assignments, tier 2 at 15 assignments) and is versioned to preserve historical accuracy for past reporting periods.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Primary key. Unique identifier for each configuration version record. | PKrequiredunique |
organization_id |
uuid |
Foreign key referencing the organization this threshold configuration belongs to. All threshold evaluations are scoped to this org. | required |
version |
integer |
Monotonically increasing version number scoped per organization. Incremented on every configuration update to enable historical lookups. Version 1 is the initial config. | required |
is_active |
boolean |
Indicates whether this is the currently active configuration for the organization. Only one record per organization may have is_active = true at any time. Enforced via partial unique index. | required |
reporting_period_type |
enum |
The type of reporting period over which assignment counts are accumulated and evaluated against thresholds. | required |
tiers |
json |
Ordered array of honorarium tier definitions. Each tier specifies a minimum completed assignment count that triggers that tier's honorarium amount. Example: [{"tier_label":"tier_1","min_assignments":3,"honorarium_amount":500,"currency":"NOK"},{"tier_label":"tier_2","min_assignments":15,"honorarium_amount":1200,"currency":"NOK"}]. Tiers must have strictly ascending min_assignments values. | required |
near_threshold_warning_distance |
integer |
Number of assignments below the next tier at which coordinators are warned that a peer mentor is approaching a threshold. Used by the Coordinator Threshold Overview Widget to highlight near-threshold mentors. Default 2. | - |
custom_period_start |
datetime |
Start date of the custom reporting period. Only applicable when reporting_period_type = 'custom'. NULL for standard period types. | - |
custom_period_end |
datetime |
End date of the custom reporting period. Only applicable when reporting_period_type = 'custom'. Must be after custom_period_start. | - |
created_by |
uuid |
User ID of the organization admin who created or last versioned this configuration record. | required |
notes |
text |
Optional free-text notes from the admin explaining the reason for this version of the config (e.g., 'Raised tier 2 threshold per board decision 2025-03'). | - |
activated_at |
datetime |
Timestamp when this configuration became active. NULL until the record is activated. Used for audit trails and for determining which config was active during a given reporting period. | - |
deactivated_at |
datetime |
Timestamp when this configuration was superseded by a newer version. NULL for the current active config. Enables point-in-time reconstruction of historical evaluations. | - |
created_at |
datetime |
Timestamp when this configuration record was created. | required |
updated_at |
datetime |
Timestamp of the last modification to this record. Updated automatically on any field change. | required |
Database Indexes
idx_assignment_threshold_config_org_active
Columns: organization_id
Partial unique index: WHERE is_active = true. Enforces that only one active configuration exists per organization.
idx_assignment_threshold_config_org_version
Columns: organization_id, version
Enforces uniqueness of version numbers within an organization and supports ordered version history lookups.
idx_assignment_threshold_config_org_created
Columns: organization_id, created_at
Supports chronological listing of all config versions per organization in the admin UI.
idx_assignment_threshold_config_activated_at
Columns: organization_id, activated_at
Supports point-in-time config lookups: find which config was active during a given historical reporting period.
Validation Rules
tiers_json_schema
error
Validation failed
version_monotonic_per_org
error
Validation failed
honorarium_amount_non_negative
error
Validation failed
near_threshold_warning_positive
error
Validation failed
organization_exists
error
Validation failed
currency_code_valid
warning
Validation failed
Business Rules
single_active_config_per_org
Only one assignment threshold configuration may be active (is_active = true) per organization at any given time. When a new config is activated, the previously active config must have its is_active set to false and its deactivated_at timestamp set atomically within the same transaction.
immutable_versioned_history
Configuration records are never mutated after activation. Any change to threshold tiers or period settings creates a new version record with version = max(existing_versions) + 1. This preserves audit trail accuracy for historical honorarium calculations.
ascending_tier_thresholds
The tiers JSON array must contain tier definitions with strictly ascending min_assignments values. No two tiers may share the same min_assignments value. The first tier must have min_assignments >= 1.
org_admin_scope_enforcement
Only users with Org Admin role for the target organization, or Global Admins, may create or deactivate threshold configurations. Peer Mentors and Coordinators have read-only access.
custom_period_requires_dates
When reporting_period_type is 'custom', both custom_period_start and custom_period_end must be provided and custom_period_end must be strictly after custom_period_start.
historical_config_preservation
Deactivated configurations must never be deleted. They are preserved indefinitely to allow retroactive honorarium recalculation and auditing. Threshold crossing events reference the config version that was active at evaluation time.