# Backupchecks – Autotask Integration

## Implementation Breakdown & Validation Plan

_Last updated: 2026-01-13_

---

## 1. Purpose of this document

This document describes the **logical breakdown of the Autotask integration into implementation phases**.

It is intended to:
- Provide context at the start of each development chat
- Keep focus on the **overall goal** while working step by step
- Ensure each phase is independently testable and verifiable
- Prevent scope creep during implementation

This document complements:
- *Backupchecks – Autotask Integration Functional Design (Phase 1)*

---

## 2. Guiding implementation principles

- Implement in **small, validated steps**
- Each phase must be:
  - Testable in isolation
  - Reviewable without knowledge of later phases
- No UI or workflow assumptions beyond the current phase
- Sandbox-first development
- No breaking changes without explicit intent

---

## 3. Implementation phases

### Phase 1 – Autotask integration foundation

**Goal:** Establish a reliable, testable Autotask integration layer.

Scope:
- Autotask client/service abstraction
- Authentication handling
- Tracking Identifier usage
- Environment selection (Sandbox / Production)
- Test connection functionality
- Fetch reference data:
  - Queues
  - Ticket Sources

Out of scope:
- UI integration (except minimal test hooks)
- Ticket creation
- Customer mapping

Validation criteria:
- Successful authentication against Sandbox
- Reference data can be retrieved and parsed
- Clear error handling for auth and API failures

---

### Phase 2 – Settings integration

**Goal:** Persist and validate Autotask configuration in Backupchecks.

Scope:
- New Settings section:
  - Extensions & Integrations → Autotask
- Store:
  - Enable/disable toggle
  - Environment
  - API credentials
  - Tracking Identifier
  - Backupchecks Base URL
  - Ticket defaults (queue, source, priorities)
- Dropdowns populated from live Autotask reference data
- Test connection & refresh reference data actions

Out of scope:
- Customer mapping
- Ticket creation

Validation criteria:
- Settings can be saved and reloaded
- Invalid configurations are blocked
- Reference data reflects Autotask configuration

---

### Phase 3 – Customer to Autotask company mapping

**Goal:** Establish stable, ID-based customer mappings.

Scope:
- Customer screen enhancements
- Search/select Autotask companies
- Store company ID + cached name
- Detect and reflect renamed or deleted companies
- Mapping status indicators

Out of scope:
- Ticket creation
- Run-level logic

Validation criteria:
- Mapping persists correctly
- Renaming in Autotask does not break linkage
- Deleted companies are detected and reported

---

### Phase 4 – Ticket creation from Run Checks

**Goal:** Allow operators to create Autotask tickets from Backupchecks runs.

Scope:
- “Create Autotask ticket” action
- Ticket payload composition rules
- Priority mapping (Warning / Error)
- Queue, source, status defaults
- Job Details page link inclusion
- Store ticket ID and number

Out of scope:
- Ticket resolution
- Linking existing tickets

Validation criteria:
- Exactly one ticket per run
- Tickets contain correct content and links
- No duplicate tickets can be created

---

### Phase 5 – Ticket resolution flows

**Goal:** Safely resolve tickets from Backupchecks.

Scope:
- Resolve without time entries:
  - Internal note
  - Close ticket
- Resolve with time entries:
  - Internal note only
  - Ticket remains open
- All notes stored as internal/system notes

Out of scope:
- Automatic resolution
- Time entry creation

Validation criteria:
- Time entry checks enforced
- Correct notes added in all scenarios
- Ticket status reflects expected behaviour

---

### Phase 6 – Integration disable & compatibility behaviour

**Goal:** Ensure safe fallback and migration support.

Scope:
- Disable Autotask integration globally
- Restore manual ticket number workflow
- Optional compatibility mode:
  - Allow manual ticket number entry while integration enabled
- Link existing Autotask tickets to runs

Validation criteria:
- No Autotask API calls when integration is disabled
- Existing data remains visible
- Operators can safely transition between workflows

---

## 4. Usage in development chats

For each development chat:
- Include this document
- Include the Functional Design document
- Clearly state:
  - Current phase
  - Current branch name
  - Provided source/zip (if applicable)

This ensures:
- Shared context
- Focused discussions
- Predictable progress

---

## 5. Summary

This breakdown ensures the Autotask integration is:
- Predictable
- Auditable
- Incrementally delivered
- Easy to reason about during implementation

Each phase builds on the previous one without hidden dependencies.