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

# HR-IT Onboarding Integration

> Documents the integration between HR employee onboarding (HR-UX-01) and IT provisioning (IT-08).

**Version:** 1.0\
**Created:** 2026-01-05\
**Last Updated:** 2026-01-05\
**Status:** Active\
**Spec:** HR-UX-01 Employee Onboarding Wizard

## Overview

Documents the integration between HR employee onboarding (HR-UX-01) and IT provisioning (IT-08).

## Integration Flow

```
┌──────────────────────────┐
│  HR Onboarding Wizard    │
│  (Step 5: System Access) │
└──────────┬───────────────┘
           │ Employee selects:
           │ - Email account
           │ - Network access
           │ - Applications
           │ - Hardware needs
           ▼
┌──────────────────────────┐
│  Wizard Completion       │
│  (OnboardingWizardPage)  │
└──────────┬───────────────┘
           │ 1. Creates employee record
           │ 2. If access requested →
           ▼
┌──────────────────────────┐
│  useITOnboardingIntegration │
│  createITOnboarding()    │
└──────────┬───────────────┘
           │ Creates it_onboarding_instances row
           ▼
┌──────────────────────────┐
│  IT Module Dashboard     │
│  (/it/onboarding)        │
└──────────────────────────┘
```

## Data Flow

### 1. HR Onboarding Wizard (Step 5: System Access)

Employee/HR selects system access requirements:

| Field                    | Type      | Description                          |
| ------------------------ | --------- | ------------------------------------ |
| `emailRequested`         | boolean   | Request new email account            |
| `networkAccessRequested` | boolean   | Request network/VPN access           |
| `applicationAccessIds`   | string\[] | Application access requests          |
| `hardwareRequests`       | string\[] | Hardware needs (laptop, phone, etc.) |

### 2. Wizard Completion

When the onboarding wizard is completed:

```typescript theme={null}
// In OnboardingWizardPage.tsx handleComplete()
if (data.emailRequested || data.networkAccessRequested || 
    (data.hardwareRequests as string[])?.length > 0) {
  await createITOnboarding.mutateAsync({
    employeeId: employee.id,
    targetDate: data.hire_date || today,
    systemAccessRequests: {
      emailRequested: Boolean(data.emailRequested),
      networkAccessRequested: Boolean(data.networkAccessRequested),
      applicationAccessIds: data.applicationAccessIds || [],
    },
    hardwareRequests: data.hardwareRequests || [],
  });
}
```

### 3. IT Onboarding Instance Created

The hook creates a new row in `it_onboarding_instances`:

| Column          | Value                   |
| --------------- | ----------------------- |
| `employee_id`   | Link to new employee    |
| `workflow_type` | `'onboarding'`          |
| `status`        | `'pending'`             |
| `priority`      | `'normal'`              |
| `target_date`   | Employee hire date      |
| `notes`         | Access requests summary |

## Event Contract

| Event                                         | Publisher | Subscriber | Trigger                                          |
| --------------------------------------------- | --------- | ---------- | ------------------------------------------------ |
| `employee_onboarding_system_access_requested` | HR-UX-01  | IT-08      | SystemAccessStep completion with access requests |

## Integration Points

### HR Side (Publisher)

* **Hook:** `src/cores/hr/hooks/useITOnboardingIntegration.ts`
* **Page:** `src/cores/hr/pages/OnboardingWizardPage.tsx`
* **Step:** `src/cores/hr/components/wizards/steps/SystemAccessStep.tsx`

### IT Side (Subscriber)

* **Table:** `it_onboarding_instances`
* **Dashboard:** `/it/onboarding`
* **Hook:** `useITOnboardingInstances` (existing)

## Security Considerations

### Access Controls

1. **RLS Policies:** IT onboarding instances protected by organization-level RLS
2. **Permission Check:** Only users with `hr.employees.create` can trigger IT onboarding
3. **Audit Trail:** All IT instances include `created_by` for accountability
4. **IT Staff Access:** IT technicians can view via `it.onboarding.view` permission

### Data Classification

5. **PII/PHI Linkage:** IT onboarding instances link to employee records containing PII/PHI:
   * SSN (from PersonalInfoStep)
   * Date of Birth (from PersonalInfoStep)
   * Home Address (from PersonalInfoStep)
   * Emergency Contact Information

### Data Protection

6. **Encryption at Rest:** All employee data encrypted in database (AES-256)
7. **Encryption in Transit:** All API calls use TLS 1.2+
8. **PHI/PII Restrictions:**
   * System access `notes` field MUST NOT include SSN, DOB, full addresses, or other sensitive identifiers
   * Only reference employee by ID, not by sensitive data
   * Never log PII/PHI in error messages or console output

### Audit & Logging

9. **Logged Actions:** IT instance creation, status updates, access attempts, deletion
10. **Retention Period:** Audit logs retained per organization data retention policy (default: 7 years)
11. **No PII in Logs:** Error messages sanitized to prevent PII exposure

## Future Enhancements

1. **Real-time notifications:** Notify IT team when new instance created
2. **Application catalog:** Integrate with IT application inventory
3. **Hardware inventory:** Link to FM asset management
4. **Auto-assign technician:** Route based on department/location