Auto-commit local changes before build (2026-01-13 17:16:20)
This commit is contained in:
parent
c57c58cc3d
commit
777a9b4b31
@ -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.
|
||||||
|
|
||||||
Loading…
Reference in New Issue
Block a user