osTicket Integration Architecture

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 five 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 picks up events from the queue and reads each ticket by its id when the AI needs it, with payment card, government and bank identifiers masked (best effort). The AI reads the rest as written; anything stored is scrubbed of PII first.
4. The Flexivity AI service holds the AI’s work on each ticket — summaries, attributes, matching knowledge, draft replies and the conversation’s state — in the cloud, not in osTicket’s database.
5. The agent panel on the ticket page shows that work. The agent’s browser loads it from the Flexivity AI service, and the plugin’s write-back REST API applies the changes the AI makes to a ticket, such as setting its help topic or posting a reply.

┌─────────────────────────────────────────────────────────────────┐
│                        osTicket Server                          │
│                                                                 │
│  ┌──────────────┐    signal     ┌──────────────────────┐        │
│  │ Ticket Event  │─────────────>│ FAI Signal Handler   │        │
│  │ (create/edit/ │              │ (non-blocking)       │        │
│  │  close)       │              └──────────┬───────────┘        │
│  └──────────────┘                          │                    │
│                                    INSERT row                   │
│                                            v                    │
│  ┌──────────────────────┐     ┌────────────────────┐            │
│  │ FAI Write-back API   │     │  fai_event_queue   │            │
│  │ (topic, fields,      │     │  (MySQL table)     │            │
│  │  notes, replies, FAQ)│     └────────┬───────────┘            │
│  └──────────┬───────────┘              │                        │
│             ^                          │ read events            │
└─────────────┼──────────────────────────┼────────────────────────┘
              │ ticket changes           v
        ┌─────────────────────────────────────┐
        │         Flexivity AI Agent          │
        │  (reads queue, masks, relays)       │
        └─────────────────────────────────────┘
                         │ events, and tickets read by id
                         v
        ┌─────────────────────────────────────┐      ┌───────────────┐
        │      Flexivity AI Cloud Service     │<─────│ Agent panel   │
        │  AI processing, and the AI data for │ HTTPS│ (agent's      │
        │  each ticket: summary, attributes,  │      │  browser, on  │
        │  knowledge, drafts, conversation    │      │  the ticket   │
        │  state                              │      │  page)        │
        └─────────────────────────────────────┘      └───────────────┘

Note: The diagram above shows the agent deployment mode. In direct connection mode, Flexivity AI reads events and calls 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 changes osTicket’s schema, never performs slow operations during request handling, and can be fully removed without leaving any plugin tables or code behind.

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. From plugin 2.8.0 an event carries the ticket’s id and what changed, not its text.
2. Masks payment card, government and bank identifiers in anything it sends (best effort).
3. Sends the event to the Flexivity AI cloud platform for processing.
4. Marks the event as processed in the queue.

When the AI needs a ticket’s text, the cloud asks the agent for it by id, and the agent reads it from the plugin and masks it before it leaves your network (agent 1.4.0 and plugin 2.8.0). With a direct connection, the cloud reads the ticket from the plugin over HTTPS and masks it as it arrives. Either way the AI reads the ticket as written, and anything the cloud stores is scrubbed of PII first.

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

AI Data in the Flexivity AI Service

The AI’s work on a ticket is stored in the Flexivity AI service, not in osTicket’s database: the summary, the ticket’s attribute values and any corrections to them, the matching knowledge articles and related tickets, draft replies, and the state of any conversation the AI is holding with the customer. Like everything else Flexivity AI stores, it is held only in PII-scrubbed form.

Plugin versions before 2.6.0 kept summaries, recommendations and classifications in their own tables inside osTicket. Version 2.6.0 removes those tables when it is installed.

Why This Matters

• One record for every help desk. The same data serves the agent panel, AI Activity in the admin console, billing, and the AI’s next turn in a conversation. There is no copy in osTicket to fall out of step with it.
• New capabilities without a plugin release. The agent panel draws what the service sends it, so a new kind of AI information reaches agents without a plugin upgrade or a schema change.
• Less in your database. osTicket’s MySQL holds the event queue and the plugin’s own state, and nothing else of the AI’s.
• Erasure in one place. Deleting a ticket’s AI data for a right-to-erasure request removes it from the service, along with anything the plugin still holds for that ticket.

The Agent Panel

The agent panel appears on the ticket page in osTicket’s staff interface. The plugin renders an empty container and a short-lived token scoped to that ticket; the agent’s browser then loads the panel’s content over HTTPS from the Flexivity AI service. The plugin itself makes no outbound request while rendering the page, so a slow or unreachable service never delays osTicket.

The token is signed with a secret unique to your installation, identifies one ticket, and expires after five minutes. The service returns data only for the ticket the token names.

Deciding a prepared change (plugin 2.10.0). When an agent approves, edits or rejects a change the AI prepared, such as a refund, the panel asks the plugin, on the agent’s own osTicket session and with osTicket’s CSRF token, whether that agent may decide (assigned to them, or their team, or in their department when nobody is assigned, and allowed to reply). If so, the plugin posts the decision as an internal note in the agent’s name and signs a two-minute voucher, which the service checks before it records the decision. The service never takes an agent’s name from the browser. An address an agent types for a change of shipping address goes from their browser to the Flexivity AI service only; it never passes through the plugin or the agent. See Prepared Changes.

Files on a ticket (plugin 2.10.1). When Flexivity reads a ticket, the plugin includes the type of each file on each message (for example image/jpeg), so a procedure that asks the customer for a photo knows when one was sent. An image pasted into a message counts as a file. The plugin never sends a file’s name or its contents.

Write-Back Mechanism

When the AI acts on a ticket, the change is applied through the plugin’s REST API. Flexivity AI calls it through the agent’s secure tunnel or, in direct connection mode, over HTTPS. Authentication is handled via JWT tokens, so only authorized connections can make changes.

The write-back API makes these changes, and only where your configuration allows them:

• Help topic and field values, for attributes you have set to be written to osTicket.
• Internal notes for your agents.
• Replies to the customer, for tickets at the Reply, Clarify or Resolve level, posted through osTicket’s own reply function.
• The Flexivity field’s “Action pending” value (plugin 2.10.2), set while a prepared change needs an agent and cleared when it is decided, through osTicket’s own forms so custom queues and the ticket’s history see it.
• FAQ articles you push from the Knowledge Builder.

Each of these is ordinary ticket or knowledge-base data in osTicket’s existing tables, the same as a change an agent makes, and it stays part of your helpdesk data if the plugin is removed. The plugin never adds columns, triggers or indexes to osTicket’s tables.

The Flexivity field (plugin 2.10.2; earlier 2.10 releases did not place it on the form) is the one thing the plugin adds to your helpdesk’s configuration: a field named Flexivity on the Ticket Details form, created through osTicket’s own forms (as an administrator adding a field would), visible to staff only and never to customers. It holds “Action pending” (Flexivity’s) and “Test ticket” (yours). It is locked against renaming or deletion so queues and the plugin can rely on it, never offered as a target for attribute mapping, and removed when the plugin is uninstalled.

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.
• No AI data in osTicket: Summaries, attributes, drafts and conversation state are held in the Flexivity AI service, so they add nothing to osTicket’s database however many tickets you process.

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_plugin_state 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 add tables or add columns. They do not rename tables or alter existing data types on previously created columns, so a failed or interrupted migration does not leave the database in a broken state. The one exception is version 6 (plugin 2.6.0), which drops the three tables earlier versions kept AI results in, because nothing reads or writes them any more.
• 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: Uninstalling from Admin Panel > Manage > Plugins removes every fai_* table the plugin created, including the event queue and the schema version tracker. This needs plugin 2.6.0 or later.

   Earlier versions left the tables in place. To remove them after uninstalling an earlier version, run the following against osTicket’s database, replacing ost_ with your table prefix if it differs:

   DROP TABLE IF EXISTS ost_fai_event_queue, ost_fai_plugin_state,
     ost_fai_summaries, ost_fai_recommendations, ost_fai_classifications;

3. No core modifications to revert: The plugin never modifies osTicket core files or osTicket’s schema, so there is nothing to patch back. The Flexivity field the plugin added to the Ticket Details form (plugin 2.10.0) is removed with it; a ticket that had a value keeps that value in its history, as for any field an administrator deletes. Changes the AI made to tickets through the write-back API, such as a help topic or a posted reply, are ordinary helpdesk data and remain.

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 plugin tables and no modified files on disk. The AI data for your tickets is held in the Flexivity AI service and is deleted from there when your account ends.

UI Integration Approach

The AI’s work is presented in the agent panel on the ticket detail page:

• Placement: The panel is injected into the ticket detail page, below the ticket headers and before the thread, so agents see the AI context while reviewing a ticket.
• Three sections: Take Action appears only when the AI needs the agent (a draft reply, an escalated ticket, a conversation in progress). Context shows sentiment, the summary, attributes, matching knowledge and related tickets. The Activity Log records what the AI did.
• Collapsible design: Context and the Activity Log can be expanded or collapsed 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 a panel without modifying the layout, styling, or behavior of core interface components.
• Never blocks the page: The panel loads in the agent’s browser after the page has rendered, so osTicket’s own page load is unaffected by the Flexivity AI service.
• 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 make changes in osTicket. The agent panel uses its own short-lived, ticket-scoped token, described under The Agent Panel.

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, the ticket page’s extension point, 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