Merge pull request 'v20260113-08-vspc-object-linking-normalize' (#114) from v20260113-08-vspc-object-linking-normalize into main

Reviewed-on: #114

docs/backupchecks_autotask_integration_functional_design_phase_1.md

@@ -1,464 +0,0 @@
-# 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
-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.
-

docs/backupchecks_autotask_integration_implementation_breakdown.md

@@ -1,205 +0,0 @@
-# Backupchecks – Autotask Integration
-
-## Implementation Breakdown & Validation Plan
-
-_Last updated: 2026-01-13_
-
----
-
-## 1. Purpose of this document
-
-This document describes the **logical breakdown of the Autotask integration into implementation phases**.
-
-It is intended to:
-- Provide context at the start of each development chat
-- Keep focus on the **overall goal** while working step by step
-- Ensure each phase is independently testable and verifiable
-- Prevent scope creep during implementation
-
-This document complements:
-- *Backupchecks – Autotask Integration Functional Design (Phase 1)*
-
----
-
-## 2. Guiding implementation principles
-
-- Implement in **small, validated steps**
-- Each phase must be:
-  - Testable in isolation
-  - Reviewable without knowledge of later phases
-- No UI or workflow assumptions beyond the current phase
-- Sandbox-first development
-- No breaking changes without explicit intent
-
----
-
-## 3. Implementation phases
-
-### Phase 1 – Autotask integration foundation
-
-**Goal:** Establish a reliable, testable Autotask integration layer.
-
-Scope:
-- Autotask client/service abstraction
-- Authentication handling
-- Tracking Identifier usage
-- Environment selection (Sandbox / Production)
-- Test connection functionality
-- Fetch reference data:
-  - Queues
-  - Ticket Sources
-
-Out of scope:
-- UI integration (except minimal test hooks)
-- Ticket creation
-- Customer mapping
-
-Validation criteria:
-- Successful authentication against Sandbox
-- Reference data can be retrieved and parsed
-- Clear error handling for auth and API failures
-
----
-
-### Phase 2 – Settings integration
-
-**Goal:** Persist and validate Autotask configuration in Backupchecks.
-
-Scope:
-- New Settings section:
-  - Extensions & Integrations → Autotask
-- Store:
-  - Enable/disable toggle
-  - Environment
-  - API credentials
-  - Tracking Identifier
-  - Backupchecks Base URL
-  - Ticket defaults (queue, source, priorities)
-- Dropdowns populated from live Autotask reference data
-- Test connection & refresh reference data actions
-
-Out of scope:
-- Customer mapping
-- Ticket creation
-
-Validation criteria:
-- Settings can be saved and reloaded
-- Invalid configurations are blocked
-- Reference data reflects Autotask configuration
-
----
-
-### Phase 3 – Customer to Autotask company mapping
-
-**Goal:** Establish stable, ID-based customer mappings.
-
-Scope:
-- Customer screen enhancements
-- Search/select Autotask companies
-- Store company ID + cached name
-- Detect and reflect renamed or deleted companies
-- Mapping status indicators
-
-Out of scope:
-- Ticket creation
-- Run-level logic
-
-Validation criteria:
-- Mapping persists correctly
-- Renaming in Autotask does not break linkage
-- Deleted companies are detected and reported
-
----
-
-### Phase 4 – Ticket creation from Run Checks
-
-**Goal:** Allow operators to create Autotask tickets from Backupchecks runs.
-
-Scope:
-- “Create Autotask ticket” action
-- Ticket payload composition rules
-- Priority mapping (Warning / Error)
-- Queue, source, status defaults
-- Job Details page link inclusion
-- Store ticket ID and number
-
-Out of scope:
-- Ticket resolution
-- Linking existing tickets
-
-Validation criteria:
-- Exactly one ticket per run
-- Tickets contain correct content and links
-- No duplicate tickets can be created
-
----
-
-### Phase 5 – Ticket resolution flows
-
-**Goal:** Safely resolve tickets from Backupchecks.
-
-Scope:
-- Resolve without time entries:
-  - Internal note
-  - Close ticket
-- Resolve with time entries:
-  - Internal note only
-  - Ticket remains open
-- All notes stored as internal/system notes
-
-Out of scope:
-- Automatic resolution
-- Time entry creation
-
-Validation criteria:
-- Time entry checks enforced
-- Correct notes added in all scenarios
-- Ticket status reflects expected behaviour
-
----
-
-### Phase 6 – Integration disable & compatibility behaviour
-
-**Goal:** Ensure safe fallback and migration support.
-
-Scope:
-- Disable Autotask integration globally
-- Restore manual ticket number workflow
-- Optional compatibility mode:
-  - Allow manual ticket number entry while integration enabled
-- Link existing Autotask tickets to runs
-
-Validation criteria:
-- No Autotask API calls when integration is disabled
-- Existing data remains visible
-- Operators can safely transition between workflows
-
----
-
-## 4. Usage in development chats
-
-For each development chat:
-- Include this document
-- Include the Functional Design document
-- Clearly state:
-  - Current phase
-  - Current branch name
-  - Provided source/zip (if applicable)
-
-This ensures:
-- Shared context
-- Focused discussions
-- Predictable progress
-
----
-
-## 5. Summary
-
-This breakdown ensures the Autotask integration is:
-- Predictable
-- Auditable
-- Incrementally delivered
-- Easy to reason about during implementation
-
-Each phase builds on the previous one without hidden dependencies.
-