Certification
Data Entity
Description
Represents a formal certification held by a peer mentor, issued upon completing a course or qualification programme. Tracks certificate type, validity period, status, and links to the issuing course and the certified user. Supports digital certificate display, PDF generation, expiry notifications, and automatic deactivation of expired peer mentors from organisation listings.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Primary key — unique identifier for the certification record | PKrequiredunique |
user_id |
uuid |
Foreign key to the user (peer mentor) who holds this certification | required |
course_id |
uuid |
Foreign key to the course that generated this certification. Null for manually issued or legacy certificates imported from paper records. | - |
organization_id |
uuid |
Foreign key to the organisation that issued the certificate, enabling multi-tenant scoping and org-level certificate management | required |
certificate_type |
enum |
Classifies the type of certification. peer_mentor_basic is the core HLF digital certificate; course_completion covers generic completed courses; career_workshop covers the two-day group mentoring workshop (Blindeforbundet). | required |
status |
enum |
Lifecycle state of the certificate. Active certificates grant visible peer mentor status. Expired certificates trigger auto-removal from org listings. Revoked certificates are invalidated by an admin action. | required |
certificate_number |
string |
Human-readable unique certificate identifier used on the physical and digital certificate (e.g. HLF-2025-00342). Unique within the organisation. | required |
issued_at |
datetime |
Timestamp when the certificate was formally issued. Used as the start date for expiry calculations. | required |
expires_at |
datetime |
Expiry date of the certificate. Null for non-expiring certificates. When this date passes, the status scheduler sets status to 'expired' and triggers notification and auto-removal from org listing. | - |
issued_by_user_id |
uuid |
Foreign key to the user (coordinator or org admin) who manually issued or approved the certificate. Null when issued automatically upon course completion. | - |
pdf_url |
string |
URL to the generated PDF certificate stored in cloud object storage. Null until PDF has been generated. Used by the Certificate Screen for download and sharing. | - |
pdf_generated_at |
datetime |
Timestamp when the PDF was last generated. Used to determine if regeneration is needed (e.g. after user name change). | - |
revoked_at |
datetime |
Timestamp when the certificate was revoked. Null unless status is 'revoked'. | - |
revoked_by_user_id |
uuid |
Foreign key to the admin or coordinator who revoked the certificate. | - |
revocation_reason |
text |
Free-text reason provided when revoking a certificate. Required when status transitions to 'revoked'. | - |
expiry_reminder_sent_at |
datetime |
Timestamp when the expiry reminder notification was last dispatched. Prevents duplicate reminders from the certificate expiry scheduler. | - |
metadata |
json |
Flexible key-value store for organisation-specific certificate data: e.g. training hours, competency areas, workshop session IDs, or legacy import metadata. | - |
created_at |
datetime |
Record creation timestamp | required |
updated_at |
datetime |
Record last-modified timestamp, updated on any status or field change | required |
Database Indexes
idx_certifications_user_id
Columns: user_id
idx_certifications_course_id
Columns: course_id
idx_certifications_organization_id
Columns: organization_id
idx_certifications_status
Columns: status
idx_certifications_expires_at
Columns: expires_at
idx_certifications_user_type_org
Columns: user_id, certificate_type, organization_id
idx_certifications_certificate_number_org
Columns: certificate_number, organization_id
Validation Rules
expires_at_after_issued_at
error
Validation failed
valid_user_id
error
Validation failed
valid_course_id_if_provided
error
Validation failed
certificate_number_format
error
Validation failed
pdf_url_format
error
Validation failed
status_transition_guard
error
Validation failed
revocation_fields_consistency
error
Validation failed
Business Rules
unique_active_certificate_per_type
A user may hold at most one active certificate of each certificate_type within a given organisation. Issuing a new peer_mentor_basic certificate while one is already active must either renew (extend expiry) or replace (revoke old, create new) the existing record — never create a duplicate active record.
auto_expire_on_expiry_date
When the current date passes expires_at, the certificate status must be set to 'expired'. The certificate-expiry-scheduler runs nightly and updates status for all overdue active certificates. This triggers an automatic removal of the peer mentor from the organisation's active peer mentor listing.
expiry_notification_30_days_before
A push notification and/or email must be dispatched to the certificate holder 30 days before expires_at. The expiry_reminder_sent_at field is set to prevent duplicate notifications. The organisation coordinator is also notified.
pdf_required_before_share
A certificate PDF must be generated (pdf_url populated) before the user can download or share the certificate. The Certificate Screen triggers on-demand PDF generation via certificate-pdf-renderer if pdf_url is null.
revocation_requires_reason
Transitioning a certificate to 'revoked' status requires a non-empty revocation_reason and a valid revoked_by_user_id. Only coordinators and org admins may revoke certificates within their own organisation.
course_completion_auto_issue
When a course_enrollment reaches completed status and the course is configured to issue certificates, certificate-service automatically creates a certification record linked to the course_id. The issued_at is the enrollment completion timestamp.
org_scoped_certificate_number
certificate_number must be unique within the organisation (composite unique on certificate_number + organization_id). The certificate-service generates the number using a configurable org-specific format (e.g. HLF-YYYY-NNNNN).