> ## 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.

# Onboarding & Offboarding — Integration

> 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…

**Version:** 1.0.0\
**Last Updated:** 2026-03-20\
**Spec:** [HR-03 Onboarding & Offboarding](../../../specs/hr/specs/HR-03-onboarding-offboarding.md)\
**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:**

```typescript theme={null}
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:**

```typescript theme={null}
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:**

```typescript theme={null}
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:**

```typescript theme={null}
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`

```sql theme={null}
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`

```sql theme={null}
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

* [HR-03 Spec](../../../specs/hr/specs/HR-03-onboarding-offboarding.md)
* [EVENT\_CONTRACTS.md](./EVENT_CONTRACTS.md)
* [CROSS\_CORE\_INTEGRATIONS.md](./CROSS_CORE_INTEGRATIONS.md)