Import & Export Functionality
Relevant source files
The following files were used as context for generating this wiki page:
The IT Management System provides a standardized framework for data mobility through specialized import and export tools. These features are primarily driven by the js/table-tools.js library, which integrates with module-specific PHP handlers to enable seamless transition between spreadsheet formats (XLSX, CSV) and the MySQL database. Sources: js/table-tools.js, wiki/Import-Excel.md:3-8
The scope of this functionality covers bulk data ingestion for assets, employees, and configuration, as well as reporting through PDF and Excel exports. High-level operations are governed by multi-tenant scoping rules, ensuring that data is always processed within the context of the active company_id. Sources: wiki/Import-Excel.md:41-45, scripts/api.php:127-133
Architecture and Data Flow
The system employs a client-server model for data imports. The frontend utilizes FileReader APIs and vendor libraries like xlsx.full.min.js to parse local files before transmitting JSON payloads to the server. Sources: js/table-tools.js:255-280, js/AGENT_NOTES.md:12-15
Import Process Flow
The following diagram illustrates the sequence from file selection to database persistence.
Import Implementation
Requirements for Module Integration
To enable database imports for a specific module, the HTML table must be decorated with the data-itm-db-import-endpoint attribute pointing to the handler script (usually index.php). Sources: wiki/Import-Excel.md:17-21, js/table-tools.js:192-194
On the server side, modules must implement a JSON handler block at the top of their index.php file to capture the php://input stream and pass it to the shared itm_handle_json_table_import() function. Sources: wiki/Import-Excel.md:23-33, scripts/api.php:157-170
Specialized Import Handlers
Certain modules, such as Bookmarks, implement custom import logic for specific file formats like HTML browser exports. Sources: modules/bookmarks/import.php:21-40
| Module | Supported Formats | Primary Logic |
|---|---|---|
| Standard CRUD | XLSX, XLS, CSV | itm_handle_json_table_import |
| Bookmarks | HTML, CSV | bkm_parse_html_bookmarks |
| Alerts | ICS, JSON | Support for calendar file imports |
| Explorer | Files (Bulk) | Direct file system upload management |
| Sources: scripts/api.php:97-111, modules/bookmarks/import.php:30-45, wiki/Modules.md:45-50 |
Export Functionality
Exports are handled entirely on the client side for standard list views. The system offers two primary export formats:
- Excel (XLSX): Generates a true OOXML
.xlsxfile using the SheetJS library to avoid format/extension warnings. Sources: js/table-tools.js:103-118 - PDF: Opens a new print window with a styled HTML representation of the table, including automatic page-break handling. Sources: js/table-tools.js:127-149
Export UI Logic
The system automatically attaches a toolbar to tables within the .content .card container. Sources: js/table-tools.js:464-470
API and Technical Contract
Import Payload Structure
The system expects a specific JSON format for bulk imports via the table-tools interface. Sources: scripts/api.php:172-181
{
"csrf_token": "<token>",
"import_excel_rows": [
["Header1", "Header2"],
["Value1", "Value2"]
]
}
Sources: wiki/Import-Excel.md:47-52
Configuration Parameters
The visibility and positioning of import/export tools are governed by tenant-level settings. Sources: js/table-tools.js:380-385, wiki/Modules.md:58-62
| Parameter | Type | Description |
|---|---|---|
export_buttons_position | String | Position of the toolbar (left, right, top_bottom, etc.) |
data-itm-no-import-excel | Attribute | Disables the import button for a specific table |
data-itm-no-export-excel | Attribute | Disables XLSX export for a specific table |
data-itm-no-export-pdf | Attribute | Disables PDF export for a specific table |
| Sources: js/table-tools.js:348-356, js/table-tools.js:397-405 |
Security and Validation
- CSRF Protection: Every POST request must include a
csrf_token. The frontend retrieves this from a hidden input field on the page. Sources: js/table-tools.js:201-205, js/AGENT_NOTES.md:7-10 - Multi-Tenancy: The server-side handler
itm_handle_json_table_importautomatically injects the active session'scompany_idinto every imported row if the column exists in the target table. Sources: wiki/Import-Excel.md:54-58, scripts/api.php:132-136 - Safe Identifiers: Table names and column names must pass
itm_is_safe_identifier()to prevent SQL injection. Sources: wiki/Import-Excel.md:33-35
Conclusion
The Import & Export functionality is a standardized, secure, and multi-tenant aware system designed for high data throughput. By combining client-side parsing with strict server-side validation, the system ensures data integrity while providing users with flexible options for reporting and bulk data management. Sources: wiki/Import-Excel.md:86-90, scripts/api.php:218-225