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

# Credentialing & Compliance — Integration

> Version: 1.0.0 Last Updated: 2026-03-20 Spec: HR-02 Credentialing & Compliance Constitution Reference: Section 1.2 (Core Independence), Section 1.3 (Integratio…

**Version:** 1.0.0\
**Last Updated:** 2026-03-20\
**Spec:** [HR-02 Credentialing & Compliance](../../../specs/hr/specs/HR-02-credentialing-compliance.md)\
**Constitution Reference:** Section 1.2 (Core Independence), Section 1.3 (Integration Patterns)

***

## Overview

HR-02 manages employee credentials, certifications, and compliance tracking. It publishes events for credential expiration and verification, and integrates with PF-10 (Notifications), PF-11 (Document Management), and FW (Forms & Workflow) for renewal workflows.

***

## Integration Points

### Platform Foundation (PF) Dependencies

**Required PF Features:**

* **PF-10 (Notifications)**: Send expiration alerts (90/60/30/14/7 days), verification status notifications
* **PF-11 (Document Management)**: Store credential PDFs, manage versions, secure access
* **PF-04 (Audit Logging)**: Log credential uploads, verifications, expirations for compliance
* **FW (Forms & Workflow)**: Credential renewal workflows (Enhancement 1)

**Integration Type:** Direct dependency (PF features are complete), Platform Integration Layer for FW

### Consumer Core Dependencies (Downstream)

**Internal HR Features:**

* **HR-01 (Employee Directory)**: Links credentials to employees, displays compliance status on profile
* **HR-03 (Onboarding)**: New hire checklist includes credential uploads
* **HR-04 (Scheduling)**: Blocks scheduling for employees with expired credentials (via event subscription)
* **HR-05 (Time Tracking)**: Blocks clock-in for employees with expired credentials (via event subscription)
* **HR-07 (Payroll)**: Compliance report for payroll eligibility

**External Cores:**

* **RH (Recovery Housing)**: Clinical staff credential verification for resident care (future)
* **GR (Governance)**: Training completion tracking (future)

***

## Event Contracts

### Event: `hr_credential_expired` (canonical)

**Publisher:** HR (HR-02)\
**Subscribers:** HR-04 (Scheduling), HR-05 (Time Tracking)\
**Status:** 📝 Planned (Q2 2026)

**Purpose:** Block scheduling and time tracking for employees with expired credentials

**Payload Schema:**

```typescript theme={null}
interface HrCredentialExpiredPayload {
  event_type: 'hr_credential_expired';
  employee_id: uuid;
  credential_id: uuid;
  credential_type_id: uuid;
  expiration_date: date;
  organization_id: uuid;
  timestamp: timestamptz;
}
```

**Note:** Event name follows canonical `{core}_{entity}_{action}` format. Legacy alias `credential_expired` may be deprecated in favor of `hr_credential_expired`.

### Event: `hr_credential_verified`

**Publisher:** HR (HR-02)\
**Subscribers:** HR-04 (Scheduling)\
**Status:** 📝 Planned (Q2 2026)

**Purpose:** Enable scheduling once credentials are verified

**Payload Schema:**

```typescript theme={null}
interface HrCredentialVerifiedPayload {
  event_type: 'hr_credential_verified';
  employee_id: uuid;
  credential_id: uuid;
  verification_status: 'verified' | 'rejected';
  verified_by: uuid;
  verified_at: timestamptz;
  organization_id: uuid;
  timestamp: timestamptz;
}
```

### Event: `hr_credential_renewal_workflow_started` (Enhancement 1)

**Publisher:** HR (HR-02)\
**Subscribers:** FW (Forms & Workflow)\
**Status:** 📝 Planned (Enhancement 1)

**Purpose:** Trigger renewal workflow 60 days before credential expiration

**Payload Schema:**

```typescript theme={null}
interface HrCredentialRenewalWorkflowStartedPayload {
  event_type: 'hr_credential_renewal_workflow_started';
  credential_id: uuid;
  employee_id: uuid;
  credential_type: string;
  expiration_date: date;
  days_until_expiration: number;
  organization_id: uuid;
  timestamp: timestamptz;
}
```

### Event: `hr_credential_renewed` (Enhancement 1)

**Publisher:** FW (Forms & Workflow)\
**Subscribers:** HR-02\
**Status:** 📝 Planned (Enhancement 1)

**Purpose:** Update credential expiration date after renewal workflow completes

**Payload Schema:**

```typescript theme={null}
interface HrCredentialRenewedPayload {
  event_type: 'hr_credential_renewed';
  credential_id: uuid;
  employee_id: uuid;
  new_expiration_date: date;
  renewal_workflow_id: uuid;
  organization_id: uuid;
  timestamp: timestamptz;
}
```

***

## Platform Integration Layer Usage

**Consumes:**

* **PF-10 (Notifications)**:
  * Expiration alerts via `send_notification()` function
  * Notification types: `credential_expiring`, `credential_expired`, `credential_verified`
  * Channels: in\_app, email (future)
* **PF-11 (Document Management)**:
  * Credential PDFs stored in `pf_documents` bucket
  * Category: `credential`
  * Access controlled via document permissions
* **PF-12 (Reports)**:
  * Compliance reports (expiration forecasts, audit reports)
  * Pre-built templates for credential compliance
* **FW (Forms & Workflow)**:
  * Credential renewal workflows via `@/platform/forms`
  * Renewal form templates and approval gates
  * Workflow triggers based on credential expiration dates

***

## Integration Examples

### Example 1: Send Expiration Alert via PF-10

```sql theme={null}
-- In credential expiration check function
SELECT send_notification(
  _user_id := employee.profile_id,
  _title := 'Credential Expiring Soon',
  _body := credential_type.name || ' expires on ' || credential.expiration_date,
  _type := 'credential_expiring',
  _channel := 'in_app',
  _data := jsonb_build_object(
    'credential_id', credential.id,
    'expiration_date', credential.expiration_date,
    'days_until_expiration', days_until_expiration
  )
);
```

### Example 2: Store Credential Document via PF-11

```typescript theme={null}
// In credential upload handler
import { useDocumentUpload } from '@/platform/documents';

const { upload } = useDocumentUpload();

await upload({
  file: credentialFile,
  title: `${credentialType.name} - ${employee.full_name}`,
  category: 'credential',
  organization_id: currentOrg.id,
  site_id: employee.primary_site_id,
  metadata: {
    employee_id: employee.id,
    credential_type_id: credentialType.id,
    expiration_date: expirationDate
  }
});
```

***

## Security Considerations

### Multi-Tenancy

* ✅ **RLS Enforcement**: All `hr_credentials` tables filtered by `organization_id` via RLS policies
* ✅ **Document Access**: Credential PDFs access-controlled via PF-11 document permissions

### Role-Based Access Control

* ✅ **HR Admin**: Full access to all credentials (CRUD)
* ✅ **Manager**: View credentials for direct reports
* ✅ **Staff**: View own credentials only

### Data Protection

* ✅ **PII Handling**: Credential documents may contain PII; stored securely in PF-11
* ✅ **Audit Trail**: All credential uploads, verifications, expirations logged via PF-04

***

## Testing Requirements

* [ ] Event payload structure validation
* [ ] Event fires on trigger condition (credential expiration, verification)
* [ ] Correct `organization_id` included in all events
* [ ] Subscribers handle events correctly (HR-04, HR-05, FW)
* [ ] PF-10 notifications sent at correct expiration thresholds
* [ ] PF-11 document upload and access control works correctly
* [ ] RLS policies enforce org isolation on credential queries

***

## References

* [HR-02 Spec](../../../specs/hr/specs/HR-02-credentialing-compliance.md)
* [EVENT\_CONTRACTS.md](./EVENT_CONTRACTS.md)
* [CROSS\_CORE\_INTEGRATIONS.md](./CROSS_CORE_INTEGRATIONS.md)