ivooskamp/backupchecks
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
ef8d12065b
backupchecks/docs/backupchecks_autotask_integration_implementation_breakdown.md

4.7 KiB
Raw Blame History

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.