Auto-commit local changes before build (2026-01-15 09:37:33)

docs/backupchecks_autotask_integration_functional_design_phase_1.md

@@ -124,7 +124,77 @@ Per Run, Backupchecks stores:
 This ensures:
 - No duplicate tickets
 - Full audit trail
-- Clear operator feedback
+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
 
 ---
 
@@ -141,23 +211,102 @@ This rule is **mandatory and non-configurable**.
 
 > **Rationale:** Prevents financial and operational conflicts inside Autotask.
 
-### 6.2 Operator experience
+### 6.2 Behaviour when time entries exist
 
-- Resolve action is visible only if conditions are met.
+If an operator clicks **Resolve ticket** but the ticket **contains time entries**:
-- If time entries exist:
+- The ticket **must not be closed** by Backupchecks.
-  - Resolve action is hidden or disabled
+- Backupchecks **adds an internal system note** to the ticket stating that it was marked as resolved from Backupchecks.
-  - Clear message is shown to the operator
+- 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, Backupchecks always adds the following note **before closing**:
+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 (not customer-facing)
+- **System / internal note** (never customer-facing)
-- Ensures auditability and clarity
+- 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.
 
 ---
 
@@ -175,26 +324,58 @@ Characteristics:
 - API Password
 - Tracking Identifier
 
-### 7.3 Optional / recommended settings
+### 7.3 Ticket creation defaults (configurable)
 
-- Default ticket queue
+These defaults are applied when Backupchecks creates a new Autotask ticket.
-- Default issue type / category
-- Priority mapping (Error vs Warning)
-- Default new ticket status
 
-### 7.4 Resolve configuration
+- 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 text (read-only, fixed)
+- Closing note texts (read-only, fixed):
+  - Standard resolve note
+  - Time-entry-blocked resolve note
 
-### 7.5 Validation & diagnostics
+### 7.6 Validation & diagnostics
 
 - Test connection
-- Validate configuration
+- Validate configuration (credentials, reference data access)
 - Optional API logging level
 
-> **Note:** Customer mapping is intentionally **not** part of global settings.
-
 ---
 
 ## 8. Roles & Permissions
@@ -208,11 +389,59 @@ Characteristics:
 
 ---
 
-## 9. Explicit Non-Goals (Phase 1)
+## 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
@@ -220,11 +449,12 @@ The following are explicitly excluded:
 
 ---
 
-## 10. Phase 1 Summary
+## 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
 

docs/backupchecks_autotask_integration_implementation_breakdown.md

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