Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

Version: 1.0.0
Last Updated: 2026-03-20
Spec: HR-03 Onboarding & Offboarding
Constitution Reference: Section 1.2 (Core Independence), Section 1.3 (Integration Patterns)

Overview

HR-03 manages employee onboarding and offboarding workflows. It publishes events to trigger IT-08 (IT Onboarding/Offboarding) workflows for IT provisioning and access revocation.

Integration Points

Platform Foundation (PF) Dependencies

Required PF Features:
  • PF-10 (Notifications): Onboarding task reminders, offboarding completion alerts
  • PF-11 (Document Management): Store onboarding documents, I-9 forms, agreements
  • PF-04 (Audit Logging): Track onboarding/offboarding progress and completion
  • FW (Forms & Workflow): Onboarding/offboarding workflow templates
Integration Type: Direct dependency (PF features are complete), Platform Integration Layer for FW

Consumer Core Dependencies (Downstream)

Internal HR Features:
  • HR-01 (Employee Directory): Creates hr_employees record during onboarding
  • HR-02 (Credentialing): Onboarding checklist includes credential uploads
External Cores:
  • IT-08 (IT Onboarding/Offboarding): IT provisioning and access revocation triggered via events

Event Contracts

Event: hr_onboarding_started

Publisher: HR (HR-03)
Subscribers: IT-08 (IT Onboarding/Offboarding)
Status: 📝 Planned
Purpose: Create IT provisioning instance when onboarding starts Trigger: hr_onboarding_instances INSERT Payload Schema:
interface HrOnboardingStartedPayload {
  event_type: 'hr_onboarding_started';
  employee_id: uuid;
  onboarding_instance_id: uuid;
  template_id: uuid;
  start_date: date;
  is_clinical: boolean;
  organization_id: uuid;
  timestamp: timestamptz;
}

Event: hr_onboarding_task_created

Publisher: HR (HR-03)
Subscribers: IT-08 (IT Onboarding/Offboarding)
Status: 📝 Planned
Purpose: Create IT task instance when onboarding task with category ‘it_setup’ is created Trigger: hr_onboarding_task_instances INSERT (category: ‘it_setup’) Payload Schema:
interface HrOnboardingTaskCreatedPayload {
  event_type: 'hr_onboarding_task_created';
  task_instance_id: uuid;
  onboarding_instance_id: uuid;
  employee_id: uuid;
  category: 'it_setup';
  title: string;
  due_date: date;
  organization_id: uuid;
  timestamp: timestamptz;
}

Event: hr_offboarding_started

Publisher: HR (HR-03)
Subscribers: IT-08 (IT Onboarding/Offboarding)
Status: 📝 Planned
Purpose: Create IT offboarding instance when offboarding starts Trigger: hr_offboarding_instances INSERT Payload Schema:
interface HrOffboardingStartedPayload {
  event_type: 'hr_offboarding_started';
  employee_id: uuid;
  offboarding_instance_id: uuid;
  termination_date: date;
  termination_type: 'voluntary' | 'involuntary' | 'retirement' | 'end_contract';
  organization_id: uuid;
  timestamp: timestamptz;
}

Event: hr_offboarding_task_created

Publisher: HR (HR-03)
Subscribers: IT-08 (IT Onboarding/Offboarding)
Status: 📝 Planned
Purpose: Create IT access revocation task when offboarding checklist item with category ‘access_revocation’ is created Trigger: hr_offboarding_checklist_items INSERT (category: ‘access_revocation’) Payload Schema:
interface HrOffboardingTaskCreatedPayload {
  event_type: 'hr_offboarding_task_created';
  checklist_item_id: uuid;
  offboarding_instance_id: uuid;
  employee_id: uuid;
  category: 'access_revocation';
  title: string;
  organization_id: uuid;
  timestamp: timestamptz;
}

Implementation (Database Triggers)

Trigger: hr_onboarding_started

CREATE OR REPLACE FUNCTION hr_publish_onboarding_started()
RETURNS TRIGGER AS $$
DECLARE
  v_organization_id uuid;
BEGIN
  -- Resolve and validate organization_id before publishing
  SELECT organization_id INTO v_organization_id
  FROM hr_employees
  WHERE id = NEW.employee_id;
  
  IF v_organization_id IS NULL THEN
    RAISE EXCEPTION 'Employee % not found or has no organization_id', NEW.employee_id;
  END IF;
  
  PERFORM pg_notify('domain_events', json_build_object(
    'event_type', 'hr_onboarding_started',
    'employee_id', NEW.employee_id,
    'onboarding_instance_id', NEW.id,
    'template_id', NEW.template_id,
    'start_date', NEW.start_date,
    'is_clinical', COALESCE((SELECT is_clinical FROM hr_onboarding_templates WHERE id = NEW.template_id), false),
    'organization_id', v_organization_id,
    'timestamp', now()
  )::text);
  RETURN NEW;
END;
$$ LANGUAGE plpgsql SECURITY DEFINER SET search_path = public;

CREATE TRIGGER trigger_hr_onboarding_started
AFTER INSERT ON hr_onboarding_instances
FOR EACH ROW
EXECUTE FUNCTION hr_publish_onboarding_started();

Trigger: hr_offboarding_started

CREATE OR REPLACE FUNCTION hr_publish_offboarding_started()
RETURNS TRIGGER AS $$
BEGIN
  PERFORM pg_notify('domain_events', json_build_object(
    'event_type', 'hr_offboarding_started',
    'employee_id', NEW.employee_id,
    'offboarding_instance_id', NEW.id,
    'termination_date', NEW.termination_date,
    'termination_type', NEW.termination_type,
    'organization_id', (SELECT organization_id FROM hr_employees WHERE id = NEW.employee_id),
    'timestamp', now()
  )::text);
  RETURN NEW;
END;
$$ LANGUAGE plpgsql SECURITY DEFINER SET search_path = public;

CREATE TRIGGER trigger_hr_offboarding_started
AFTER INSERT ON hr_offboarding_instances
FOR EACH ROW
EXECUTE FUNCTION hr_publish_offboarding_started();

Platform Integration Layer Usage

Consumes:
  • PF-10 (Notifications): Onboarding task reminders, offboarding completion alerts
  • PF-11 (Document Management): Store onboarding documents, I-9 forms, agreements
  • PF-04 (Audit Logging): Track onboarding/offboarding progress and completion
  • FW (Forms & Workflow): Onboarding/offboarding workflow templates

Security Considerations

Multi-Tenancy

  • RLS Enforcement: All hr_onboarding_* and hr_offboarding_* tables filtered by organization_id via RLS policies

Role-Based Access Control

  • HR Admin: Full access to all onboarding/offboarding instances
  • Manager: View onboarding/offboarding for direct reports
  • Staff: View own onboarding/offboarding only

Data Protection

  • PII Handling: Onboarding documents may contain PII; stored securely in PF-11
  • Audit Trail: All onboarding/offboarding progress logged via PF-04

Testing Requirements

  • Event payload structure validation
  • Event fires on trigger condition (onboarding/offboarding instance creation, task creation)
  • Correct organization_id included in all events
  • Subscribers handle events correctly (IT-08)
  • Database triggers execute correctly
  • RLS policies enforce org isolation on onboarding/offboarding queries

References