Integration Approach

This page explains the architecture behind the Flexivity AI osTicket plugin. It is intended for system administrators and technical staff who want to understand exactly how the integration works, verify that it follows osTicket best practices, and confirm it will not interfere with their existing helpdesk operations.

Architecture Overview

The Flexivity AI plugin integrates with osTicket through four layers, each designed to minimize impact on osTicket’s core operation:

1. Signal handlers capture ticket events (created, updated, closed) using osTicket’s built-in signal system.
2. An event queue table decouples event capture from processing, ensuring osTicket request handling is never blocked.
3. Flexivity AI polls the event queue, sends events for AI processing, and receives results.
4. A write-back REST API allows Flexivity AI to store AI-generated summaries and recommendations in plugin-specific tables.

┌─────────────────────────────────────────────────────────────────┐
│                        osTicket Server                          │
│                                                                 │
│  ┌──────────────┐    signal     ┌──────────────────────┐        │
│  │ Ticket Event  │─────────────>│ FAI Signal Handler   │        │
│  │ (create/edit/ │              │ (non-blocking)       │        │
│  │  close)       │              └──────────┬───────────┘        │
│  └──────────────┘                          │                    │
│                                    INSERT row                   │
│                                            │                    │
│                                            v                    │
│                               ┌────────────────────┐           │
│                               │  fai_event_queue   │           │
│                               │  (MySQL table)     │           │
│                               └────────┬───────────┘           │
│                                        │                        │
│  ┌─────────────────────┐               │ poll                   │
│  │ fai_summaries       │               │                        │
│  │ fai_recommendations │<──────┐       │                        │
│  └─────────────────────┘       │       │                        │
│                                │       │                        │
│  ┌──────────────────────┐      │       │                        │
│  │ FAI Write-back API   │──────┘       │                        │
│  │ (REST endpoint)      │              │                        │
│  └──────────┬───────────┘              │                        │
│             ^                          │                        │
└─────────────┼──────────────────────────┼────────────────────────┘
              │                          │
              │  write results           │  read events
              │                          v
        ┌─────────────────────────────────────┐
        │         Flexivity AI Agent          │
        │   (polls queue, sends to cloud,     │
        │    writes results back)             │
        └─────────────────────────────────────┘
                         │
                         │ scrubbed events
                         v
                ┌──────────────────┐
                │  Flexivity AI    │
                │  Cloud Platform  │
                │  (AI processing) │
                └──────────────────┘

Note: The diagram above shows the agent deployment mode. In direct connection mode, Flexivity AI communicates with the plugin REST API directly from the cloud rather than through a local agent.

The key design principle is that every interaction with osTicket is non-blocking and non-destructive. The plugin never modifies osTicket core tables, never performs slow operations during request handling, and can be fully removed without leaving any trace.

Signal-Based Event Capture

osTicket provides a built-in signal system for extending its functionality without modifying core source files. Signals are similar in concept to WordPress hooks or Django signals — they allow plugins to register callback functions that are invoked when specific events occur within the application.

The Flexivity AI plugin registers signal handlers for the following osTicket events:

• ticket.created — A new ticket is submitted.
• object.edited — A ticket or thread entry is modified.
• ticket.closed — A ticket is resolved and closed.

These are the same extension points used by osTicket’s own bundled plugins (such as authentication backends and storage plugins). Signal-based integration is the documented, recommended approach for osTicket plugin development.

Why Signals Are the Right Approach

• Officially supported: Signals are part of osTicket’s public plugin API. They are maintained across osTicket releases and are the intended mechanism for third-party extensions.
• No core file modifications: The plugin registers its handlers through osTicket’s plugin bootstrap process. No osTicket source files are patched, overwritten, or monkey-patched.
• Version-resilient: Because the plugin depends on stable signal names rather than internal implementation details, it remains compatible across osTicket minor and patch releases (1.17.x, 1.18.x).

Fire-and-Forget Event Queue

This is the most important architectural decision in the plugin. Signal handlers execute inline during osTicket’s request processing cycle. If a signal handler performs a slow operation — such as an HTTP request to an external API — it blocks the entire request for every user interacting with osTicket.

The Flexivity AI plugin avoids this entirely. Signal handlers do exactly one thing: insert a row into the fai_event_queue table. This is a single MySQL INSERT operation against a local table, typically completing in under 1 millisecond.

Signal fires  ──>  INSERT INTO fai_event_queue (...)  ──>  Signal returns
                   (single local MySQL write)

The handler does not:

• Make HTTP or HTTPS requests to any external service.
• Perform DNS lookups or network I/O.
• Read from remote APIs, cloud services, or the Flexivity AI platform.
• Execute complex queries, joins, or aggregations.
• Acquire locks or wait on external resources.

What This Means in Practice

• No added latency: Ticket creation, editing, and closure remain as fast as they were before the plugin was installed. The overhead of a single INSERT to a local table is negligible.
• No failure coupling: If the Flexivity AI cloud platform is unreachable, or the agent is offline, osTicket continues operating normally. Events accumulate in the queue and are processed when connectivity is restored.
• No timeout risk: There is no possibility of an external API timeout causing osTicket to hang or return an error to the user.

How Events Are Processed

The Flexivity AI agent — running as a separate process alongside osTicket — polls the fai_event_queue table on a regular interval. When it finds unprocessed events, it:

1. Reads the event data from the queue.
2. Scrubs any personally identifiable information (PII) before transmission.
3. Sends the scrubbed event to the Flexivity AI cloud platform for processing.
4. Marks the event as processed in the queue.

This polling model ensures that all processing happens outside of osTicket’s request cycle.

Write-Back Mechanism

After the Flexivity AI platform processes an event and generates results (such as a ticket summary or a recommended response), those results need to be delivered back to osTicket so that agents can see them.

The plugin exposes a lightweight REST API endpoint on the osTicket server. Flexivity AI calls this endpoint to write results back. Authentication is handled via JWT tokens, ensuring that only authorized connections can submit data.

Plugin-Specific Storage Tables

AI-generated results are stored in dedicated plugin tables:

• fai_summaries — Stores AI-generated ticket summaries, linked to the originating ticket by ticket ID. For each ticket, only the latest summary is stored — updated summaries overwrite the prior version rather than being appended.
• fai_recommendations — Stores recommended responses and suggested actions for agents.

These tables are entirely owned by the Flexivity AI plugin. The plugin never writes to, modifies, or alters any osTicket core table. Ticket data, thread entries, user records, department configurations, and all other osTicket data remain untouched.

Why This Matters

• No schema conflicts: osTicket upgrades can modify their own tables without risk of collision with plugin data.
• Straightforward debugging: If an issue arises, plugin data lives in clearly namespaced tables (fai_* prefix) that can be inspected independently of osTicket core data.
• Safe rollback: Removing the plugin and its tables has zero effect on osTicket’s data integrity.

Database Isolation

The Flexivity AI plugin creates and manages the following tables within osTicket’s MySQL database:

All tables use the fai_ prefix to clearly distinguish them from osTicket’s own tables (which use the ost_ prefix). The plugin does not add columns to existing osTicket tables, does not create triggers on osTicket tables, and does not modify indexes on osTicket tables.

Storage Efficiency

The plugin’s storage footprint is designed to remain bounded and predictable:

• Event queue pruning: Processed events are cleaned up from the fai_event_queue table after successful processing. The queue only holds unprocessed and in-flight events, preventing unbounded table growth.
• Summary overwrites: Only the latest summary version is retained per ticket. When a ticket is updated and a new summary is generated, it replaces the previous summary rather than creating additional rows.

These mechanisms ensure that the plugin’s storage requirements scale with your active ticket volume rather than accumulating indefinitely over time.

Schema Migrations

The plugin manages its database schema through a versioned migration system:

• Version tracking: The current schema version is stored in the fai_schema_version table. Each migration increments this version number.
• Automatic execution: Migrations run automatically when the plugin is activated or updated. Administrators do not need to run manual SQL scripts.
• Non-destructive changes: Migrations only add tables or add columns. They do not drop columns, rename tables, or alter existing data types on previously created columns. This ensures that a failed or interrupted migration does not leave the database in a broken state.
• Forward-only: Migrations are applied sequentially. The plugin checks the current version and applies any migrations with a higher version number.

This approach follows the same pattern used by osTicket itself for its own internal schema updates, ensuring consistency with the platform’s conventions.

Clean Uninstall Guarantee

Removing the Flexivity AI plugin returns osTicket to its original state:

1. Signal handlers are deregistered: The plugin’s event listeners are removed from osTicket’s signal dispatch table. No orphaned callbacks remain.
2. Plugin tables are dropped: All fai_* tables are removed from the database, including the event queue, results tables, and schema version tracker.
3. No core modifications to revert: Because the plugin never modifies osTicket core files or core database tables, there is nothing to patch back.
4. No residual configuration: Plugin settings stored in osTicket’s plugin configuration system are removed along with the plugin entry.

After uninstallation, osTicket operates exactly as it did before the plugin was installed. There are no leftover tables, no orphaned data in core tables, and no modified files on disk.

UI Integration Approach

The AI-generated summaries and recommendations are presented within the osTicket interface on the ticket detail page:

• Placement: The Summary and Recommendation views are injected into the ticket detail page, positioned immediately below the ticket headers and before the thread. This ensures agents see AI context exactly when they need it — while reviewing a ticket.
• Data-dependent visibility: The Summary and Recommendation sections only appear when there is data available for the current ticket. If no summary or recommendation has been generated yet, no empty placeholder UI is shown.
• Collapsible design: Both sections use a collapsible panel design. Agents can expand or collapse them as needed, keeping the interface clean when the AI context is not needed.

Why This Design Is Effective

• Non-intrusive: The plugin does not change any existing osTicket UI elements. It adds new sections without modifying the layout, styling, or behavior of core interface components.
• Follows osTicket patterns: The collapsible panel approach follows osTicket’s existing UI conventions, so agents experience a consistent interface.
• Contextual: AI results appear at the point of need — on the ticket detail page where agents are actively working. There is no need to navigate to a separate dashboard or external tool.

Authentication Mechanism

The plugin uses JWT-based (JSON Web Token) authentication for its write-back REST API endpoints. This ensures that only authorized Flexivity AI connections can submit AI-generated results to osTicket.

Why JWT Over Shared API Keys

osTicket’s built-in API uses simple shared API keys for authentication. The Flexivity AI plugin uses JWTs instead, which provide several security advantages:

• Cryptographically signed: JWTs are signed with asymmetric keys (RSA), making them tamper-proof. Shared API keys are simple bearer tokens that offer no integrity guarantees.
• Expiration and identity claims: Each JWT encodes an expiration time and identity information (organization ID, instance ID). Shared keys have no built-in expiration or identity binding.
• Central revocation: Tokens can be revoked centrally from the Flexivity AI administration console, immediately invalidating all connections using that token.
• Time-bound validity: The expiration claim prevents replay attacks — even if a token is intercepted, it becomes useless after its validity period.

Why These Patterns Are Safe

The integration approach was designed around three principles:

Non-Blocking

Every operation that occurs during osTicket’s request handling cycle completes in constant time (a single MySQL INSERT). No network calls, no external dependencies, no variable-latency operations. osTicket’s performance characteristics remain unchanged.

Standards-Compliant

The plugin uses only osTicket’s documented, public extension points: the signal system, the plugin API, and custom database tables. These are the same mechanisms used by osTicket’s own bundled plugins and by the broader osTicket plugin ecosystem. There are no undocumented API calls, no reflection-based hacks, and no reliance on internal implementation details that could break between releases.

Reversible

The integration is fully reversible at every level. The plugin can be disabled (stops processing, signal handlers detached) or fully uninstalled (all plugin data removed). In either case, osTicket returns to its pre-plugin state with no manual intervention required.

Summary