ivooskamp/backupchecks

Fork 0

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

2026-01-15 09:37:33 +01:00

14 KiB

Raw Permalink Blame History

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 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:

Overall remark (run-level summary) – if present, this is leading.
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

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 Behaviour when time entries exist

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 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 (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.

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 Ticket creation defaults (configurable)

These defaults are applied when Backupchecks creates a new Autotask ticket.

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 texts (read-only, fixed):
- Standard resolve note
- Time-entry-blocked resolve note

7.6 Validation & diagnostics

Test connection
Validate configuration (credentials, reference data access)
Optional API logging level

8. Roles & Permissions

Admin / Operator:
- Create tickets
- Resolve tickets (if allowed)
Reporter:
- View ticket number and link
- No create or resolve actions

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.