toga-ai 1.0.314 → 1.0.315

package/knowledge/1.0/apps/library/features/elite-freshservice-sync.md

@@ -6,7 +6,7 @@ project: Library
 client: elite
 type: client-feature
 status: active
-updated: 2026-06-15
+updated: 2026-07-10
 owners: ["snaredla"]
 files:
   - library/app/api/toga2.php
@@ -165,5 +165,49 @@ Pass `true` for the dedup GET — errors must not silently empty the dedup array
 Each ticket sync is wrapped in `try/catch` — exceptions are sent to Sentry and the run
 continues with the next ticket. A single bad ticket does not abort the whole sync.
 
+## Elite-specific sync behaviour
+
+### Department assignment (TOGaDesk → TOGA 2)
+Elite tickets use `c_togadeskDepartmentId` on `Client_Elite.TicketTeams` to reverse-lookup the correct Toga2 team from TOGaDesk's actual `departmentid`. CF84 (custom field storing team name) is **never** updated when an agent manually transfers a ticket between TOGaDesk departments via the UI — so it cannot be used as the sync source for team.
+
+Lookup in `syncTogaDesk1TicketIntoToga2Ticket`:
+```php
+$eliteTeamLookupOptions = [
+    'where' => ['and' => [['c_togadeskDepartmentId' => ['=' => (int) $togadeskTicket->departmentid]]]]
+];
+$eliteTeamResult = App_Api_Toga2::send(..., 'GET', '/ticket-teams', null, $eliteTeamLookupOptions, ...);
+if ($eliteTeamResult->meta->totalRecordCount == 1) {
+    $payload['ticketTeam'] = ['uuid' => $eliteTeamResult->data->ticketTeams[0]->uuid];
+}
+```
+
+**Pending DB migration** — `c_togadeskDepartmentId INT NULL` must be added to `Client_Elite.TicketTeams` with team→dept mappings before this lookup works.
+
+### Timestamp guard (prevents overwriting Freshservice changes)
+Before pushing any field update (priority, status, category, group, type) to Freshservice, the sync compares timestamps:
+```php
+$eliteOriginalUpdatedAt = ... strtotime($eliteTicket->updated_at) ...;  // captured BEFORE reply POSTs
+$togadeskUpdatedAt = strtotime($togadeskLastModified);
+$togadeskUpdateIsMoreRecent = ($togadeskUpdatedAt > $eliteOriginalUpdatedAt);
+```
+Nothing is written to Freshservice unless TOGaDesk is strictly newer. Safe to reset `TOGA_LAST_TICKET_INTEGRATION_DATETIME` for re-sync — Freshservice changes are protected.
+
+### Reply status badge mapping
+`tickets_replies.newStatus` is set from `$ticketNote->ticketStage->code` when a reply is synced in. Elite code → TOGaDesk status:
+
+| Freshservice code | TOGaDesk status |
+|---|---|
+| 2 | Open |
+| 3 | Awaiting User |
+| 6 | In Progress |
+| 4 | Resolved |
+| 5 | Closed |
+
+**Gotcha:** `case 2` was previously mapped to `STATUS__NEW_TICKET` (wrong) — fixed 2026-07-10. Replies from Freshservice with status "Open" were showing "New Ticket" badge in TOGaDesk.
+
+### Variable name pollution gotcha
+The Elite team lookup block inside `syncTogaDesk1TicketIntoToga2Ticket` must use its own dedicated options variable (`$eliteTeamLookupOptions`) — never reuse `$method`, `$route`, `$payload`, or `$options`. Those shared variables are consumed by the `send()` call immediately after the block. Reusing them causes the wrong endpoint to be called, resulting in a Sentry crash: `Undefined property: stdClass::$tickets`.
+
 ## Change history
 - 2026-06-10 — Documented `App_Api_Toga2::syncWithTogadesk` orchestration (bidirectional TOGA 2 ↔ TOGaDesk ticket/note/file sync, watermarks, `ticketNoteFiles` gotcha). (snaredla)
+- 2026-07-10 — Added Elite-specific section: department reverse-lookup via `c_togadeskDepartmentId`, timestamp guard, reply status badge mapping fix (`case 2` → Open), variable pollution gotcha. (snaredla)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.314",
+  "version": "1.0.315",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",