# 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