5.8 KiB
Backupchecks – Autotask Integration
Functional Design – Phase 1
Last updated: 2026-01-13
1. Scope & Goals
This document describes the functional design and agreed decisions for the first phase of the Autotask integration in Backupchecks.
Goals for phase 1:
- Allow operators to manually create Autotask tickets from Backupchecks.
- Ensure full operator control over when a ticket is created.
- Prevent ticket spam and duplicate tickets.
- Maintain clear ownership between Backupchecks and Autotask.
- Provide a safe and auditable way to resolve tickets from Backupchecks.
Out of scope for phase 1:
- Automatic ticket creation
- Automatic ticket closing on success
- Issue correlation across multiple runs
- Time entry creation or modification
2. Core Principles (Leading)
These principles apply to all design and implementation choices:
- Autotask is an external authoritative system (PSA).
- Backupchecks is a consumer, not an owner, of PSA data.
- IDs are leading, names are display-only.
- All PSA mappings are explicit, never implicit or automatic.
- Operators always retain manual control.
- Renaming in Autotask must never break mappings.
3. Customer ↔ Autotask Company Mapping
3.1 Mapping model
- Mapping is configured in the Customers screen.
- Mapping is a 1-to-1 explicit relationship.
- Stored values per customer:
- PSA type:
autotask - Autotask Company ID (leading)
- Autotask Company Name (cached for display)
- Last sync timestamp
- Mapping status:
ok | renamed | missing | invalid
- PSA type:
Note: The Autotask Company ID is the source of truth. The name exists only for UI clarity.
3.2 Name synchronisation
- If the company name is changed in Autotask:
- Backupchecks updates the cached name automatically.
- The mapping remains intact.
- Backupchecks customer names are independent and never overwritten.
3.3 Failure scenarios
- Autotask company deleted or inaccessible:
- Mapping status becomes
invalid. - Ticket creation is blocked.
- UI clearly indicates broken mapping.
- Mapping status becomes
4. Ticket Creation Model
4.1 Operator-driven creation
- Tickets are created only via an explicit operator action.
- Location: Run Checks page.
- Manual ticket number input is removed.
- A new action replaces it:
- “Create Autotask ticket”
Rationale: There are too many backup alerts that do not require a ticket. Human judgement remains essential.
4.2 One ticket per run (Key decision)
- Exactly one ticket per Run.
- A run can never create multiple tickets.
- If a ticket exists:
- Creation action is replaced by:
- “Open ticket”
- (Later) “Add note”
- Creation action is replaced by:
Rationale: Multiple errors within a run often share the same root cause. This prevents ticket flooding.
4.3 Ticket contents (baseline)
Minimum ticket fields:
- Subject:
[Backupchecks] <Customer> - <Job> - <Status>
- Description:
- Run date/time
- Backup type and job
- Affected objects (e.g. HV01, USB Disk)
- Error / warning messages
- Reference to Backupchecks (URL or identifier)
Optional (configurable later):
- Queue
- Issue type / category
- Priority mapping
5. Ticket State Tracking in Backupchecks
Per Run, Backupchecks stores:
- Autotask Ticket ID
- Autotask Ticket Number
- Ticket URL (optional)
- Created by (operator)
- Created at timestamp
- Last known ticket status (snapshot)
This ensures:
- No duplicate tickets
- Full audit trail
- Clear operator feedback
6. Ticket Resolution from Backupchecks
6.1 Resolution policy
Backupchecks may resolve an Autotask ticket only if:
- The ticket exists
- The ticket is not already closed
- No time entries are present on the ticket
This rule is mandatory and non-configurable.
Rationale: Prevents financial and operational conflicts inside Autotask.
6.2 Operator experience
- Resolve action is visible only if conditions are met.
- If time entries exist:
- Resolve action is hidden or disabled
- Clear message is shown to the operator
6.3 Closing note (fixed text)
When resolving a ticket, Backupchecks always adds the following note before closing:
Ticket resolved via Backupchecks after verification that the backup issue is no longer present.
Characteristics:
- Fixed text (no operator editing in phase 1)
- System / internal note (not customer-facing)
- Ensures auditability and clarity
7. Backupchecks Settings
7.1 New settings section
Settings → Extensions & Integrations → Autotask
7.2 Required settings
- Enable Autotask integration (on/off)
- Environment: Sandbox / Production
- API Username
- API Password
- Tracking Identifier
7.3 Optional / recommended settings
- Default ticket queue
- Default issue type / category
- Priority mapping (Error vs Warning)
- Default new ticket status
7.4 Resolve configuration
- Allow resolving tickets from Backupchecks (on/off)
- Closing note text (read-only, fixed)
7.5 Validation & diagnostics
- Test connection
- Validate configuration
- Optional API logging level
Note: Customer mapping is intentionally not part of global settings.
8. Roles & Permissions
- Admin / Operator:
- Create tickets
- Resolve tickets (if allowed)
- Reporter:
- View ticket number and link
- No create or resolve actions
9. Explicit Non-Goals (Phase 1)
The following are explicitly excluded:
- Automatic ticket creation
- Automatic ticket closing
- Updating ticket content after creation
- Multiple tickets per run
- Time entry handling
- Multi-PSA support
10. Phase 1 Summary
Phase 1 delivers:
- Safe, controlled PSA integration
- Operator-driven ticket lifecycle
- Clear audit trail
- Minimal risk to Autotask data integrity
This design intentionally prioritises predictability and control over automation.
Future phases may build on this foundation.