Organizational Structure & Employees
Relevant source files
The following files were used as context for generating this wiki page:
The Organizational Structure & Employees system serves as the core identity management layer of the IT Management System. It facilitates the management of employee records, departmental structures, and complex reporting hierarchies. The system is designed with a multi-tenant architecture, ensuring that employee data and organizational charts are strictly isolated by company_id.
This module provides not only standard CRUD (Create, Read, Update, Delete) capabilities but also advanced features such as interactive organizational charts with drag-and-drop hierarchy updates, bulk Excel/CSV imports with automated lookup resolution, and multi-field duplicate detection to maintain data integrity.
Sources: modules/employees/AGENT_NOTES.md:4, modules/org_chart/AGENT_NOTES.md:4, AGENT_NOTES.md:4
Core Data Model
The organizational structure is built upon four primary entities that define an employee's place within a company. The relationships between these entities are governed by foreign keys and a self-referencing hierarchy within the employees table.
Entity Relationships
The following diagram illustrates how employees are linked to departments, positions, and their managers.
The system relies on the reports_to field to construct the reporting chain.
Sources: modules/employees/AGENT_NOTES.md:6-12, modules/org_chart/AGENT_NOTES.md:12
Primary Tables Summary
| Table | Purpose | Key Dependencies |
|---|---|---|
employees | Main repository for contact info, hierarchy, and employment details. | company_id, department_id, reports_to |
departments | Manages organizational units and their contact information. | company_id |
employee_positions | Lookup table for job titles and positions. | company_id |
employee_statuses | Defines employment states (e.g., Active, Terminated, On Leave). | company_id |
Sources: modules/departments/AGENT_NOTES.md:4-10, modules/employee_positions/AGENT_NOTES.md:4-10, modules/employee_statuses/AGENT_NOTES.md:4-10
Employee Management & Lifecycle
The employees module handles the complete lifecycle of a staff member. Key features include photo uploads, unique employee codes, and visibility flags that control how employees appear in other modules.
Visibility Rules
Visibility is controlled by specific boolean flags and status checks:
- Org Chart Visibility: Only employees with
on_orgchart = 1and an "Active" status are rendered in the visual hierarchy. - Contacts Visibility: Only employees with
on_contacts = 1and an active status are displayed in the Contacts/Directory module.
Sources: modules/employees/AGENT_NOTES.md:15-18, modules/org_chart/AGENT_NOTES.md:16
Duplicate Detection Logic
To prevent data fragmentation, the system runs a cross-check within the database to flag duplicate records based on four criteria: work_email, personal_email, employee_code, and external_id.
// modules/employees/index.php:156-168
function emp_recalculate_duplicates($conn, $company_id) {
$cid = (int)$company_id;
mysqli_query($conn, 'UPDATE employees SET duplicate=0 WHERE company_id=' . $cid);
$duplicateConditions = [];
foreach (['work_email', 'personal_email', 'employee_code', 'external_id'] as $field) {
$fieldEsc = emp_escape_identifier($field);
$duplicateConditions[] = "(LOWER(TRIM(COALESCE(" . $fieldEsc . ", ''))) IN (SELECT ident FROM (SELECT LOWER(TRIM(" . $fieldEsc . ")) AS ident FROM employees WHERE company_id=" . $cid . " AND " . $fieldEsc . " IS NOT NULL AND TRIM(" . $fieldEsc . ") <> '' GROUP BY LOWER(TRIM(" . $fieldEsc . ")) HAVING COUNT(*) > 1) dups) AND " . $fieldEsc . " IS NOT NULL AND TRIM(" . $fieldEsc . ") <> '')";
}
// ... logic to update duplicate flag
}
Sources: modules/employees/index.php:156-172
Organizational Chart & Hierarchy
The Org Chart module provides an interactive tree visualization of the company reporting structure. It utilizes a recursive algorithm to build the tree and includes safety mechanisms to prevent infinite loops.
Drag and Drop Hierarchy Updates
Users can reassign managers by dragging an employee node onto another. This action triggers an AJAX request to the update_hierarchy endpoint.
Cycle Detection Algorithm
The system prevents an employee from reporting to themselves or any of their own subordinates through an in-memory map-based cycle detection function.
// modules/org_chart/index.php:73-84
function itm_is_circular_reporting($employeeMap, $startReportsTo, $targetEmployeeId) {
$current = $startReportsTo;
$visited = [];
while ($current > 0) {
if ($current === $targetEmployeeId) return true;
if (isset($visited[$current])) return true;
$visited[$current] = true;
$current = isset($employeeMap[$current]) ? $employeeMap[$current] : 0;
}
return false;
}
Sources: modules/org_chart/index.php:73-84
Data Import System
The system supports bulk data entry through a robust JSON-based import endpoint (import_excel_rows). This endpoint is capable of resolving text-based names (like "IT Department") into their corresponding database IDs automatically.
Import Workflow
- Header Normalization: The system maps various column names (e.g., "Job Title", "Position") to canonical database fields.
- Lookup Resolution: It checks if departments or positions exist; if not, it creates them on-the-fly for the current tenant.
- Full Sync Option: The logic can identify and remove records not present in the import file to perform a complete synchronization.
Sources: modules/employees/index.php:61-105, modules/employees/index.php:258-290
| Canonical Header | Source Variation Examples |
|---|---|
external_id | Hilton ID, External ID |
work_email | Work Email, Email |
employment_status_id | Status, Employment Status |
department_id | Department Name, Department |
Sources: modules/employees/index.php:70-110
Multi-Tenant Security
Data isolation is strictly enforced at the database layer. Every query interacting with employees, departments, or positions MUST filter by company_id retrieved from the user's session.
Safe Pattern Example:
$stmt = $conn->prepare("SELECT * FROM employees WHERE company_id = ? AND id = ?");
$stmt->bind_param("ii", $companyId, $id);
$stmt->execute();
Sources: modules/employees/AGENT_NOTES.md:29-33, modules/org_chart/AGENT_NOTES.md:30-34
Summary
The Organizational Structure & Employees system provides a comprehensive framework for managing human resources within an IT infrastructure context. By combining strict multi-tenant isolation with interactive visualization tools and intelligent import mechanisms, it ensures that organizational data remains accurate, navigable, and secure across multiple companies.