From 48e7830957d9fece372efa03acdc4c5cad8562e9 Mon Sep 17 00:00:00 2001 From: Ivo Oskamp Date: Thu, 15 Jan 2026 09:37:33 +0100 Subject: [PATCH] Auto-commit local changes before build (2026-01-15 09:37:33) --- ...k_integration_functional_design_phase_1.md | 274 ++++++++++++++++-- ...sk_integration_implementation_breakdown.md | 205 +++++++++++++ 2 files changed, 457 insertions(+), 22 deletions(-) create mode 100644 docs/backupchecks_autotask_integration_implementation_breakdown.md diff --git a/docs/backupchecks_autotask_integration_functional_design_phase_1.md b/docs/backupchecks_autotask_integration_functional_design_phase_1.md index f07dd7a..0575753 100644 --- a/docs/backupchecks_autotask_integration_functional_design_phase_1.md +++ b/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 time entries exist: - - Resolve action is hidden or disabled - - Clear message is shown to the operator +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, 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) -- Ensures auditability and clarity +- **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. --- @@ -175,26 +324,58 @@ Characteristics: - API Password - Tracking Identifier -### 7.3 Optional / recommended settings +### 7.3 Ticket creation defaults (configurable) -- Default ticket queue -- Default issue type / category -- Priority mapping (Error vs Warning) -- Default new ticket status +These defaults are applied when Backupchecks creates a new Autotask ticket. -### 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 diff --git a/docs/backupchecks_autotask_integration_implementation_breakdown.md b/docs/backupchecks_autotask_integration_implementation_breakdown.md new file mode 100644 index 0000000..1fca3d2 --- /dev/null +++ b/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. +