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

# IT Module Integration Contracts

> Version: 1.2.0 Last Updated: 2026-02-15 Status: 🟡 In Progress (IT-01 Complete, Phase B Events Implemented)

**Version:** 1.2.0\
**Last Updated:** 2026-02-15\
**Status:** 🟡 In Progress (IT-01 Complete, Phase B Events Implemented)

This document defines all integration contracts for the IT (Information Technology) core module.

***

## Overview

The IT module (IT-01 through IT-06) provides Information Technology management capabilities including asset management, support ticketing, vendor management, software licensing, security compliance, and procurement. This document specifies all events published, APIs exposed, and platform layers consumed.

***

## Status Legend

* ✅ **Implemented** - Fully implemented and tested
* 📝 **Planned** - Specified but not yet implemented
* 🟡 **In Progress** - Partially implemented

***

## Event Contracts

### IT-01: Asset Purchased Event

**Event:** `it_asset_purchased`\
**Publisher:** IT (IT-01 Asset Management)\
**Subscribers:** FA (Finance - asset capitalization)\
**Status:** ✅ Implemented\
**Last Verified:** 2026-02-15\
**Spec Reference:** [IT-01 IT Asset Management](../../../specs/it/specs/IT-01-it-asset-management.md)

**Payload Schema:**

```typescript theme={null}
{
  event_type: 'it_asset_purchased';
  asset_id: uuid;
  asset_tag: string;
  asset_type: 'desktop' | 'laptop' | 'tablet' | 'phone' | 'server' | 'network_equipment' | 'peripheral' | 'printer' | 'monitor' | 'other';
  asset_name: string;
  purchase_cost: number;
  purchase_date: date;
  vendor_id: uuid;
  vendor_name: string;
  po_number?: string;
  serial_number?: string;
  warranty_months?: number;
  organization_id: uuid;
  site_id?: uuid;
  timestamp: timestamptz;
}
```

**Implementation:**

```sql theme={null}
CREATE TRIGGER it_asset_purchased_trigger
  AFTER INSERT OR UPDATE ON it_assets
  FOR EACH ROW
  EXECUTE FUNCTION it_notify_asset_purchased();
-- Fires when purchase_cost and purchase_date are first set
```

**Consumer Actions:**

* FA: Create fixed asset record for capitalization if cost exceeds threshold
* FA: Record asset depreciation schedule

***

### IT-01: Asset Assigned Event

**Event:** `it_asset_assigned`\
**Publisher:** IT (IT-01 Asset Management)\
**Subscribers:** PF-10 (Notifications), HR\
**Status:** ✅ Implemented (channel: `it_events`, trigger on it\_asset\_assignments)
**Spec Reference:** [IT-01 IT Asset Management](../../../specs/it/specs/IT-01-it-asset-management.md)

**Payload Schema:**

```typescript theme={null}
{
  event_type: 'it_asset_assigned';
  asset_id: uuid;
  asset_tag: string;
  asset_name: string;
  asset_type: string;
  employee_id: uuid;
  employee_name: string;
  assignment_date: date;
  previous_assignee_id?: uuid;
  location: {
    site_id: uuid;
    building?: string;
    room?: string;
  };
  organization_id: uuid;
  assigned_by: uuid;
  timestamp: timestamptz;
}
```

**Consumer Actions:**

* PF-10: Notify employee of new asset assignment
* HR: Update employee equipment inventory

***

### IT-01: Asset Maintenance Required Event

**Event:** `it_asset_maintenance_required`\
**Publisher:** IT (IT-01 Asset Management)\
**Subscribers:** FM (Facilities - for work orders), PF-10 (Notifications)\
**Status:** 🟡 In Progress (DB triggers pending)
**Spec Reference:** [IT-01 IT Asset Management](../../../specs/it/specs/IT-01-it-asset-management.md)

**Payload Schema:**

```typescript theme={null}
{
  event_type: 'it_asset_maintenance_required';
  asset_id: uuid;
  asset_tag: string;
  asset_name: string;
  maintenance_type: 'repair' | 'preventive' | 'upgrade' | 'replacement';
  description: string;
  priority: 'low' | 'medium' | 'high' | 'critical';
  requested_by: uuid;
  location: {
    site_id: uuid;
    building?: string;
    room?: string;
  };
  organization_id: uuid;
  timestamp: timestamptz;
}
```

**Consumer Actions:**

* FM: Create work order for physical maintenance
* PF-10: Notify IT manager of maintenance request

***

### IT-01: Asset Disposed Event

**Event:** `it_asset_disposed`\
**Publisher:** IT (IT-01 Asset Management)\
**Subscribers:** FA (Finance), GR (Governance - for compliance tracking)\
**Status:** ✅ Implemented\
**Last Verified:** 2026-02-15\
**Spec Reference:** [IT-01 IT Asset Management](../../../specs/it/specs/IT-01-it-asset-management.md)

**Payload Schema:**

```typescript theme={null}
{
  event_type: 'it_asset_disposed';
  asset_id: uuid;
  asset_tag: string;
  asset_name: string;
  disposal_method: 'recycled' | 'sold' | 'donated' | 'destroyed';
  disposal_date: date;
  disposal_value?: number;
  data_sanitization_method?: string;
  certificate_of_destruction?: boolean;
  disposed_by: uuid;
  organization_id: uuid;
  timestamp: timestamptz;
}
```

**Implementation:**

```sql theme={null}
CREATE TRIGGER it_asset_disposed_trigger
  AFTER UPDATE ON it_assets
  FOR EACH ROW
  EXECUTE FUNCTION it_notify_asset_disposed();
-- Fires when status changes to 'disposed'
```

**Consumer Actions:**

* FA: Remove from fixed asset register, record disposal transaction
* GR: Log compliance record for data destruction (if applicable)

***

### IT-02: Ticket Created Event

**Event:** `it_ticket_created`\
**Publisher:** IT (IT-02 Support Ticketing)\
**Subscribers:** PF-10 (Notifications)\
**Status:** ✅ Implemented (channel: `it_events`, trigger on it\_tickets INSERT)\
**Spec Reference:** [IT-02 IT Support & Ticketing](../../../specs/it/specs/IT-02-it-support-ticketing.md)

**Payload Schema:**

```typescript theme={null}
{
  event_type: 'it_ticket_created';
  ticket_id: uuid;
  ticket_number: string;
  category: 'hardware' | 'software' | 'network' | 'access' | 'email' | 'other';
  subcategory?: string;
  priority: 'low' | 'medium' | 'high' | 'critical';
  subject: string;
  description: string;
  requester_id: uuid;
  requester_name: string;
  requester_email: string;
  affected_asset_id?: uuid;
  organization_id: uuid;
  site_id?: uuid;
  timestamp: timestamptz;
}
```

**Consumer Actions:**

* PF-10: Notify IT support team of new ticket
* PF-10: Send confirmation to requester

***

### IT-02: Ticket Status Changed Event

**Event:** `it_ticket_status_changed`\
**Publisher:** IT (IT-02 Support Ticketing)\
**Subscribers:** PF-10 (Notifications)\
**Status:** ✅ Implemented\
**Last Verified:** 2026-02-15\
**Spec Reference:** [IT-02 IT Support & Ticketing](../../../specs/it/specs/IT-02-it-support-ticketing.md)

**Payload Schema:**

```typescript theme={null}
{
  event_type: 'it_ticket_status_changed';
  ticket_id: uuid;
  ticket_number: string;
  old_status: 'open' | 'in_progress' | 'pending' | 'resolved' | 'closed';
  new_status: 'open' | 'in_progress' | 'pending' | 'resolved' | 'closed';
  requester_id: uuid;
  assigned_to_id?: uuid;
  changed_by: uuid;
  resolution_notes?: string;
  organization_id: uuid;
  timestamp: timestamptz;
}
```

**Implementation:**

```sql theme={null}
CREATE TRIGGER it_ticket_status_changed_trigger
  AFTER UPDATE ON it_tickets
  FOR EACH ROW
  EXECUTE FUNCTION it_notify_ticket_status_changed();
-- Fires when status changes
```

**Consumer Actions:**

* PF-10: Notify requester of status change
* PF-10: Notify assignee of assignment (if newly assigned)

***

### IT-02: SLA Breached Event

**Event:** `it_sla_breached`\
**Publisher:** IT (IT-02 Support Ticketing)\
**Subscribers:** PF-10 (Notifications), IT-02 Dashboard\
**Status:** 📝 Planned\
**Spec Reference:** [IT-02 IT Support & Ticketing](../../../specs/it/specs/IT-02-it-support-ticketing.md)

**Payload Schema:**

```typescript theme={null}
{
  event_type: 'it_sla_breached';
  ticket_id: uuid;
  ticket_number: string;
  sla_type: 'response' | 'resolution';
  sla_target_hours: number;
  actual_hours: number;
  breach_time: timestamptz;
  priority: 'low' | 'medium' | 'high' | 'critical';
  assigned_to_id?: uuid;
  organization_id: uuid;
  timestamp: timestamptz;
}
```

**Consumer Actions:**

* PF-10: Alert IT manager and assigned technician
* IT-02: Update SLA metrics on dashboard

***

### IT-03: Contract Expiring Event

**Event:** `it_contract_expiring`\
**Publisher:** IT (IT-03 Vendor Management)\
**Subscribers:** PF-10 (Notifications)\
**Status:** ✅ Implemented (channel: `it_events`, trigger when expiration within 90 days)\
**Spec Reference:** [IT-03 IT Vendor Management](../../../specs/it/specs/IT-03-it-vendor-management.md)

**Payload Schema:**

```typescript theme={null}
{
  event_type: 'it_contract_expiring';
  contract_id: uuid;
  contract_number: string;
  vendor_id: uuid;
  vendor_name: string;
  contract_type: 'support' | 'maintenance' | 'subscription' | 'lease' | 'other';
  expiration_date: date;
  days_remaining: number;
  contract_value?: number;
  auto_renew: boolean;
  organization_id: uuid;
  timestamp: timestamptz;
}
```

**Consumer Actions:**

* PF-10: Notify procurement and IT manager at 90/60/30/14/7 days

***

### IT-04: License Created Event

**Event:** `it_license_created`\
**Publisher:** IT (IT-04 Software License Management)\
**Subscribers:** FA (Finance - for cost tracking)\
**Status:** 📝 Planned\
**Spec Reference:** [IT-04 Software License Management](../../../specs/it/specs/IT-04-software-license-management.md)

**Payload Schema:**

```typescript theme={null}
{
  event_type: 'it_license_created';
  license_id: uuid;
  software_name: string;
  software_vendor: string;
  license_type: 'perpetual' | 'subscription' | 'concurrent' | 'per_user' | 'per_device' | 'site' | 'enterprise';
  license_key?: string;  // ⚠️ SENSITIVE - Do not log, redact in transit
  license_count: number;
  cost_per_license: number;
  total_cost: number;
  purchase_date: date;
  expiration_date?: date;
  vendor_id?: uuid;
  organization_id: uuid;
  timestamp: timestamptz;
}
```

**Security Notes:**

* `license_key` is a sensitive credential and MUST NOT be logged or exposed in error messages
* Consider storing a reference ID instead of the actual key in event payloads
* Mask license\_key in all observability and debugging outputs

**Consumer Actions:**

* FA: Record software asset/expense

***

### IT-04: License Expiring Event

**Event:** `it_license_expiring`\
**Publisher:** IT (IT-04 Software License Management)\
**Subscribers:** PF-10 (Notifications)\
**Status:** ✅ Implemented (channel: `it_events`, trigger when expiry within 90 days)\
**Spec Reference:** [IT-04 Software License Management](../../../specs/it/specs/IT-04-software-license-management.md)

**Payload Schema:**

```typescript theme={null}
{
  event_type: 'it_license_expiring';
  license_id: uuid;
  software_name: string;
  software_vendor: string;
  license_type: string;
  expiration_date: date;
  days_remaining: number;
  license_count: number;
  renewal_cost?: number;
  organization_id: uuid;
  timestamp: timestamptz;
}
```

**Consumer Actions:**

* PF-10: Notify IT manager and procurement at 90/60/30/14/7 days

***

### IT-04: License Renewed Event

**Event:** `it_license_renewed`\
**Publisher:** IT (IT-04 Software License Management)\
**Subscribers:** FA (Finance - for renewal costs)\
**Status:** ✅ Implemented\
**Last Verified:** 2026-02-15\
**Spec Reference:** [IT-04 Software License Management](../../../specs/it/specs/IT-04-software-license-management.md)

**Payload Schema:**

```typescript theme={null}
{
  event_type: 'it_license_renewed';
  license_id: uuid;
  software_name: string;
  software_vendor: string;
  old_expiration_date: date;
  new_expiration_date: date;
  renewal_date: date;
  renewal_cost: number;
  renewed_by: uuid;
  organization_id: uuid;
  timestamp: timestamptz;
}
```

**Implementation:**

```sql theme={null}
CREATE TRIGGER it_license_renewed_trigger
  AFTER UPDATE ON it_licenses
  FOR EACH ROW
  EXECUTE FUNCTION it_notify_license_renewed();
-- Fires when expiry_date is extended (new > old)
```

**Consumer Actions:**

* FA: Record renewal expense

***

### IT-04: License Compliance Alert Event

**Event:** `it_license_compliance_alert`\
**Publisher:** IT (IT-04 Software License Management)\
**Subscribers:** PF-10 (Notifications)\
**Status:** 📝 Planned\
**Spec Reference:** [IT-04 Software License Management](../../../specs/it/specs/IT-04-software-license-management.md)

**Payload Schema:**

```typescript theme={null}
{
  event_type: 'it_license_compliance_alert';
  license_id: uuid;
  software_name: string;
  compliance_status: 'compliant' | 'over_deployed' | 'under_utilized';
  license_count: number;
  usage_count: number;
  variance: number;
  variance_percent: number;
  threshold_breached: 'warning' | 'critical';
  organization_id: uuid;
  timestamp: timestamptz;
}
```

**Consumer Actions:**

* PF-10: Alert IT manager and compliance officer
* IT-04: Update compliance dashboard

***

### IT-05: Security Incident Created Event

**Event:** `it_security_incident_created`\
**Publisher:** IT (IT-05 Security & Compliance)\
**Subscribers:** GR (Governance & Risk), PF-10 (Notifications)\
**Status:** 📝 Planned\
**Spec Reference:** [IT-05 IT Security & Compliance](../../../specs/it/specs/IT-05-it-security-compliance.md)

**Payload Schema:**

```typescript theme={null}
{
  event_type: 'it_security_incident_created';
  incident_id: uuid;
  incident_number: string;
  incident_type: 'malware' | 'phishing' | 'unauthorized_access' | 'data_breach' | 'policy_violation' | 'other';
  severity: 'low' | 'medium' | 'high' | 'critical';
  description: string;
  affected_asset_ids?: uuid[];
  affected_user_ids?: uuid[];
  detected_at: timestamptz;
  reported_by: uuid;
  organization_id: uuid;
  site_id?: uuid;
  timestamp: timestamptz;
}
```

**Consumer Actions:**

* GR: Log compliance incident for regulatory reporting
* PF-10: Alert security team and management based on severity

***

### IT-05: Critical Vulnerability Detected Event

**Event:** `it_critical_vulnerability_detected`\
**Publisher:** IT (IT-05 Security & Compliance)\
**Subscribers:** GR (Governance), PF-10 (Notifications)\
**Status:** 📝 Planned\
**Spec Reference:** [IT-05 IT Security & Compliance](../../../specs/it/specs/IT-05-it-security-compliance.md)

**Payload Schema:**

```typescript theme={null}
{
  event_type: 'it_critical_vulnerability_detected';
  vulnerability_id: uuid;
  cve_id?: string;
  vulnerability_name: string;
  severity: 'low' | 'medium' | 'high' | 'critical';
  cvss_score?: number;
  affected_asset_ids: uuid[];
  affected_asset_count: number;
  remediation_available: boolean;
  patch_id?: uuid;
  organization_id: uuid;
  timestamp: timestamptz;
}
```

**Consumer Actions:**

* GR: Track for compliance reporting
* PF-10: Alert security team (critical = immediate)

***

### IT-05: Patch Deployment Overdue Event

**Event:** `it_patch_deployment_overdue`\
**Publisher:** IT (IT-05 Security & Compliance)\
**Subscribers:** PF-10 (Notifications)\
**Status:** 📝 Planned\
**Spec Reference:** [IT-05 IT Security & Compliance](../../../specs/it/specs/IT-05-it-security-compliance.md)

**Payload Schema:**

```typescript theme={null}
{
  event_type: 'it_patch_deployment_overdue';
  patch_id: uuid;
  patch_name: string;
  severity: 'low' | 'medium' | 'high' | 'critical';
  target_date: date;
  days_overdue: number;
  affected_asset_ids: uuid[];
  affected_asset_count: number;
  organization_id: uuid;
  timestamp: timestamptz;
}
```

**Consumer Actions:**

* PF-10: Alert IT security team and manager

***

### IT-06: Purchase Request Submitted Event

**Event:** `it_purchase_request_submitted`\
**Publisher:** IT (IT-06 Procurement)\
**Subscribers:** FW-34 (Approval Workflows), PF-10 (Notifications)\
**Status:** ✅ Implemented (channel: `it_events`, trigger when approval\_status = submitted)\
**Spec Reference:** [IT-06 IT Procurement](../../../specs/it/specs/IT-06-it-procurement.md)

**Payload Schema:**

```typescript theme={null}
{
  event_type: 'it_purchase_request_submitted';
  request_id: uuid;
  request_number: string;
  requester_id: uuid;
  requester_name: string;
  request_type: 'hardware' | 'software' | 'service' | 'renewal';
  estimated_cost: number;
  justification: string;
  vendor_id?: uuid;
  vendor_name?: string;
  organization_id: uuid;
  site_id?: uuid;
  timestamp: timestamptz;
}
```

**Consumer Actions:**

* FW-34: Initiate approval workflow based on cost thresholds
* PF-10: Notify approvers

***

### IT-06: Purchase Request Approved Event

**Event:** `it_purchase_request_approved`\
**Publisher:** IT (IT-06 Procurement)\
**Subscribers:** FA-04 (Purchase Orders), PF-10 (Notifications)\
**Status:** ✅ Implemented (channel: `it_events`, trigger when approval\_status = approved)\
**Spec Reference:** [IT-06 IT Procurement](../../../specs/it/specs/IT-06-it-procurement.md)

**Payload Schema:**

```typescript theme={null}
{
  event_type: 'it_purchase_request_approved';
  request_id: uuid;
  request_number: string;
  requester_id: uuid;
  request_type: 'hardware' | 'software' | 'service' | 'renewal';
  estimated_cost: number;
  vendor_id?: uuid;
  vendor_name?: string;
  approved_by: uuid;
  approved_at: timestamptz;
  approval_notes?: string;
  organization_id: uuid;
  timestamp: timestamptz;
}
```

**Consumer Actions:**

* FA-04: Create purchase order
* PF-10: Notify requester of approval

***

### IT-06: Purchase Request Received Event

**Event:** `it_purchase_request_received`\
**Publisher:** IT (IT-06 Procurement)\
**Subscribers:** IT-01 (Asset creation), PF-10 (Notifications)\
**Status:** 📝 Planned\
**Spec Reference:** [IT-06 IT Procurement](../../../specs/it/specs/IT-06-it-procurement.md)

**Payload Schema:**

```typescript theme={null}
{
  event_type: 'it_purchase_request_received';
  request_id: uuid;
  request_number: string;
  po_number?: string;
  items_received: [{
    item_description: string;
    quantity: number;
    serial_numbers?: string[];
  }];
  received_by: uuid;
  received_date: date;
  vendor_id?: uuid;
  organization_id: uuid;
  timestamp: timestamptz;
}
```

**Consumer Actions:**

* IT-01: Create asset records for received hardware
* PF-10: Notify requester of receipt

***

## API Contracts

### IT-01: Asset Lookup API

**Endpoint:** `GET /api/v1/it/assets/{asset_id}`\
**Method:** GET\
**Provider:** IT (IT-01 Asset Management)\
**Consumer:** IT-02 (ticket linking), IT-05 (security tracking)\
**Status:** 📝 Planned\
**Spec Reference:** [IT-01 IT Asset Management](../../../specs/it/specs/IT-01-it-asset-management.md)

**Purpose:** Lookup IT asset details for ticket linking and security tracking.

**Request:**

```
GET /api/v1/it/assets/{asset_id}
Authorization: Bearer {jwt_token}
```

**Path Parameters:**

* `asset_id` (required): UUID of asset

**Response Schema (200 OK):**

```typescript theme={null}
{
  asset_id: uuid;
  asset_tag: string;
  asset_name: string;
  asset_type: 'desktop' | 'laptop' | 'tablet' | 'phone' | 'server' | 'network_equipment' | 'peripheral' | 'printer' | 'monitor' | 'other';
  manufacturer: string;
  model: string;
  serial_number: string;
  status: 'available' | 'assigned' | 'in_repair' | 'retired' | 'disposed';
  assigned_to_employee_id?: uuid;
  assigned_to_name?: string;
  location: {
    site_id: uuid;
    site_name: string;
    building?: string;
    room?: string;
  };
  purchase_date?: date;
  warranty_expiration_date?: date;
  last_maintenance_date?: date;
  organization_id: uuid;
}
```

**Error Codes:**

* `404 Not Found`: Asset not found
* `403 Forbidden`: User does not have access to asset
* `500 Internal Server Error`: Internal IT error

**Authentication:** JWT required, RLS enforces organization isolation\
**Rate Limiting:** 100 requests/minute per organization\
**Version:** v1.0.0 (planned)

***

### IT-01: Asset Search API

**Endpoint:** `GET /api/v1/it/assets`\
**Method:** GET\
**Provider:** IT (IT-01 Asset Management)\
**Consumer:** IT-02, IT-04, IT-05, IT-06\
**Status:** 📝 Planned\
**Spec Reference:** [IT-01 IT Asset Management](../../../specs/it/specs/IT-01-it-asset-management.md)

**Purpose:** Search and filter IT assets.

**Request:**

```
GET /api/v1/it/assets?asset_type=laptop&status=assigned&site_id={uuid}&page=1&page_size=50
Authorization: Bearer {jwt_token}
```

**Query Parameters:**

* `asset_type` (optional): Filter by asset type
* `status` (optional): Filter by status
* `site_id` (optional): Filter by site
* `assigned_to` (optional): Filter by assigned employee ID
* `search` (optional): Search by asset tag, name, or serial number
* `page` (optional): Page number (default: 1)
* `page_size` (optional): Results per page (default: 50, max: 100)

**Response Schema (200 OK):**

```typescript theme={null}
{
  assets: [{
    asset_id: uuid;
    asset_tag: string;
    asset_name: string;
    asset_type: string;
    status: string;
    assigned_to_name?: string;
    site_name: string;
  }];
  total_count: number;
  page: number;
  page_size: number;
  has_next_page: boolean;
}
```

**Authentication:** JWT required, RLS enforces organization isolation\
**Rate Limiting:** 100 requests/minute per organization\
**Version:** v1.0.0 (planned)

***

### IT-03: Vendor Lookup API

**Endpoint:** `GET /api/v1/it/vendors/{vendor_id}`\
**Method:** GET\
**Provider:** IT (IT-03 Vendor Management)\
**Consumer:** IT-01, IT-04, IT-06\
**Status:** 📝 Planned\
**Spec Reference:** [IT-03 IT Vendor Management](../../../specs/it/specs/IT-03-it-vendor-management.md)

**Purpose:** Lookup IT vendor details for asset, license, and procurement linking.

**Request:**

```
GET /api/v1/it/vendors/{vendor_id}
Authorization: Bearer {jwt_token}
```

**Path Parameters:**

* `vendor_id` (required): UUID of vendor

**Response Schema (200 OK):**

```typescript theme={null}
{
  vendor_id: uuid;
  vendor_name: string;
  vendor_type: 'hardware' | 'software' | 'service' | 'consulting' | 'reseller';
  contact_name?: string;
  contact_email?: string;
  contact_phone?: string;
  website?: string;
  status: 'active' | 'inactive' | 'suspended';
  payment_terms?: string;
  contract_count: number;
  active_contracts: [{
    contract_id: uuid;
    contract_type: string;
    expiration_date: date;
  }];
  organization_id: uuid;
}
```

**Error Codes:**

* `404 Not Found`: Vendor not found
* `403 Forbidden`: User does not have access to vendor
* `500 Internal Server Error`: Internal IT error

**Authentication:** JWT required, RLS enforces organization isolation\
**Rate Limiting:** 100 requests/minute per organization\
**Version:** v1.0.0 (planned)

***

### IT-04: License Compliance Check API

**Endpoint:** Database function `it_check_license_compliance()`\
**Provider:** IT (IT-04 Software License Management)\
**Consumer:** IT-04 dashboard, scheduled compliance checks\
**Status:** 📝 Planned\
**Spec Reference:** [IT-04 Software License Management](../../../specs/it/specs/IT-04-software-license-management.md)

**Purpose:** Check license compliance for a software license or all licenses.

**Function Signature:**

```sql theme={null}
it_check_license_compliance(
  p_organization_id UUID,
  p_license_id UUID DEFAULT NULL  -- NULL = check all
) RETURNS TABLE (
  license_id UUID,
  software_name TEXT,
  license_count INTEGER,
  usage_count INTEGER,
  compliance_status TEXT,  -- 'compliant' | 'over_deployed' | 'under_utilized'
  variance INTEGER,
  variance_percent NUMERIC
)
```

**Usage Example:**

```sql theme={null}
-- Check all licenses for organization
SELECT * FROM it_check_license_compliance('org-uuid-here');

-- Check specific license
SELECT * FROM it_check_license_compliance('org-uuid-here', 'license-uuid-here');
```

**Security Notes:**

* Function is `SECURITY DEFINER` to avoid RLS recursion
* Always uses `SET search_path = public` for security
* Returns only licenses within organization context

**Version:** v1.0.0 (planned)

***

## Platform Integration Layer Usage

### Platform Layers Used by IT Module

| Layer                      | Spec                                                                                                            | Usage                                                             | Consuming Specs            |
| -------------------------- | --------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | -------------------------- |
| Forms (PF-08)              | [PLATFORM\_INTEGRATION\_LAYERS.md](./PLATFORM_INTEGRATION_LAYERS.md#pf-08-forms-integration-layer)              | Ticket submission forms, Purchase request forms                   | IT-02, IT-06               |
| Workforce                  | [PLATFORM\_INTEGRATION\_LAYERS.md](./PLATFORM_INTEGRATION_LAYERS.md#pf-14-platform-workforce-integration-layer) | Employee assignments for assets, ticket assignments               | IT-01, IT-02               |
| Data Lookup (PF-15)        | [PLATFORM\_INTEGRATION\_LAYERS.md](./PLATFORM_INTEGRATION_LAYERS.md#pf-15-data-lookup-integration-layer)        | Asset, vendor, employee selectors                                 | IT-01, IT-02, IT-03, IT-06 |
| Custom Fields (PF-16)      | [PLATFORM\_INTEGRATION\_LAYERS.md](./PLATFORM_INTEGRATION_LAYERS.md#pf-16-custom-fields-integration-layer)      | Org-specific metadata on all IT entities                          | All IT specs               |
| Notifications (PF-10)      | [PLATFORM\_INTEGRATION\_LAYERS.md](./PLATFORM_INTEGRATION_LAYERS.md#pf-10-notifications-integration-layer)      | SLA alerts, expiration alerts, compliance alerts, security alerts | All IT specs               |
| Documents (PF-11)          | [PLATFORM\_INTEGRATION\_LAYERS.md](./PLATFORM_INTEGRATION_LAYERS.md#pf-11-documents-integration-layer)          | Warranties, manuals, ticket attachments, contracts                | IT-01, IT-02, IT-03        |
| Approval Workflows (FW-34) | [CROSS\_CORE\_INTEGRATIONS.md](./CROSS_CORE_INTEGRATIONS.md#fw-forms--workflow)                                 | Purchase request approvals                                        | IT-06                      |

***

## Internal IT Module Integrations

The IT module has several internal integrations between its own specs:

| From  | To    | Type  | Description                           |
| ----- | ----- | ----- | ------------------------------------- |
| IT-02 | IT-01 | API   | Tickets link to assets for context    |
| IT-04 | IT-01 | API   | Licenses assigned to assets           |
| IT-04 | IT-03 | API   | Licenses linked to vendors            |
| IT-05 | IT-01 | API   | Security patches target assets        |
| IT-05 | IT-02 | Event | Security incidents may create tickets |
| IT-06 | IT-01 | Event | Received purchases create assets      |
| IT-06 | IT-03 | API   | Purchase requests select vendors      |
| IT-06 | IT-04 | Event | Received purchases create licenses    |

***

## Cross-Core Dependencies

### IT Module Depends On:

* **PF-01 (Organizations & Sites):** Multi-tenant context for all IT entities
* **PF-02 (RBAC):** Role-based access control for IT functions
* **HR-01 (Employee Directory):** Employee lookup for asset assignment
* **FA-04 (Purchase Orders):** PO creation from approved IT purchases

### Cores That Depend on IT Module:

* **FM (Facilities):** May receive IT asset maintenance requests
* **GR (Governance):** Receives security incidents and compliance data
* **FA (Finance):** Receives asset capitalization and expense data

***

## Event Summary Table

| Event                                | Publisher | Subscribers      | Status         |
| ------------------------------------ | --------- | ---------------- | -------------- |
| `it_asset_purchased`                 | IT-01     | FA               | ✅ Implemented  |
| `it_asset_assigned`                  | IT-01     | PF-10, HR        | ✅ Implemented  |
| `it_asset_maintenance_required`      | IT-01     | FM, PF-10        | 🟡 In Progress |
| `it_asset_disposed`                  | IT-01     | FA, GR           | ✅ Implemented  |
| `it_ticket_created`                  | IT-02     | PF-10            | ✅ Implemented  |
| `it_ticket_status_changed`           | IT-02     | PF-10            | ✅ Implemented  |
| `it_sla_breached`                    | IT-02     | PF-10, IT-02     | 📝 Planned     |
| `it_contract_expiring`               | IT-03     | PF-10            | ✅ Implemented  |
| `it_license_created`                 | IT-04     | FA               | 📝 Planned     |
| `it_license_expiring`                | IT-04     | PF-10            | ✅ Implemented  |
| `it_license_renewed`                 | IT-04     | FA               | ✅ Implemented  |
| `it_license_compliance_alert`        | IT-04     | PF-10            | 📝 Planned     |
| `it_security_incident_created`       | IT-05     | GR, PF-10        | 📝 Planned     |
| `it_critical_vulnerability_detected` | IT-05     | GR, PF-10        | 📝 Planned     |
| `it_patch_deployment_overdue`        | IT-05     | PF-10            | 📝 Planned     |
| `it_purchase_request_submitted`      | IT-06     | FW-34, PF-10     | ✅ Implemented  |
| `it_purchase_request_approved`       | IT-06     | FA-04, PF-10     | ✅ Implemented  |
| `it_purchase_request_received`       | IT-06     | IT-01, PF-10     | 📝 Planned     |
| `it_report_generated`                | IT-07     | PF-10, PF-11     | 📝 Planned     |
| `it_report_failed`                   | IT-07     | PF-10            | 📝 Planned     |
| `it_provisioning_started`            | IT-08     | HR-03, PF-10     | ✅ Implemented  |
| `it_provisioning_completed`          | IT-08     | HR-03, PF-10     | ✅ Implemented  |
| `it_account_provisioned`             | IT-08     | PF-10, Audit     | ✅ Implemented  |
| `it_account_deactivated`             | IT-08     | PF-10, Audit, GR | ✅ Implemented  |
| `it_change_submitted`                | IT-09     | PF-10            | 📝 Planned     |
| `it_change_approved`                 | IT-09     | PF-10            | ✅ Implemented  |
| `it_change_rejected`                 | IT-09     | PF-10            | 📝 Planned     |
| `it_change_scheduled`                | IT-09     | PF-10            | 📝 Planned     |
| `it_change_implemented`              | IT-09     | PF-10, IT-07     | 📝 Planned     |
| `it_change_rolled_back`              | IT-09     | PF-10, GR, IT-02 | 📝 Planned     |
| `it_cab_review_required`             | IT-09     | PF-10            | 📝 Planned     |

***

## API Summary Table

| Endpoint                                     | Method      | Provider | Consumers                  | Status     |
| -------------------------------------------- | ----------- | -------- | -------------------------- | ---------- |
| `/api/v1/it/assets/{asset_id}`               | GET         | IT-01    | IT-02, IT-05               | 📝 Planned |
| `/api/v1/it/assets`                          | GET         | IT-01    | IT-02, IT-04, IT-05, IT-06 | 📝 Planned |
| `/api/v1/it/vendors/{vendor_id}`             | GET         | IT-03    | IT-01, IT-04, IT-06        | 📝 Planned |
| `it_check_license_compliance()`              | DB Function | IT-04    | IT-04 Dashboard            | 📝 Planned |
| `/api/v1/it/dashboard/summary`               | GET         | IT-07    | IT Dashboard               | 📝 Planned |
| `/api/v1/it/dashboard/widgets/:widget_id`    | GET         | IT-07    | IT Dashboard               | 📝 Planned |
| `/api/v1/it/reports/run/:report_id`          | POST        | IT-07    | Report Builder             | 📝 Planned |
| `/api/v1/it/reports/:run_id/download`        | GET         | IT-07    | Report Viewer              | 📝 Planned |
| `/api/v1/it/onboarding/pending`              | GET         | IT-08    | IT Onboarding Dashboard    | 📝 Planned |
| `/api/v1/it/onboarding/:id/complete-task`    | POST        | IT-08    | Task Completion            | 📝 Planned |
| `/api/v1/it/offboarding/pending`             | GET         | IT-08    | IT Offboarding Dashboard   | 📝 Planned |
| `/api/v1/it/accounts/:employee_id/provision` | POST        | IT-08    | Account Provisioning       | 📝 Planned |
| `/api/v1/it/accounts/:account_id/deactivate` | POST        | IT-08    | Account Deactivation       | 📝 Planned |

***

## IT-08 Events (Onboarding/Offboarding)

### IT-08: Provisioning Started Event

**Event:** `it_provisioning_started`\
**Publisher:** IT (IT-08)\
**Subscribers:** HR-03, PF-10\
**Status:** ✅ Implemented\
**Last Verified:** 2026-02-15

**Implementation:**

```sql theme={null}
CREATE TRIGGER it_provisioning_status_trigger
  AFTER UPDATE ON it_onboarding_instances
  FOR EACH ROW
  EXECUTE FUNCTION it_notify_provisioning_status();
-- Fires when status changes to 'in_progress'
```

### IT-08: Provisioning Completed Event

**Event:** `it_provisioning_completed`\
**Publisher:** IT (IT-08)\
**Subscribers:** HR-03, PF-10\
**Status:** ✅ Implemented\
**Last Verified:** 2026-02-15

**Implementation:** Same trigger as above; fires when status changes to 'completed'.

### IT-08: Account Provisioned Event

**Event:** `it_account_provisioned`\
**Publisher:** IT (IT-08)\
**Subscribers:** PF-10, Audit\
**Status:** ✅ Implemented\
**Last Verified:** 2026-02-15

**Implementation:**

```sql theme={null}
CREATE TRIGGER it_account_status_trigger
  AFTER UPDATE ON it_access_accounts
  FOR EACH ROW
  EXECUTE FUNCTION it_notify_account_status();
-- Fires when status changes to 'active'
```

### IT-08: Account Deactivated Event

**Event:** `it_account_deactivated`\
**Publisher:** IT (IT-08)\
**Subscribers:** PF-10, Audit, GR\
**Status:** ✅ Implemented\
**Last Verified:** 2026-02-15

**Implementation:** Same trigger as above; fires when status changes to 'deactivated'.

***

## Related Documentation

* [IT-01 IT Asset Management Spec](../../../specs/it/specs/IT-01-it-asset-management.md)
* [IT-02 IT Support & Ticketing Spec](../../../specs/it/specs/IT-02-it-support-ticketing.md)
* [IT-03 IT Vendor Management Spec](../../../specs/it/specs/IT-03-it-vendor-management.md)
* [IT-04 Software License Management Spec](../../../specs/it/specs/IT-04-software-license-management.md)
* [IT-05 IT Security & Compliance Spec](../../../specs/it/specs/IT-05-it-security-compliance.md)
* [IT-06 IT Procurement Spec](../../../specs/it/specs/IT-06-it-procurement.md)
* [IT-07 IT Dashboard & Reporting Spec](../../../specs/it/specs/IT-07-it-dashboard-reporting.md)
* [IT-08 IT Onboarding/Offboarding Spec](../../../specs/it/specs/IT-08-it-onboarding-offboarding.md)
* [IT-09 IT Change Management Spec](../../../specs/it/specs/IT-09-it-change-management.md)
* [IT Implementation Log](../../../specs/it/IMPLEMENTATION_LOG.md)
* [Event Contracts](./EVENT_CONTRACTS.md)
* [API Contracts](./API_CONTRACTS.md)
* [Cross-Core Integrations](./CROSS_CORE_INTEGRATIONS.md)

***

**Last Updated:** 2026-02-15\
**Next Review:** After IT-02 Implementation