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

# Employee Engagement — Integration

> Version: 1.0.0 Last Updated: 2026-03-20 Spec: HR-17 Employee Engagement Constitution Reference: Section 1.2 (Core Independence), Section 1.3 (Integration Patte…

**Version:** 1.0.0\
**Last Updated:** 2026-03-20\
**Spec:** [HR-17 Employee Engagement](../../../specs/hr/specs/HR-17-employee-engagement.md)\
**Constitution Reference:** Section 1.2 (Core Independence), Section 1.3 (Integration Patterns)

***

## Overview

HR-17 manages employee engagement surveys and exit interviews. It publishes events for survey completion and exit interview completion, and integrates with HR-03 (Offboarding) for exit interview workflows.

***

## Integration Points

### Platform Foundation (PF) Dependencies

**Required PF Features:**

* **PF-08 (Forms)**: Survey forms, exit interview forms
  * **Integration Type:** Platform Integration Layer
  * **Documentation:** See [PLATFORM\_INTEGRATION\_LAYERS.md](./PLATFORM_INTEGRATION_LAYERS.md#pf-08-forms-integration-layer)
  * **Usage:** Survey forms and exit interview forms use `@/platform/forms` for form embedding and submission handling
* **PF-10 (Notifications)**: Survey reminders, completion notifications
  * **Integration Type:** Platform Integration Layer
  * **Documentation:** See [PLATFORM\_INTEGRATION\_LAYERS.md](./PLATFORM_INTEGRATION_LAYERS.md#pf-10-notifications-system)
  * **Usage:** Survey reminders and completion notifications via `@/platform/notifications`

### Consumer Core Dependencies (Downstream)

**Internal HR Features:**

* **HR-01 (Employee Directory)**: Employee context
* **HR-03 (Offboarding)**: Exit interview integration

***

## Event Contracts

### Event: `hr_survey_completed`

**Publisher:** HR (HR-17)\
**Subscribers:** PF-10 (Notifications)\
**Status:** 📝 Planned

**Purpose:** Notify managers of survey completion for tracking participation

**Payload Schema:**

```typescript theme={null}
interface HrSurveyCompletedPayload {
  event_type: 'hr_survey_completed';
  survey_id: uuid;
  response_id: uuid;
  employee_id: uuid | null; // null if anonymous
  completion_percentage: number;
  organization_id: uuid;
  timestamp: timestamptz;
}
```

**Reference:** See [EVENT\_CONTRACTS.md](./EVENT_CONTRACTS.md#hr-17-employee-engagement-events) for complete event schemas.

### Event: `hr_exit_interview_completed`

**Publisher:** HR (HR-17)\
**Subscribers:** HR-03 (Offboarding)\
**Status:** 📝 Planned

**Purpose:** Update offboarding workflow when exit interview completed

**Payload Schema:**

```typescript theme={null}
interface HrExitInterviewCompletedPayload {
  event_type: 'hr_exit_interview_completed';
  exit_interview_id: uuid;
  employee_id: uuid;
  offboarding_instance_id: uuid;
  reason_for_leaving: string;
  would_recommend: boolean;
  organization_id: uuid;
  timestamp: timestamptz;
}
```

**Reference:** See [EVENT\_CONTRACTS.md](./EVENT_CONTRACTS.md#hr-17-employee-engagement-events) for complete event schemas.

### Events Consumed

#### `hr_employee_terminated`

**Publisher:** HR-03 (Offboarding)\
**Subscriber:** HR-17 (Employee Engagement)\
**Status:** 📝 Planned

**Purpose:** Automatically trigger exit interview when employee terminated

**Integration:** See [CROSS\_CORE\_INTEGRATIONS.md](./CROSS_CORE_INTEGRATIONS.md) for integration details

***

## Platform Integration Layer Usage

**Consumes:**

* **PF-08 (Forms)**: Survey forms, exit interview forms via `@/platform/forms`
* **PF-10 (Notifications)**: Survey reminders, completion notifications via `@/platform/notifications`

***

## Security Considerations

### Multi-Tenancy

* ✅ **RLS Enforcement**: All `hr_surveys` and `hr_exit_interviews` tables filtered by `organization_id` via RLS policies

### Role-Based Access Control

* ✅ **HR Admin**: Full access to all surveys and exit interviews
* ✅ **Manager**: View survey results for own team (if permitted)
* ✅ **Staff**: Complete own surveys and exit interviews only

### Data Protection

* ✅ **PII Handling**: Survey and exit interview responses may contain sensitive employee information; access controlled via RLS
* ✅ **Anonymity**: Anonymous surveys do not include `employee_id` in responses
* ✅ **Audit Trail**: All survey and exit interview changes logged via PF-04

***

## Testing Requirements

* [ ] Event payload structure validation
* [ ] Event fires on trigger condition (survey completion, exit interview completion)
* [ ] Correct `organization_id` included in all events
* [ ] Subscribers handle events correctly (PF-10, HR-03)
* [ ] Anonymous survey handling works correctly (no employee\_id)
* [ ] RLS policies enforce org isolation on survey and exit interview queries

***

## References

* [HR-17 Spec](../../../specs/hr/specs/HR-17-employee-engagement.md)
* [EVENT\_CONTRACTS.md](./EVENT_CONTRACTS.md)
* [CROSS\_CORE\_INTEGRATIONS.md](./CROSS_CORE_INTEGRATIONS.md)