backupchecks/docs/backupchecks_autotask_integration_functional_design_living_document.md

Backupchecks – Autotask Integration

Functional Design

Last updated: 2026-01-16

---

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

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.

4.2 One ticket per run

• Exactly one ticket per run.
• A run can never create multiple tickets.
• If a ticket exists:
  • Creation action is replaced by Open ticket.

4.3 Ticket contents (baseline)

Minimum ticket fields:

• Subject: [Backupchecks] - -
• Description:
  • Run date/time
  • Backup type and job
  • Affected objects
  • Error or warning messages
  • Reference to Backupchecks

---

5. Ticket State Tracking in Backupchecks

Per run, Backupchecks stores:

• Autotask Ticket ID
• Autotask Ticket Number
• Ticket URL
• Created by
• Created at timestamp
• Last known ticket status (snapshot)

---

6. Ticket Resolution from Backupchecks

Backupchecks may resolve a ticket only if:

• The ticket exists
• The ticket is not already closed
• No time entries are present

If time entries exist, the ticket is not closed and an internal system note is added.

---

7. Backupchecks Settings

Settings → Extensions & Integrations → Autotask

Includes:

• Enable integration (on/off)
• Environment
• API credentials
• Tracking Identifier
• Default queue and status
• Priority mapping

7.1 Enable / disable behaviour (mandatory)

Backupchecks must support switching the Autotask integration on and off at any time.

When Autotask integration is enabled:

• Autotask actions are available (create ticket, resolve ticket, link existing ticket).
• Ticket polling/synchronisation (Phase 2) is active.

When Autotask integration is disabled:

• Backupchecks falls back to the manual workflow:
  • Operators can manually enter ticket numbers.
  • No Autotask API calls are executed.
  • No polling is performed.
  • No resolve action is available (as it would require Autotask calls).
• Existing stored Autotask references remain visible for audit/history.

The enable/disable switch must be reversible and must not require data deletion or migration.

---

8. Roles & Permissions

• Admin / Operator: create and resolve tickets
• Reporter: view-only access

---

9. Explicit Non-Goals (Phase 1)

• Automatic ticket creation
• Automatic ticket closing
• Time entry handling
• Multiple tickets per run
• PSA-side logic

---

10. Phase 1 Summary

Phase 1 delivers controlled, operator-driven PSA integration with a strong focus on auditability and predictability.

---

11. Phase 2 – Ticket State Synchronisation (PSA-driven)

This phase introduces PSA-driven state awareness for already linked tickets. The goal is to keep Backupchecks aligned with Autotask without introducing active control or automation.

11.1 Polling strategy (Run Checks entry point)

• Polling is executed only when Autotask integration is enabled.

• When the Run Checks page is opened, Backupchecks performs a targeted poll to Autotask.

• When the Run Checks page is opened, Backupchecks performs a targeted poll to Autotask.

• Only tickets that are:

  • Linked to runs shown on the page, and
  • Not in a terminal state inside Backupchecks are included.

• Tickets already marked as resolved or broken are excluded.

This prevents unnecessary API calls and limits polling to operator-relevant context.

11.2 Active-ticket-only retrieval

• Backupchecks only queries tickets that are considered active in Autotask.
• Completed or closed tickets are not included in the active-ticket query.
• This ensures minimal load and avoids repeated retrieval of historical data.

11.3 PSA-driven completion handling

If Autotask reports a ticket with status Completed:

• The linked run in Backupchecks is automatically marked as Resolved.
• The resolution is explicitly flagged as:
  • Resolved by PSA
• Backupchecks does not add notes or modify the ticket in Autotask.

UI behaviour:

• Operators can clearly see that the resolution originated from the PSA.
• A visual indicator highlights that the underlying backup issue may still require verification.

11.4 Operator awareness and follow-up

When a ticket is resolved by PSA:

• Backupchecks does not assume the technical issue is resolved.
• Operators are expected to:
  • Review the related run
  • Decide whether further action is required inside Backupchecks

No automatic reopening or ticket creation is performed.

11.5 Deleted ticket detection

If a linked ticket is deleted in Autotask:

• Backupchecks detects this during polling.
• The ticket linkage is marked as:
  • Deleted in PSA

UI behaviour:

• A clear warning is shown to the operator.
• The historical ticket reference remains visible for audit purposes.
• Ticket-related actions are blocked until the operator:
  • Links a replacement ticket, or
  • Creates a new Autotask ticket

11.6 Ticket resolution from Backupchecks (operator-driven)

Phase 2 includes implementation of manual ticket resolution from Backupchecks under the already defined Phase 1 rules.

• Resolution is always an explicit operator action (no automation).
• Resolution rules remain leading (see Chapter 6):
  • Ticket must exist
  • Ticket must not already be closed
  • Ticket may only be closed by Backupchecks if no time entries exist
  • If time entries exist, Backupchecks adds an internal system note and leaves the ticket open

UI behaviour (Run Checks and Job Details):

• Show a Resolve ticket action only when a validated Autotask Ticket ID exists.
• When resolution succeeds, update the run to Resolved and store:
  • Resolved timestamp
  • Resolved by (operator)
  • Resolution origin: Resolved by Backupchecks

Important alignment with PSA-driven sync:

• If Autotask later reports the ticket as Completed, Backupchecks keeps the run resolved, but the origin remains:
  • Resolved by Backupchecks
• If Autotask reports completion before the operator resolves it, Backupchecks sets:
  • Resolved by PSA

11.7 Explicit non-goals (Phase 2)

The following remain explicitly out of scope:

• Automatic ticket creation
• Automatic ticket reopening
• Automatic resolution without operator intent
• Status pushing from Backupchecks to Autotask (except the explicit Resolve action described above)
• Any modification of existing Autotask ticket content (except fixed-format internal system notes used during resolution rules)

---

12. Future Design Considerations (Post-Phase 2)

The following sections describe future design intent only. They are explicitly out of scope for Phase 2 and introduce no implementation commitments.

12.1 Ticket lifecycle awareness (read-only intelligence)

Objective: Provide better insight into the state of linked tickets without adding actions.

Scope:

• Periodic read-only retrieval of ticket status
• Display of:
  • Current status
  • Queue
  • Assigned resource (owner)

Shown in:

• Run Checks
• Job Details
• Tickets / Remarks overview

Explicitly excluded:

• No automatic actions
• No status synchronisation back to Autotask

Value:

• Operators need to open Autotask less frequently
• Faster visibility into whether a ticket has been picked up

12.2 Operator notes & context enrichment

Objective: Add contextual information to existing tickets without taking ownership away from the PSA.

Scope:

• Add internal/system notes from Backupchecks
• Notes are always written in a fixed format
• Notes are added only by explicit operator action

Rules:

• Never overwrite existing ticket content
• Never create customer-facing notes
• Never generate notes automatically

Value:

• Tickets remain up to date without duplication
• Autotask remains the authoritative system

12.3 Controlled assistance (semi-automatic support)

Objective: Support operator decision-making without introducing automation.

Examples:

• Suggestion: a similar error already has an open ticket
• Suggestion: previous run was successful, consider resolving the ticket
• Highlight repeated failures without any linked ticket

Important constraints:

• Suggestions only
• No automatic ticket creation
• No automatic ticket closure

Value:

• Reduced human error
• No loss of operator control

12.4 Cross-run correlation (analytical)

Objective: Provide insight into structural or recurring problems before tickets are created.

Scope:

• Detection of repeated failures across multiple runs
• Detection of the same object with the same error over time
• Visualisation inside Backupchecks only

Explicitly excluded:

• Ticket bundling
• Ticket merging
• Any Autotask-side modifications

Value:

• Better decisions prior to ticket creation
• Reduced noise in the PSA

12.5 Multi-PSA abstraction (design preparation)

Objective: Prepare the internal design for future PSA support without implementing it.

Scope:

• PSA-agnostic internal models:
  • Ticket
  • Company mapping
  • Resolution rules
• Autotask remains the only concrete implementation

Why this is documented now:

• Prevents Autotask-specific technical debt
• Keeps the architecture open for other PSA platforms

12.6 Governance & audit depth

Objective: Ensure full traceability for MSP and enterprise environments.

Scope:

• Extended audit logging:
  • Who created, linked or resolved a ticket
  • When the action occurred
  • From which run the action originated
• Read-only export capabilities
• Optional compliance-oriented views

Value:

• MSP and enterprise readiness
• Supports internal and external audits

12.7 Explicit non-directions

The following are intentionally excluded unless a strategic decision is made later:

• Automatic ticket creation
• Automatic ticket handling
• Time registration
• Mutation of existing ticket content
• PSA business logic inside Backupchecks