backupchecks/docs/backupchecks_autotask_integration_phase_2_implementation.md

# 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.