# 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] <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.