# 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` > **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. --- ## 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” > **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] - - ` - 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 n- Clear operator feedback --- ## 5A. Ticket Content Composition Rules This chapter defines how Backupchecks determines **what content is placed in an Autotask ticket**, with the explicit goal of keeping tickets readable and actionable. ### 5A.1 Guiding principle - A ticket is a **signal**, not a log file. - The ticket must remain readable for the ticket owner. - Full technical details always remain available in Backupchecks. ### 5A.2 Content hierarchy (deterministic) Backupchecks applies the following strict hierarchy when composing ticket content: 1. **Overall remark** (run-level summary) – if present, this is leading. 2. **Object-level messages** – used only when no overall remark exists. This hierarchy is fixed and non-configurable in phase 1. ### 5A.3 Scenario A – Overall remark present If an overall remark exists for the run: - The ticket description contains: - The overall remark - Job name, run date/time, and status - Object-level errors are **not listed in full**. - A short informational line is added: - “Multiple objects reported errors. See Backupchecks for full details.” > **Rationale:** The overall remark already represents a consolidated summary. Listing many objects would reduce ticket clarity. ### 5A.4 Scenario B – No overall remark If no overall remark exists: - The ticket description includes object-level errors. - Object listings are **explicitly limited**: - A maximum of *N* objects (exact value defined during implementation) - If more objects are present: - “And X additional objects reported similar errors.” > **Rationale:** Prevents large, unreadable tickets while still providing concrete examples. ### 5A.5 Mandatory reference to Backupchecks Every ticket created by Backupchecks must include a **direct link to the Job Details page of the originating run**. This link is intended as the primary navigation entry point for the ticket owner. The ticket description must include: - Job name - Run date/time - A clickable URL pointing to the Job Details page of that run in Backupchecks > **Rationale:** The Job Details page provides the most complete and structured context for investigation. This ensures: - Full traceability - Fast access to complete technical details --- ### 5A.6 Explicit exclusions The following content is deliberately excluded from ticket descriptions: - Complete object lists when large - Repeated identical error messages - Raw technical dumps or stack traces --- ## 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 Behaviour when time entries exist If an operator clicks **Resolve ticket** but the ticket **contains time entries**: - The ticket **must not be closed** by Backupchecks. - Backupchecks **adds an internal system note** to the ticket stating that it was marked as resolved from Backupchecks. - The ticket remains open for the ticket owner to review and close manually. Proposed internal system note text: > `Ticket marked as resolved in Backupchecks, but not closed automatically because time entries are present.` > **Rationale:** Ensures the ticket owner is explicitly informed without violating Autotask process or financial controls. ### 6.3 Closing note (fixed text) When resolving a ticket **and no time entries are present**, Backupchecks always adds the following **internal system 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** (never customer-facing) - Ensures auditability and traceability --- --- ## 6A. Handling Existing Tickets & Compatibility Mode ### 6A.1 Existing manual ticket numbers In the pre-integration workflow, a run may already contain a manually entered ticket number. When Autotask integration is **enabled**: - Existing ticket numbers remain visible. - Backupchecks may offer a one-time action: - **“Link existing Autotask ticket”** - This validates the ticket in Autotask and stores the **Autotask Ticket ID**. > **Note:** Without an Autotask Ticket ID, Backupchecks must not attempt to resolve a ticket. When Autotask integration is **disabled**: - The current/manual workflow applies (manual ticket number entry). ### 6A.2 Linking existing Autotask tickets When integration is enabled, operators can link an existing Autotask ticket to a run: - Search/select a ticket (preferably by ticket number) - Store: - Autotask Ticket ID - Autotask Ticket Number - Ticket URL (optional) After linking: - The run behaves like an integration-created ticket for viewing and resolution rules. ### 6A.3 Compatibility mode (optional setting) Optional setting (recommended for transition periods): - **“Allow manual ticket number entry when Autotask is enabled”** (default: OFF) Behaviour: - When ON, operators can still manually enter a ticket number even if integration is enabled. - Resolve from Backupchecks is still only possible for tickets that have a validated Autotask Ticket ID. > **Rationale:** Provides a safe escape hatch during rollout and migration. --- ## 6B. Deleted Tickets in Autotask Tickets may be deleted in Autotask. When a ticket referenced by Backupchecks is deleted, the linkage becomes invalid. ### 6B.1 Detection When Backupchecks attempts to fetch the ticket by Autotask Ticket ID: - If Autotask returns “not found” (deleted/missing), Backupchecks marks the linkage as **broken**. ### 6B.2 Behaviour when a ticket is deleted - The run keeps the historical reference (ticket number/ID) for audit purposes. - The ticket state is shown as: - **“Missing in Autotask (deleted)”** - Actions are blocked: - No “Open ticket” (if no valid URL) - No “Resolve ticket” - Operators can choose: - **Re-link to another ticket** (if the ticket was recreated or replaced) - **Create a new Autotask ticket** (creates a new link for that run) > **Note:** Backupchecks should never silently remove the stored linkage, to preserve auditability. ### 6B.3 Optional: periodic validation Optionally (later), Backupchecks may periodically validate linked ticket IDs and flag missing tickets. --- ## 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 Ticket creation defaults (configurable) These defaults are applied when Backupchecks creates a new Autotask ticket. - Ticket Source (default): **Monitoring Alert** - Default Queue (default): **Helpdesk** - Default Status (default): **New** - Priority mapping: - Warning → **Medium** - Error → **High** > **Note:** Issue Type / Category is intentionally **not set** by Backupchecks and will be assigned by the ticket owner or traffic manager. --- ### 7.3A Backupchecks Base URL - Base URL of the Backupchecks instance (e.g. `https://backupchecks.example.com`) This value is required to construct: - Direct links to Job Details pages - Stable references inside Autotask tickets > **Note:** This setting is mandatory for ticket creation and must be validated. --- ### 7.4 Dynamic reference data Backupchecks must retrieve the following reference data from Autotask and present it in Settings: - Available Queues - Available Ticket Sources These lists are: - Loaded on demand (or via refresh action) - Stored for selection in Settings > **Rationale:** Prevents hard-coded values and keeps Backupchecks aligned with Autotask configuration changes. ### 7.5 Resolve configuration - Allow resolving tickets from Backupchecks (on/off) - Closing note texts (read-only, fixed): - Standard resolve note - Time-entry-blocked resolve note ### 7.6 Validation & diagnostics - Test connection - Validate configuration (credentials, reference data access) - Optional API logging level --- ## 8. Roles & Permissions - Admin / Operator: - Create tickets - Resolve tickets (if allowed) - Reporter: - View ticket number and link - No create or resolve actions --- ## 9. Handling Existing, Linked and Deleted Tickets ### 9.1 Existing tickets (pre-integration) - Runs that already contain a manually entered ticket number remain valid. - When Autotask integration is enabled, operators may optionally: - Link the run to an existing Autotask ticket (validated against Autotask). - After linking, the run follows the same rules as integration-created tickets. > **Note:** This optional compatibility flow exists to support a gradual transition and avoids forced migration. ### 9.2 Optional compatibility mode - Optional setting: **Allow manual ticket number entry when Autotask is enabled** - Default: OFF - Intended as a temporary transition mechanism. ### 9.3 Deleted tickets in Autotask (important case) Tickets may be deleted directly in Autotask. Backupchecks must handle this safely and explicitly. Behaviour: - Backupchecks never assumes tickets exist based on stored data alone. - On any ticket-related action (view, resolve, open): - Backupchecks validates the ticket ID against Autotask. If Autotask returns *not found*: - The ticket is marked as **Deleted (external)**. - The existing link is preserved as historical data but marked inactive. - No further actions (resolve, update) are allowed on that ticket. UI behaviour: - Ticket number remains visible with a clear indicator: - “Ticket deleted in Autotask” - Operator is offered one explicit action: - “Create new Autotask ticket” (results in a new ticket linked to the same run) > **Rationale:** Ticket deletion is an external administrative decision. Backupchecks records the fact but does not attempt to repair or hide it. ### 9.4 Why links are not silently removed - Silent removal would break audit trails. - Historical runs must retain context, even if external objects no longer exist. - Operators must explicitly decide how to proceed. --- ## 10. Explicit Non-Goals (Phase 1) The following are explicitly excluded: - Automatic ticket creation - Automatic ticket closing - Automatic re-creation of deleted tickets - Updating ticket content after creation - Multiple tickets per run - Time entry handling - Multi-PSA support --- ## 11. Phase 1 Summary Phase 1 delivers: - Safe, controlled PSA integration - Operator-driven ticket lifecycle - Explicit handling of legacy, linked and deleted tickets - 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.