206 lines
4.7 KiB
Markdown
206 lines
4.7 KiB
Markdown
# 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.
|
||
|