Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 15 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

## [Unreleased]

## [0.1.1] - 2026-11-08

### Added

- **Closing statuses that never ask** (setting "Never ask for → Closing statuses"). Preselected: closed statuses named like "Duplicate", "Spam", "Rejected" or "Hinfällig". Closing with such a status leaves no trace; a later close with another status still asks.
- **Note at the ticket when asked** (own mail mode): short (recipient, scale, valid until; default), short plus the mail as sent with its rating links, or none.
- **Note on a failed send**, always: the question couldn't be sent and isn't retried.

### Documentation

- INSTALL: after creating the instance, open it again and check the checkboxes. osTicket 1.18 doesn't store checkbox defaults on the first save.
- INSTALL: new settings apply their built-in default until the instance is saved once.

## [0.1.0] - 2026-11-03

### Added
Expand All @@ -22,5 +35,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Retention: rows are deleted after 24 months; the IP is stored only as a keyed hash.
- Mail in the style of a brand line over an accent rule, buttons as table cells, a grey footer with an AI notice; texts editable, German (informal) and English built in.

[Unreleased]: https://github.com/studio-prisma/osticket-plugin-feedback/compare/v0.1.0...HEAD
[Unreleased]: https://github.com/studio-prisma/osticket-plugin-feedback/compare/v0.1.1...HEAD
[0.1.1]: https://github.com/studio-prisma/osticket-plugin-feedback/compare/v0.1.0...v0.1.1
[0.1.0]: https://github.com/studio-prisma/osticket-plugin-feedback/releases/tag/v0.1.0
6 changes: 5 additions & 1 deletion README.de.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@ Die Bewertungen bleiben in der Datenbank des Helpdesks. Kein Umfragedienst, kein
- Tickets, die ein KI-Agent schließt (Agenten mit dem Backend `ai-agent`, wie [AI Actions](https://github.com/studio-prisma/osticket-plugin-ai-actions) sie anlegt), auch wenn das im Cron passiert
- Unter-Tickets
- Abteilungen, Hilfethemen und Absender-Domains aus den Einstellungen; standardmäßig die eigenen Domains des Helpdesks
- Schließen mit einem Status wie „Dublette“ oder „Spam“ (Einstellung, nach Namen vorausgewählt)
- Tickets, zu denen schon gefragt wurde

## Voraussetzungen
Expand All @@ -47,7 +48,8 @@ Schritt für Schritt mit Prüfpunkten: **[docs/INSTALL.de.md](docs/INSTALL.de.md
| Bad means | Sterne bis … / NPS bis … | 2 / 6 |
| Link valid for | Tage (1–90) | 14 |
| Comment field after the click | an / aus | an |
| Never ask for | Abteilungen, Hilfethemen, Absender-Domains, eigene Domains | Abteilungen mit „Alert“/„Protokoll“ im Namen, eigene Domains |
| Note at the ticket when asked | keine / kurz / mit der gesendeten Mail | kurz; ein gescheiterter Versand bekommt immer eine Notiz |
| Never ask for | Abteilungen, Hilfethemen, Status beim Schließen, Absender-Domains, eigene Domains | Abteilungen mit „Alert“/„Protokoll“ im Namen, Status mit „Duplicate“/„Spam“/„Hinfällig“ im Namen, eigene Domains |
| Texte | Betreff, Mailtext, Frage, Zeile, KI-Hinweis; leer = eingebauter Text | eingebaut, Deutsch (du) oder Englisch |
| Accent colour | `#rrggbb` | `#330066` |

Expand All @@ -66,6 +68,8 @@ Die Mailtexte verstehen osTicket-Variablen wie `%{ticket.number}` und `%{recipie
- **Spitze Klammern in Kommentaren** erscheinen in der Notiz als ‹ ›, weil der Sanitizer von osTicket alles entfernt, was wie ein Tag aussieht.
- **Modus „Zeile“** braucht eine Antwort, die den Status auf geschlossen setzt. Schließen ohne Antwort fragt in diesem Modus niemanden, und eine Antwort mit „Antworten an: niemand“ trägt keine Zeile und zählt nicht als gefragt.
- **Safe Links mit JavaScript:** Ein Scanner, der das JavaScript der Seite in einer Sandbox ausführt, würde die Bewertung abschicken. Bisher nicht beobachtet; im echten Microsoft-365-Tenant zu prüfen.
- **Häkchen-Standardwerte bei einer neuen Instanz:** osTicket 1.18 speichert sie beim ersten Speichern nicht. Nach dem Anlegen die Instanz noch einmal öffnen und die Häkchen prüfen (siehe INSTALL, Schritt 2).
- **Notiz „mit der Mail“** legt die Bewertungslinks des Kunden ans Ticket. Jeder Agent, der das Ticket öffnen darf, kann ihnen folgen; das ist der Preis dafür, genau zu sehen, was rausging.
- **Nur eine Frage,** keine Erinnerungen, kein Export, keine Bewertung einzelner Agenten. Das ist bewusst außerhalb des Umfangs.
- **Wochenzusammenfassung von AI Actions:** Das Plugin beantwortet das Signal `feedback.digest` mit einer Zeile. AI Actions schickt es noch nicht.

Expand Down
6 changes: 5 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@ Ratings stay in the help desk's own database. No survey service, no tracking pix
- tickets an AI agent closes (agents with the backend `ai-agent`, as [AI Actions](https://github.com/studio-prisma/osticket-plugin-ai-actions) creates them), including closes it makes in osTicket's cron
- sub-tickets
- departments, help topics and sender domains from the settings; the help desk's own domains by default
- closes with a status like "Duplicate" or "Spam" (setting, preselected by name)
- tickets that were already asked

## Requirements
Expand All @@ -47,7 +48,8 @@ Step by step with checkpoints: **[docs/INSTALL.md](docs/INSTALL.md)**. Short ver
| Bad means | stars up to … / NPS up to … | 2 / 6 |
| Link valid for | days (1–90) | 14 |
| Comment field after the click | on / off | on |
| Never ask for | departments, help topics, sender domains, own domains | departments named like "Alert"/"Protokoll", own domains |
| Note at the ticket when asked | none / short / with the mail as sent | short; a failed send always gets a note |
| Never ask for | departments, help topics, closing statuses, sender domains, own domains | departments named like "Alert"/"Protokoll", statuses named like "Duplicate"/"Spam"/"Hinfällig", own domains |
| Texts | subject, mail text, question, line, AI notice; empty = built-in text | built-in, German (informal) or English |
| Accent colour | `#rrggbb` | `#330066` |

Expand All @@ -66,6 +68,8 @@ The mail texts accept osTicket variables such as `%{ticket.number}` and `%{recip
- **Angle brackets in comments** appear as ‹ › in the note, because osTicket's sanitizer strips anything that looks like a tag.
- **"Line" mode** needs a reply that sets the closed status. Closing without a reply asks nobody in that mode, and a reply posted with "Reply to: none" carries no line and doesn't count as asked.
- **Safe Links with JavaScript:** a scanner that runs the page's JavaScript in a sandbox would submit the rating. Not observed so far; to be checked against a real Microsoft 365 tenant.
- **Checkbox defaults on a new instance:** osTicket 1.18 doesn't store them on the first save. Open the instance again after creating it and check the boxes (see INSTALL, step 2).
- **"With the mail" note** puts the customer's rating links into the ticket. Any agent who can open the ticket can follow them; that is a trade-off for seeing exactly what went out.
- **Only one question,** no reminders, no export, no per-agent rating. These are out of scope on purpose.
- **AI Actions weekly summary:** the plugin answers the signal `feedback.digest` with one line. AI Actions doesn't send it yet.

Expand Down
1 change: 1 addition & 0 deletions SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,7 @@ Expected response: an acknowledgement within 7 days, an assessment within 30. Th
These are documented design decisions, not findings:

- **Anyone who has the mail can rate.** The link is the authorisation, like a password-reset link. A forwarded mail lets the recipient rate and change the rating while it's valid.
- **Agents with the "with the mail" note can rate.** That setting copies the sent mail, links included, into an internal note. Every agent who can open the ticket can follow them. The default note has no links.
- **A link scanner that runs JavaScript** submits the rating like a person would. The confirmation step stops scanners that only fetch the page; one that executes the page in a sandbox is indistinguishable from a click.
- **Rate limit per IP** counts all customers behind one NAT together (60 requests per 10 minutes, about 20 ratings).
- **No revocation of single links** other than switching the plugin off (all links) or deleting the row in `<prefix>feedback_request`.
Expand Down
5 changes: 3 additions & 2 deletions class.FeedbackPlugin.php
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@
class FeedbackPlugin extends Plugin
{
/** Mirrors plugin.php. */
public const VERSION = '0.1.0';
public const VERSION = '0.1.1';

/** Route bases, relative to the help desk root. */
public const CLIENT_BASE = 'ajax.php/feedback';
Expand Down Expand Up @@ -74,7 +74,8 @@ public function bootstrap(): void
}
$raw = array();
foreach (array('enabled', 'mode', 'scale', 'on_bad', 'bad_stars', 'bad_nps', 'valid_days', 'exclude_depts',
'exclude_topics', 'exclude_domains', 'exclude_own', 'comment_on', 'language', 'subject', 'text',
'exclude_topics', 'exclude_statuses', 'exclude_domains', 'exclude_own', 'comment_on', 'note_sent',
'language', 'subject', 'text',
'question', 'line', 'foot_on', 'foot', 'accent') as $k) {
$raw[$k] = $config->get($k);
}
Expand Down
43 changes: 43 additions & 0 deletions config.php
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,18 @@ public function getOptions()
),
)),

'note_sent' => new ChoiceField(array(
'label' => 'Note at the ticket when asked',
'default' => 'short',
'choices' => array(
'off' => 'No note',
'short' => 'Short note: recipient, scale, valid until',
'full' => 'Short note plus the mail as sent, with its rating links',
),
'hint' => 'Own mail only. A failed send always gets a note. With the mail, every agent who '
. 'opens the ticket sees the customer\'s rating links.',
)),

'sec_except' => new SectionBreakField(array(
'label' => 'Never ask for',
)),
Expand All @@ -108,6 +120,15 @@ public function getOptions()
'configuration' => array('multiselect' => true, 'prompt' => 'None'),
)),

'exclude_statuses' => new ChoiceField(array(
'label' => 'Closing statuses',
'default' => self::defaultStatuses(),
'choices' => self::closedStatuses(),
'hint' => 'Closing with one of these never asks, e.g. duplicates or spam. Preselected: closed '
. 'statuses named like "Duplicate", "Spam", "Rejected" or "Hinfällig".',
'configuration' => array('multiselect' => true, 'prompt' => 'None'),
)),

'exclude_domains' => new TextareaField(array(
'label' => 'Sender domains',
'default' => '',
Expand Down Expand Up @@ -208,6 +229,28 @@ private static function topics(): array
return $out;
}

/** Statuses whose state is "closed". @return array<int,string> */
private static function closedStatuses(): array
{
$out = array();
if (!function_exists('db_query') || !defined('TICKET_STATUS_TABLE')) {
return $out;
}
$res = db_query(sprintf("SELECT id, name FROM %s WHERE state='closed' ORDER BY sort, name", TICKET_STATUS_TABLE));
while ($res && ($r = db_fetch_row($res))) {
$out[(int) $r[0]] = (string) $r[1];
}
return $out;
}

/** Closing statuses that mean "nothing was done", by name. @return array<int,string> */
private static function defaultStatuses(): array
{
return array_filter(self::closedStatuses(), static function (string $name): bool {
return preg_match('/duplicate|dublette|spam|reject|abgelehnt|hinf(ä|ae)llig|obsolete|invalid/iu', $name) === 1;
});
}

/** Departments for alerts and logs, by name. @return array<int,string> */
private static function defaultDepts(): array
{
Expand Down
12 changes: 8 additions & 4 deletions docs/INSTALL.de.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,9 +48,12 @@ Prüfung: `include/plugins/feedback/` enthält `plugin.php`, `config.php`, `clas
3. Reiter „Instanzen“ → „Neue Instanz hinzufügen“, Name z. B. `Feedback`, Haken bei „Aktiv“.
4. In der Instanz die Einstellungen durchgehen. **„Ask customers“ bleibt aus.**
- „Never ask for → Departments“: Abteilungen für Alerts, Monitoring, Protokolle. Vorausgewählt sind Abteilungen mit „Alert“, „Protokoll“ oder „Monitoring“ im Namen.
- „Closing statuses“: Schließen mit einem dieser Status fragt nie, z. B. „Dublette“ oder „Spam“. Vorausgewählt sind geschlossene Status mit „Duplicate“, „Spam“, „Rejected“ oder „Hinfällig“ im Namen.
- „Help topics“ und „Sender domains“ nach Bedarf, z. B. Domains von Partnern, die nicht gefragt werden sollen.
- „Note at the ticket when asked“: kurz (Standard), mit der gesendeten Mail oder keine. Mit der Mail sieht jeder Agent, der das Ticket öffnet, die Bewertungslinks des Kunden.
- Texte leer lassen für den eingebauten Text (Du-Form). „Language of the built-in texts“ auf „Deutsch (du)“, wenn das Helpdesk nicht auf Deutsch steht.
5. Speichern.
6. **Instanz noch einmal öffnen und die Häkchen prüfen.** osTicket 1.18 speichert beim Anlegen einer Instanz die Standardwerte von Häkchen nicht: Nach dem ersten Speichern können „Comment field after the click“, „Own domains“ und „Footer with AI notice“ aus sein, obwohl sie standardmäßig an sind. Gewünschte Häkchen wieder setzen, Speichern, erneut öffnen und prüfen, dass sie bleiben.

Prüfung: Agentenpanel → Anwendungen → „Feedback“ öffnet die Auswertung mit „Status: aus“ und ohne rote Meldung.

Expand All @@ -74,10 +77,11 @@ Prüfung: beides gesetzt. Ohne Schritt 2 wird das Ticket trotzdem geöffnet und
1. „Ask customers“ an, Speichern.
2. Testticket mit der Testadresse aus Schritt 0 anlegen, als Agent darauf antworten, Ticket schließen.
3. In der Testadresse liegt eine Mail „Kurze Frage zu deinem Ticket [Nummer]“ mit 👍/👎.
4. 👍 klicken: Seite „Danke!“, am Ticket die interne Notiz „Kundenbewertung · Bewertung: Daumen hoch (zufrieden)“. Das Ticket bleibt zu.
5. Zweites Testticket, gleicher Ablauf, 👎 klicken, Kommentar schreiben, „Kommentar senden“: Das Ticket ist offen, dem Agenten zugewiesen, der geantwortet hat, und er hat eine Zuweisungsmail mit Bewertung und Kommentar.
4. Am Ticket: interne Notiz „Zufriedenheitsfrage“ mit Empfänger und Gültigkeit. Steht dort „konnte nicht gesendet werden“, ist der Mailversand von osTicket gescheitert (Systemprotokoll; bei OAuth das Token des ausgehenden Kontos prüfen).
5. 👍 klicken: Seite „Danke!“, am Ticket die interne Notiz „Kundenbewertung · Bewertung: Daumen hoch (zufrieden)“. Das Ticket bleibt zu.
6. Zweites Testticket, gleicher Ablauf, 👎 klicken, Kommentar schreiben, „Kommentar senden“: Das Ticket ist offen, dem Agenten zugewiesen, der geantwortet hat, und er hat eine Zuweisungsmail mit Bewertung und Kommentar.

Abbruch, wenn: bei Schritt 3 keine Mail kommt. Dann zuerst prüfen: Ist die Kundenadresse eine eigene Domain? Hat ein Agent geantwortet (keine KI)? Ist die Abteilung ausgenommen? Steht im Systemprotokoll ein Eintrag „Feedback plugin“?
Abbruch, wenn: bei Schritt 3 keine Mail kommt. Dann zuerst prüfen: Steht am Ticket eine Notiz „Zufriedenheitsfrage“ (siehe Schritt 4)? Ist die Kundenadresse eine eigene Domain? Hat ein Agent geantwortet (keine KI)? Ist die Abteilung oder der Status beim Schließen ausgenommen? Steht im Systemprotokoll ein Eintrag „Feedback plugin“?

---

Expand Down Expand Up @@ -107,5 +111,5 @@ Gespeichert werden Ticket-ID, Bewertung, Kommentar, Zeit und ein Hash der IP-Adr

## 7. Update und Entfernen

- **Update:** neuen Ordner über den alten entpacken. Die Tabellen bleiben, Einstellungen auch.
- **Update:** neuen Ordner über den alten entpacken. Die Tabellen bleiben, Einstellungen auch. Neue Einstellungen gelten mit ihrem eingebauten Standard, bis die Instanz einmal gespeichert ist: Instanz öffnen, neue Felder prüfen, Speichern.
- **Entfernen:** Instanz löschen, Plugin deinstallieren, Ordner löschen. Die Tabellen `<prefix>feedback_request` und `<prefix>feedback_hit` bleiben in der Datenbank, bis du sie selbst löschst (`DROP TABLE`). Die Notizen an den Tickets bleiben.
12 changes: 8 additions & 4 deletions docs/INSTALL.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,9 +48,12 @@ Check: `include/plugins/feedback/` holds `plugin.php`, `config.php`, `class.Feed
3. Tab "Instances" → "Add New Instance", name e.g. `Feedback`, tick "Active".
4. Go through the instance settings. **"Ask customers" stays off.**
- "Never ask for → Departments": departments for alerts, monitoring, logs. Preselected are departments with "Alert", "Protokoll" or "Monitoring" in their name.
- "Closing statuses": closing with one of these never asks, e.g. "Duplicate" or "Spam". Preselected are closed statuses with "Duplicate", "Spam", "Rejected" or "Hinfällig" in their name.
- "Help topics" and "Sender domains" as needed, e.g. partner domains that shouldn't be asked.
- "Note at the ticket when asked": short (default), with the mail as sent, or none. With the mail, every agent who opens the ticket sees the customer's rating links.
- Leave the texts empty for the built-in text. "Language of the built-in texts" decides between German (informal "du") and English; "Help desk language" follows the system language.
5. Save.
6. **Open the instance again and check the checkboxes.** osTicket 1.18 doesn't store checkbox defaults when an instance is created: after the first save "Comment field after the click", "Own domains" and "Footer with AI notice" can be off although they are on by default. Tick them again where wanted, Save, open once more and check they stay ticked.

Check: agent panel → Applications → "Feedback" opens the evaluation with "State: off" and no red message.

Expand All @@ -74,10 +77,11 @@ Check: both set. Without step 2 the ticket is still reopened and assigned, only
1. "Ask customers" on, Save.
2. Create a test ticket with the test address from step 0, reply as an agent, close the ticket.
3. The test mailbox has a mail "A quick question about your ticket [number]" (German: "Kurze Frage zu deinem Ticket") with 👍/👎.
4. Click 👍: page "Thank you!", at the ticket the internal note "Customer rating · Rating: thumbs up (satisfied)". The ticket stays closed.
5. Second test ticket, same steps, click 👎, write a comment, "Send comment": the ticket is open, assigned to the agent who replied, and that agent has an assignment alert with rating and comment.
4. At the ticket: internal note "Satisfaction question" with recipient and validity. "Could not be sent" there means osTicket's outgoing mail failed (system log; with OAuth check the token of the outgoing account).
5. Click 👍: page "Thank you!", at the ticket the internal note "Customer rating · Rating: thumbs up (satisfied)". The ticket stays closed.
6. Second test ticket, same steps, click 👎, write a comment, "Send comment": the ticket is open, assigned to the agent who replied, and that agent has an assignment alert with rating and comment.

Stop if: no mail arrives in step 3. Check first: is the customer address an own domain? Did a human agent reply (not an AI agent)? Is the department excluded? Is there a "Feedback plugin" entry in the system log?
Stop if: no mail arrives in step 3. Check first: is there a note "Satisfaction question" at the ticket (see step 4)? Is the customer address an own domain? Did a human agent reply (not an AI agent)? Is the department or the closing status excluded? Is there a "Feedback plugin" entry in the system log?

---

Expand Down Expand Up @@ -107,5 +111,5 @@ Stored: ticket ID, rating, comment, time and a hash of the IP address (for the r

## 7. Update and removal

- **Update:** unzip the new folder over the old one. Tables and settings stay.
- **Update:** unzip the new folder over the old one. Tables and settings stay. New settings apply their built-in default until the instance is saved once: open the instance, check the new fields, Save.
- **Removal:** delete the instance, uninstall the plugin, delete the folder. The tables `<prefix>feedback_request` and `<prefix>feedback_hit` stay in the database until you drop them yourself. The notes at the tickets stay.
Loading
Loading