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