Help Desk: osTicket

This page covers an osTicket instance: creating it, and everything on its Help Desk page. For the Help Desk list and instance statuses, see Help Desk.

Creating a new instance

1. Open Help Desk and click Add Instance. You can also start from the setup card on your dashboard.

2. In Register Instance, name the help desk (for example, “IT Support Desk”) and choose how Flexivity reaches it:

   • Shared Hosting (cloud-managed): a direct connection to an internet-accessible osTicket.
   • Self-Hosted (on-premise agent): a Docker agent alongside an osTicket behind a firewall.

   On your first instance you also choose the ticketing system. After that it is fixed for the account; see One ticketing system per account.

3. Install the plugin and connect, as the wizard’s next two steps describe.

The instance shows as Pending until it connects. See Connecting osTicket for each step.

Each osTicket instance is also one brand, created when you connect it and named after it. It is the brand you choose on AI Configuration and the Knowledge Builder.

The instance page

The top of the page reports the connection’s state. Below it is one list of cards, each something you set.

Agent Health (self-hosted)

• Status: whether the agent is connected

• Version: the agent version running, with Update Agent when a newer one is available

• Last Heartbeat: when the agent last checked in, roughly every minute while it is connected

• Update Channel: how the agent receives updates:

  • Stable (default): updates after they have been tested. Recommended for production.
  • Latest: updates as soon as they are published. Useful for a test environment.
  • Pinned: stays on the version you choose and does not update itself.

  A change takes effect at the agent’s next update check, usually within a few minutes.

Connection Health (direct connection)

• Status: whether Flexivity can reach the plugin
• Last Heartbeat: when Flexivity last reached it

Plugin Info

The plugin version installed, and the osTicket version it reports. Empty until Flexivity has reached the plugin for the first time.

Instance Setup

• Edit Setup reopens the setup wizard: change how Flexivity reaches this help desk, see the plugin’s values again, download the plugin, or download a fresh docker-compose.yml for the agent.
• Deactivate Instance stops all processing and sets the instance to Suspended. Reactivate Instance turns it back on.
• Delete Instance, offered once an instance is deactivated, removes it permanently, with its sync jobs, connection and indexes.

Rotating the plugin’s keys

Rotate a key if you think it has leaked, or on a routine schedule. Both are in Edit Setup, on the Install osTicket Plugin step:

• Verification Key: click Rotate Key next to it, then paste the new key into the plugin’s Verification Key (RSA Public Key) field in osTicket and save. Until you do, the plugin refuses Flexivity’s requests and the instance reports an error.
• KB Search API Key: click Rotate Key under KB AI Search Widget. The old key stops working at once, so paste the new one into the plugin’s KB Search API Key field straight away.

Classification / Attributes

Configure opens the page that decides what the AI records about each ticket, grouped by who provides the attribute:

• Mapped attributes: your own osTicket fields, such as the help topic, up to 5. Each one either reads the field, so your team’s value is used as it is, or is decided by the AI and can be written to it. Writing is off until you switch it on for the attribute. Even then a value is written only when the AI is sure enough: by its own confidence against a threshold, or by agreement with similar tickets your team labelled by hand.
• Flexivity attributes: your own attributes, kept only in Flexivity and never written to osTicket, up to 10. New attribute adds one. The AI decides each from the descriptions of its values, so write them the way you would explain the value to a new agent.
• System attributes: built into Flexivity and not counted against either limit. Some are decided by the AI, like Sentiment; others are worked out from the ticket, like Agent has replied, which records whether someone on your team has already answered. Each is switched on or off with the tick box on its row.

When an agent changes a value the AI chose, the agent’s value wins, and the change is recorded so you can see how often the AI was corrected.

Rules on AI Configuration act on these attributes.

KB AI Search

A search box on your public osTicket pages, where customers ask a question in their own words and get an answer from your published FAQ articles, with links to them. It is off unless you switch it on, because it answers anyone who can reach it.

1. Sync your FAQ articles first, from the osTicket Knowledge Base card on Knowledge Sources. The search answers only from articles that are published and synced.
2. Switch KB AI Search on in its card, and enable the widget in the plugin’s settings in osTicket.
3. Click Configure to open KB AI Search Settings:
   • Response Style: Standard, Concise or Friendly Customer Service, for the tone and length of answers.
   • Temperature: lower gives more focused, consistent answers; higher gives more varied ones.
   • Similarity Threshold: how closely an article must match the question to be used. Higher uses fewer, closer matches.

The widget’s colour and welcome message are set in the plugin, in osTicket.

Ticket History

Your resolved and closed tickets, indexed so the AI can find similar cases and how they were resolved, and so the Knowledge Builder has your history to work from. The card shows the index size. Its Sync button opens the Historical Ticket Database page. See Syncing ticket history.

Knowledge Base

Your published FAQ articles, indexed so the AI can answer from them. They are managed on Knowledge Sources, not on this page: its osTicket Knowledge Base card shows the index size, and its Sync button runs the first sync, after which changes to published articles are picked up as they happen.

Syncing ticket history

Run the first sync once the instance is Active. On the Historical Ticket Database page:

1. Under Start a New Sync, choose how far back to go in Sync tickets from the last: 3, 6 or 12 months, as far as your plan allows. The choice is saved as soon as you make it.
2. Optionally, narrow the sync to tickets resolved since a date.
3. Click Start Sync.

A progress card shows how many tickets are done and an estimated finish, with a button to cancel. The sync runs in the background and does not slow osTicket down, and new tickets keep being processed while it runs. A large archive takes a while: roughly 1–2 hours for 10,000 tickets, 4–8 hours for 50,000, and 12 hours or more beyond 100,000. Tickets already indexed are skipped, so running a sync again only adds what is new.

Past Sync Jobs lists earlier runs and their status: Completed, Failed, Canceled, or Interrupted, which you can Resume from where it stopped.

When an instance is not Active

• Disconnected, self-hosted: the agent has stopped checking in. Common causes are a stopped or restarted container, a network interruption, or the server going offline. The agent reconnects by itself once the cause is fixed; if it stays disconnected, check the agent container’s logs.
• Disconnected, direct connection: Flexivity can no longer reach the plugin. Check that osTicket is reachable over HTTPS and that the plugin is still active.
• Error: usually revoked or expired plugin credentials, or a plugin version the cloud no longer supports. The instance page names the problem.

See Troubleshooting: osTicket.