# Backupchecks – Autotask Integration ## Phase 2 – Implementation Design *Document type: Implementation design* *Scope: Phase 2 only* --- ## 1. Purpose This document describes the **technical implementation approach** for Phase 2 of the Autotask integration. Phase 2 focuses on **ticket state synchronisation and operator-driven resolution**, based on the approved functional design. No future concepts or post–Phase 2 ideas are included in this document. --- ## 2. Preconditions Phase 2 assumes: - Phase 1 is fully implemented and deployed - Autotask integration can be enabled and disabled at runtime - Tickets are already linked to runs via Autotask Ticket ID - Backupchecks is not the authoritative system for ticket state --- ## 3. High-level Behaviour Overview Phase 2 is implemented in **controlled sub-phases**. Each phase introduces a limited set of actions and ends with an explicit **functional validation moment** before continuing. The sub-phases are: - Phase 2.1 – Read-only ticket polling - Phase 2.2 – PSA-driven resolution handling - Phase 2.3 – Deleted ticket detection - Phase 2.4 – Manual ticket resolution from Backupchecks --- ## 4. Phase 2.1 – Read-only Ticket Polling ### 4.1 Scope This phase introduces **read-only polling** of Autotask ticket state. No mutations or resolution logic is applied. ### 4.2 Trigger point Polling is triggered when: - Autotask integration is enabled - The **Run Checks** page is opened There is no background scheduler or periodic task. ### 4.3 Polling scope Only tickets that meet **all** of the following criteria are included: - Ticket is linked to a run visible on the Run Checks page - Run is not already resolved in Backupchecks - Ticket is not marked as deleted or invalid ### 4.4 Autotask query strategy - Query only **active tickets** in Autotask - Ticket ID is always used as the lookup key ### 4.5 Control moment – Phase 2.1 Functional validation: - Run Checks page loads without delay - Correct tickets are polled - No state changes occur in Backupchecks - No Autotask data is modified --- ### 4.2 Polling scope Only tickets that meet **all** of the following criteria are included: - Ticket is linked to a run visible on the Run Checks page - Run is not already resolved in Backupchecks - Ticket is not marked as deleted or invalid This guarantees: - Minimal API usage - Operator-context-only data retrieval --- ### 4.3 Autotask query strategy - Query only **active tickets** in Autotask - Completed / closed tickets are excluded from the active query - Ticket ID is always used as the lookup key If an expected ticket is not returned: - A follow-up single-ticket lookup is executed - If still not found, the ticket is treated as **deleted in PSA** --- ## 5. Phase 2.2 – PSA-driven Resolution Handling ### 5.1 Scope This phase adds **state interpretation** on top of read-only polling. ### 5.2 Completed ticket handling If Autotask reports the ticket status as **Completed**: - Mark the linked run as **Resolved** - Set resolution origin to: - `Resolved by PSA` - Store resolution timestamp No write-back to Autotask is performed. ### 5.3 Active ticket handling If the ticket exists and is active: - Update cached ticket status snapshot only - No state change in Backupchecks ### 5.4 Control moment – Phase 2.2 Functional validation: - PSA-completed tickets resolve runs correctly - Resolution origin is shown correctly - Active tickets do not alter run state --- ### 5.2 Completed ticket If Autotask reports the ticket status as **Completed**: - Mark the linked run as **Resolved** - Set resolution origin to: - `Resolved by PSA` - Store resolution timestamp No write-back to Autotask is performed. --- ### 5.3 Deleted or missing ticket If the ticket cannot be found in Autotask: - Mark ticket linkage as: - `Deleted in PSA` - Block ticket-related actions - Preserve historical references (ID, number, URL) Operator must explicitly link or create a replacement ticket. --- ## 6. Phase 2.3 – Deleted Ticket Detection ### 6.1 Scope This phase introduces detection of tickets that are removed from Autotask. ### 6.2 Detection logic If a linked ticket is not returned by the active-ticket query: - Execute a single-ticket lookup - If still not found: - Mark ticket linkage as `Deleted in PSA` ### 6.3 Behaviour - Ticket actions are blocked - Historical references remain visible - Operator must explicitly relink or recreate a ticket ### 6.4 Control moment – Phase 2.3 Functional validation: - Deleted tickets are detected reliably - Warning is visible in UI - No silent unlinking occurs --- ## 7. Phase 2.4 – Manual Ticket Resolution (Backupchecks → Autotask) ### 7.1 Preconditions The Resolve action is available only if: - Autotask integration is enabled - A valid Autotask Ticket ID exists - Ticket is not already closed in PSA ### 7.2 Resolution flow 1. Operator triggers **Resolve ticket** 2. Backupchecks retrieves ticket details from Autotask 3. Time entry check is executed #### Case A – No time entries - Ticket is set to completed in Autotask - Run is marked as **Resolved** - Resolution origin: - `Resolved by Backupchecks` #### Case B – Time entries exist - Ticket is not closed - Fixed-format internal system note is added - Run remains unresolved ### 7.3 Control moment – Phase 2.4 Functional validation: - Resolution works only under defined rules - Time entry logic is respected - Resolution origin is persisted correctly --- ### 6.2 Resolution flow 1. Operator triggers **Resolve ticket** 2. Backupchecks retrieves ticket details from Autotask 3. Time entry check is executed #### Case A – No time entries - Ticket is set to the configured completed status in Autotask - Run is marked as **Resolved** - Resolution origin: - `Resolved by Backupchecks` #### Case B – Time entries exist - Ticket is not closed - A fixed-format internal system note is added - Run remains unresolved --- ### 6.3 Post-resolution sync alignment If a ticket resolved by Backupchecks is later polled as Completed: - Backupchecks keeps the existing resolved state - Resolution origin remains: - `Resolved by Backupchecks` If Autotask resolves the ticket first: - Backupchecks sets: - `Resolved by PSA` --- ## 7. Data Model Adjustments Phase 2 requires the following additional fields per run: - `ticket_last_polled_at` - `ticket_resolution_origin`: - `psa` - `backupchecks` - `ticket_deleted_in_psa` (boolean) Existing Phase 1 fields remain unchanged. --- ## 8. UI Behaviour ### 8.1 Run Checks - Visual indicator for linked tickets - Resolution origin badge: - Resolved by PSA - Resolved by Backupchecks - Warning banner for deleted tickets --- ### 8.2 Job Details - Same indicators as Run Checks - Resolve action visibility follows resolution rules --- ## 9. Error Handling & Logging - All Autotask API calls are logged with: - Correlation ID - Ticket ID - Run ID - Polling failures do not block page rendering - Partial polling failures are tolerated per ticket --- ## 10. Explicit Non-Implementation (Phase 2) The following are **not implemented**: - Background schedulers - Automatic ticket creation - Automatic ticket reopening - Status pushing without operator action - Ticket content mutation beyond fixed system notes --- ## 11. Phase-based Implementation Workflow For each Phase 2 sub-phase, a **dedicated chat** must be used. This ensures focus, traceability, and controlled implementation. The instructions below must be copied **verbatim** when starting a new chat for the corresponding phase. --- ## Phase 2.1 – Chat Instructions Purpose: Implement **read-only ticket polling** when the Run Checks page is opened. Chat instructions: - Scope is limited to Phase 2.1 only - No ticket state changes are allowed - No resolve, close, or mutation logic may be added - Only backend polling and UI visibility updates are permitted - All changes must be functionally testable on Run Checks Exit criteria: - Polling executes only when Run Checks is opened - Only relevant active tickets are queried - No Backupchecks run state is modified --- ## Phase 2.2 – Chat Instructions Purpose: Implement **PSA-driven resolution handling** based on polling results. Chat instructions: - Phase 2.1 must already be completed and validated - Only Completed ticket handling may be added - Resolution origin must be stored and displayed - No Backupchecks-initiated ticket changes are allowed Exit criteria: - Completed tickets resolve runs correctly - Resolution origin is accurate and persistent - Active tickets remain unchanged --- ## Phase 2.3 – Chat Instructions Purpose: Implement **deleted ticket detection and operator visibility**. Chat instructions: - Phase 2.1 and 2.2 must already be completed - Detection must be explicit and non-destructive - Historical ticket references must remain intact - UI must clearly indicate deleted state Exit criteria: - Deleted tickets are reliably detected - Operators are clearly informed - Ticket actions are blocked correctly --- ## Phase 2.4 – Chat Instructions Purpose: Implement **manual ticket resolution from Backupchecks to Autotask**. Chat instructions: - All previous Phase 2 sub-phases must be completed - Resolution must be strictly operator-driven - Time entry rules must be enforced exactly - Resolution origin must be stored correctly Exit criteria: - Tickets are resolved only when allowed - Time entry edge cases behave correctly - State remains consistent with PSA polling --- ## 12. Phase 2 Completion Criteria Phase 2 is considered complete when: - All Phase 2 sub-phases have passed their control moments - No cross-phase leakage of logic exists - Enable/disable integration behaviour is respected - Functional behaviour matches the approved design exactly --- End of Phase 2 implementation document.