ivooskamp/backupchecks
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
v20260116-04-runchecks-autotask-ticket-polling
backupchecks/docs/backupchecks_autotask_integration_phase_2_implementation.md

9.7 KiB
Raw Permalink Blame History

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.