Overview
This document defines the integration contract between the HR (Human Resources) core and the FW (Forms & Workflow) core. HR uses FW for dynamic forms, approval workflows, event-driven automations, and business rules across multiple HR features. Related Specifications:- HR-02: Credentialing & Compliance
- HR-03: Onboarding & Offboarding
- HR-06: PTO & Leave Management
- HR-10: Performance Management & Reviews
- HR-11: Benefits Administration
- HR-14: Employee Relations
- HR-15: Compensation Management
- FW-01/FW-05: Forms (single-page and multi-page)
- FW-03: Automation Engine (event triggers, actions)
- FW-15: Form Field Lookups (employee/department dropdowns)
- FW-16: Event-Based Workflow Triggers
- FW-34: Approval Workflows (multi-level with delegation)
- FW-45: Decision Tables (routing rules)
Integration Pattern
Primary Pattern: Pattern 1 — Platform Integration Layer Secondary Pattern: Pattern 2 — Event-Based Integration HR accesses FW capabilities through:@/platform/forms— form rendering and submission@/platform/approvals— approval chain submission and inbox@/platform/events— publishing HR events for FW automation triggers@/platform/data-lookup— HR data as form field lookup sources@/platform/calendar— business day calculations for SLA deadlines
Event Contracts (HR → FW)
Events published by HR that trigger FW automations and workflows.HR-03: Employee Lifecycle Events
Event: hr_employee_hired
Event: hr_employee_hired
Channel: hr_events
Publisher: HR (HR-03 Onboarding)
Subscribers: FW-03 (onboarding workflow trigger), PF-10 (notification)
Status: ✅ Implemented (registered in KnownEventName)
Purpose
Triggers the employee onboarding workflow when a new hire record is created.Trigger Conditions
- Trigger: New employee record created with
status = 'active'or onboarding instance started
Payload Schema
Consumer Actions
Testing Requirements
- Event fires when new employee created
- Payload includes
organization_id,employee_id,department_id - No PII (name, SSN, DOB) in payload
- Onboarding workflow triggered within FW
Event: hr_employee_terminated
Event: hr_employee_terminated
Channel: hr_events
Publisher: HR (HR-03 Offboarding)
Subscribers: FW-03 (offboarding workflow trigger), PF-10 (notification)
Status: ✅ Implemented (registered in KnownEventName)
Purpose
Triggers the employee offboarding workflow when an employee is terminated or resigns.Payload Schema
Consumer Actions
HR-02: Credential Management Events
Event: hr_credential_expired
Event: hr_credential_expired
Channel: hr_events
Publisher: HR (HR-02 Credentialing)
Subscribers: FW-03 (renewal reminder automation)
Status: ✅ Implemented (registered in KnownEventName)
Purpose
Triggers renewal reminder workflow when an employee credential expires or approaches expiry.Payload Schema
Consumer Actions
Event: hr_credential_verified
Event: hr_credential_verified
Channel: hr_events
Publisher: HR (HR-02 Credentialing)
Subscribers: FW-03 (compliance status update)
Status: ✅ Implemented (registered in KnownEventName)
Purpose
Updates compliance tracking when a credential is verified or renewed.Payload Schema
HR-06: Leave Management Events
Event: hr_leave_request_submitted
Event: hr_leave_request_submitted
Channel: hr_events
Publisher: HR (HR-06 PTO & Leave Management)
Subscribers: FW-34 (approval workflow)
Status: ✅ Implemented (registered in KnownEventName)
Purpose
Triggers the leave request approval workflow when an employee submits a leave request.Payload Schema
Consumer Actions
HR-10: Performance Management Events
Event: hr_performance_review_due
Event: hr_performance_review_due
Channel: hr_events
Publisher: HR (HR-10 Performance Management)
Subscribers: FW-03 (review cycle workflow)
Status: 📝 Planned (not yet in KnownEventName)
Purpose
Triggers the performance review cycle workflow when reviews are due for employees.Payload Schema
Event: hr_pip_initiated
Event: hr_pip_initiated
Channel: hr_events
Publisher: HR (HR-10 Performance Management)
Subscribers: FW-03 (PIP tracking workflow)
Status: 📝 Planned (not yet in KnownEventName; related hr_pip_terminated is registered)
Purpose
Triggers PIP tracking workflow with milestone reminders and escalation deadlines.Payload Schema
HR-11: Benefits Events
Event: hr_benefits_enrollment_approved
Event: hr_benefits_enrollment_approved
Channel: hr_events
Publisher: HR (HR-11 Benefits Administration)
Subscribers: FW-03 (enrollment processing automation)
Status: ✅ Implemented (registered in KnownEventName)
Purpose
Triggers post-approval processing when a benefits enrollment is approved.Payload Schema
HR-14: Employee Relations Events
Event: hr_disciplinary_action_termination
Event: hr_disciplinary_action_termination
Channel: hr_events
Publisher: HR (HR-14 Employee Relations)
Subscribers: FW-03 (termination workflow), HR-03 (offboarding trigger)
Status: ✅ Implemented (registered in KnownEventName)
Purpose
Triggers termination workflow when a disciplinary action results in termination.Payload Schema
Event: hr_incident_reported
Event: hr_incident_reported
Channel: hr_events
Publisher: HR (HR-14 Employee Relations)
Subscribers: FW-03 (investigation workflow)
Status: ✅ Implemented (registered in KnownEventName)
Purpose
Triggers investigation workflow when an employee incident is reported.Payload Schema
Approval Chain Configurations
Leave Request Approval
Chain ID:hr-leave-request-approval
Entity Type: hr_leave_requests
Based On: HR-06
Decision Table for Routing:
Credential Renewal Approval
Chain ID:hr-credential-renewal-approval
Entity Type: hr_credentials
Based On: HR-02
Performance Review Approval
Chain ID:hr-performance-review-approval
Entity Type: hr_performance_reviews
Based On: HR-10
Compensation Change Approval
Chain ID:hr-compensation-change-approval
Entity Type: hr_compensation_changes
Based On: HR-15
Decision Table for Routing:
Form Templates
HR uses these FW form templates (specs inspecs/fw/templates/):
Planned Form Templates (Not Yet Specced)
Workflow Templates
Planned Workflow Templates (From Recommended Templates)
Form Field Lookups
HR exposes these data sources for FW form field lookups (FW-15):Platform Layer Usage
Hooks HR Components Import
Testing Requirements
Unit Tests
- HR event payloads match documented schemas
- Leave request decision table returns correct approval chain
- Compensation decision table returns correct approval levels
- No PII/PHI in event payloads
Integration Tests
-
hr_employee_hiredevent triggers onboarding workflow in FW -
hr_leave_request_submittedevent routes to correct approval chain -
hr_credential_expiredevent triggers reminder automation - Approval request status updates propagate back to HR entity
- Form field lookups return correct HR data
E2E Tests
- Complete leave request flow: form submission → approval → balance update
- Complete onboarding flow: hire → workflow → parallel tasks → completion
- Credential expiry → reminder → renewal → verification flow
RLS Tests
- HR events filtered by
organization_id - Approval requests scoped to submitter’s organization
- Form submissions isolated per tenant
Implementation Status
Related Documentation
- FW Cross-Core Integration Guide — Shared patterns
- Event Contracts — HR event registry
- Cross-Core Integration Matrix — Platform-wide matrix
- Recommended Workflow Templates — HR templates (8)
- FW-28 HR/FA Template Plan — Implementation roadmap