From 777a9b4b312c63e73551cca4dbbfaae679673da4 Mon Sep 17 00:00:00 2001
From: Ivo Oskamp <ivooskamp@oskamp.info>
Date: Tue, 13 Jan 2026 17:16:20 +0100
Subject: [PATCH] Auto-commit local changes before build (2026-01-13 17:16:20)

---
 ...k_integration_functional_design_phase_1.md | 234 ++++++++++++++++++
 1 file changed, 234 insertions(+)
 create mode 100644 docs/backupchecks_autotask_integration_functional_design_phase_1.md

diff --git a/docs/backupchecks_autotask_integration_functional_design_phase_1.md b/docs/backupchecks_autotask_integration_functional_design_phase_1.md
new file mode 100644
index 0000000..f07dd7a
--- /dev/null
+++ b/docs/backupchecks_autotask_integration_functional_design_phase_1.md
@@ -0,0 +1,234 @@
+# 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.
+