Auto-commit local changes before build (2026-01-15 09:37:33)
This commit is contained in:
parent
777a9b4b31
commit
48e7830957
@ -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
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user