{% extends "documentation/base.html" %}

{% block doc_content %}
<h1>Remarks & Tickets</h1>

<p class="lead">
  Document known issues, track followup work, and link backup problems to tickets for resolution.
</p>

<h2>Overview</h2>

<p>BackupChecks provides two mechanisms for documenting and tracking backup issues:</p>

<ul>
  <li><strong>Tickets:</strong> For issues requiring external followup (customer action, vendor support, hardware replacement)</li>
  <li><strong>Remarks:</strong> For internal notes, known issues, or temporary problems that don't need formal ticket tracking</li>
</ul>

<p>Both tickets and remarks can be linked to specific job runs, making it easy to track which backups are affected by known issues.</p>

<h2>Accessing Tickets & Remarks</h2>

<p>To view and manage tickets and remarks:</p>

<ol>
  <li>Navigate to <strong>Tickets</strong> in the main navigation menu</li>
  <li>Available to <strong>Admin</strong>, <strong>Operator</strong>, and <strong>Viewer</strong> roles</li>
  <li>Two tabs are available:
    <ul>
      <li><strong>Tickets:</strong> Shows all tickets with their resolution status</li>
      <li><strong>Remarks:</strong> Shows all remarks with their resolution status</li>
    </ul>
  </li>
</ol>

<h2>Tickets</h2>

<h3>What is a Ticket?</h3>

<p>A <strong>ticket</strong> represents an issue that requires tracking and followup. Tickets are used for:</p>

<ul>
  <li>Hardware failures requiring replacement</li>
  <li>Software bugs reported to vendors</li>
  <li>Customer action items (upgrade server, allocate more storage)</li>
  <li>Configuration changes needed (adjust backup schedule, exclude specific files)</li>
</ul>

<h3>Ticket Properties</h3>

<p>Each ticket has the following properties:</p>

<table>
  <thead>
    <tr>
      <th>Property</th>
      <th>Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><strong>Ticket code</strong></td>
      <td>Unique identifier (e.g., T12345, CUST-456). Can reference an external PSA ticket number.</td>
    </tr>
    <tr>
      <td><strong>Description</strong></td>
      <td>Brief description of the issue</td>
    </tr>
    <tr>
      <td><strong>Active from date</strong></td>
      <td>Date when the ticket becomes active (usually the date the issue was first observed)</td>
    </tr>
    <tr>
      <td><strong>Start date</strong></td>
      <td>Timestamp when the ticket was created in BackupChecks</td>
    </tr>
    <tr>
      <td><strong>Resolved at</strong></td>
      <td>Timestamp when the ticket was marked as resolved (blank if still active)</td>
    </tr>
    <tr>
      <td><strong>Scopes</strong></td>
      <td>Which backup jobs, customers, or objects this ticket affects</td>
    </tr>
  </tbody>
</table>

<h3>Creating a Ticket</h3>

<p>Tickets can be created from several locations in the application:</p>

<h4>From Run Checks Modal</h4>

<ol>
  <li>Open the Run Checks modal for a job with a warning or failure</li>
  <li>Review the job run details</li>
  <li>Click <strong>Create Ticket</strong> (button location depends on UI implementation)</li>
  <li>Fill in ticket details:
    <ul>
      <li><strong>Ticket code:</strong> Enter a unique identifier (e.g., reference your PSA system)</li>
      <li><strong>Description:</strong> Briefly describe the issue</li>
      <li><strong>Active from date:</strong> Select when the issue started (defaults to today)</li>
    </ul>
  </li>
  <li>The ticket is automatically linked to the current job run</li>
  <li>Scopes are automatically populated based on the job</li>
</ol>

<h4>From Tickets Page</h4>

<p>Tickets can also be created manually from the Tickets page (for issues not tied to a specific run).</p>

<h3>Ticket Scopes</h3>

<p>A ticket can have multiple <strong>scopes</strong> defining what it affects:</p>

<ul>
  <li><strong>Customer scope:</strong> All backup jobs for a specific customer</li>
  <li><strong>Backup software scope:</strong> All jobs using specific backup software (e.g., all Veeam jobs)</li>
  <li><strong>Backup type scope:</strong> All jobs of a specific type (e.g., all Replication Jobs)</li>
  <li><strong>Job scope:</strong> A specific backup job</li>
  <li><strong>Job run scope:</strong> A specific backup job run</li>
</ul>

<p>Scopes are used to automatically show ticket indicators (🎫) on affected jobs in the Daily Jobs view.</p>

<h3>Viewing Ticket Details</h3>

<ol>
  <li>Go to the <strong>Tickets</strong> page</li>
  <li>Click <strong>View</strong> on a ticket row</li>
  <li>The ticket detail page shows:
    <ul>
      <li>Ticket status (Active or Resolved)</li>
      <li>Ticket code, description, and dates</li>
      <li>Scopes (which jobs/customers are affected)</li>
      <li>Linked runs (last 20 job runs associated with this ticket)</li>
    </ul>
  </li>
</ol>

<h3>Resolving a Ticket</h3>

<p>When a ticket is resolved:</p>

<ol>
  <li>Go to the <strong>Tickets</strong> page</li>
  <li>Click <strong>Resolve</strong> on an active ticket row (Admin/Operator only)</li>
  <li>The ticket is marked as resolved with the current timestamp</li>
  <li>Resolved tickets remain visible in the ticket list with a ✅ indicator</li>
  <li>The ticket indicator (🎫) is removed from job displays</li>
</ol>

<div class="doc-callout doc-callout-info">
  <strong>💡 Ticket Resolution:</strong><br>
  Resolving a ticket does NOT delete it - it simply marks it as closed. Resolved tickets remain visible for historical reference and can be filtered using the "Status" dropdown.
</div>

<h3>Linking Tickets to Additional Runs</h3>

<p>After creating a ticket, you can link it to additional job runs as they occur:</p>

<ol>
  <li>Open the Run Checks modal for a job run</li>
  <li>Look for existing tickets in the ticket list (if available in UI)</li>
  <li>Link the ticket to the current run</li>
</ol>

<p>This creates an audit trail showing all job runs affected by the same ticket.</p>

<h2>Remarks</h2>

<h3>What is a Remark?</h3>

<p>A <strong>remark</strong> is a lightweight note for documenting known issues that don't require formal ticket tracking. Remarks are used for:</p>

<ul>
  <li>Temporary issues (planned downtime, maintenance windows)</li>
  <li>Known non-critical warnings (acceptable performance issues, cosmetic problems)</li>
  <li>Internal documentation (schedule change notes, customer preferences)</li>
  <li>Quick notes during triage ("investigated, not an issue")</li>
</ul>

<h3>Remark Properties</h3>

<table>
  <thead>
    <tr>
      <th>Property</th>
      <th>Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><strong>Body</strong></td>
      <td>Freeform text describing the remark (no length limit)</td>
    </tr>
    <tr>
      <td><strong>Start date</strong></td>
      <td>Timestamp when the remark was created</td>
    </tr>
    <tr>
      <td><strong>Resolved at</strong></td>
      <td>Timestamp when the remark was marked as resolved (blank if still active)</td>
    </tr>
    <tr>
      <td><strong>Scopes</strong></td>
      <td>Which backup jobs, customers, or objects this remark affects</td>
    </tr>
  </tbody>
</table>

<h3>Creating a Remark</h3>

<p>Remarks are created similarly to tickets:</p>

<h4>From Run Checks Modal</h4>

<ol>
  <li>Open the Run Checks modal for a job run</li>
  <li>Review the job run details</li>
  <li>Click <strong>Create Remark</strong></li>
  <li>Enter remark text in the body field (supports multi-line text)</li>
  <li>The remark is automatically linked to the current job run</li>
  <li>Scopes are automatically populated based on the job</li>
</ol>

<h4>From Tickets Page</h4>

<ol>
  <li>Go to the <strong>Tickets</strong> page</li>
  <li>Switch to the <strong>Remarks</strong> tab</li>
  <li>Create a remark manually (if supported in UI)</li>
</ol>

<h3>Viewing Remark Details</h3>

<ol>
  <li>Go to the <strong>Tickets</strong> page</li>
  <li>Switch to the <strong>Remarks</strong> tab</li>
  <li>Click <strong>View</strong> on a remark row</li>
  <li>The remark detail page shows:
    <ul>
      <li>Remark status (Active or Resolved)</li>
      <li>Remark body (full text)</li>
      <li>Scopes (which jobs/customers are affected)</li>
      <li>Linked runs (last 20 job runs associated with this remark)</li>
    </ul>
  </li>
</ol>

<h3>Resolving a Remark</h3>

<ol>
  <li>Go to the <strong>Tickets</strong> page → <strong>Remarks</strong> tab</li>
  <li>Click <strong>Resolve</strong> on an active remark row (Admin/Operator only)</li>
  <li>The remark is marked as resolved</li>
  <li>Resolved remarks remain visible with a ✅ indicator</li>
  <li>The remark indicator (💬) is removed from job displays</li>
</ol>

<h2>Filtering Tickets & Remarks</h2>

<p>The Tickets page provides filtering options:</p>

<ul>
  <li><strong>Status:</strong> Filter by "Active" (unresolved) or "All" (including resolved)</li>
  <li><strong>Customer:</strong> Show only tickets/remarks for a specific customer</li>
  <li><strong>Backup software:</strong> Filter by backup software (e.g., Veeam, Synology)</li>
  <li><strong>Backup type:</strong> Filter by backup type (e.g., Backup Job, Replication Job)</li>
  <li><strong>Search:</strong> Search by ticket code or job name</li>
</ul>

<p>Click <strong>Filter</strong> to apply the selected criteria, or <strong>Reset</strong> to clear all filters.</p>

<h2>Tickets vs. Remarks: When to Use Each</h2>

<table>
  <thead>
    <tr>
      <th>Use Ticket When...</th>
      <th>Use Remark When...</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Issue requires external followup</td>
      <td>Issue is internal or informational</td>
    </tr>
    <tr>
      <td>You need to track in a PSA system</td>
      <td>No PSA ticket is needed</td>
    </tr>
    <tr>
      <td>Customer action is required</td>
      <td>No action is required</td>
    </tr>
    <tr>
      <td>Issue will take days/weeks to resolve</td>
      <td>Issue is temporary (hours/days)</td>
    </tr>
    <tr>
      <td>You need structured tracking (ticket code, formal resolution)</td>
      <td>Quick notes or documentation are sufficient</td>
    </tr>
  </tbody>
</table>

<h2>Ticket & Remark Indicators</h2>

<p>In the Daily Jobs view and Job History pages, active tickets and remarks are indicated with icons:</p>

<ul>
  <li><strong>🎫 Ticket icon:</strong> Job has one or more active tickets</li>
  <li><strong>💬 Remark icon:</strong> Job has one or more active remarks</li>
</ul>

<p>These indicators help you quickly identify jobs with known issues during daily review.</p>

<h2>Common Workflows</h2>

<h3>Creating a Ticket for Recurring Failure</h3>

<ol>
  <li>Notice the same job failing in Daily Jobs for 3+ days</li>
  <li>Click on the job to open Run Checks modal</li>
  <li>Click <strong>Create Ticket</strong></li>
  <li>Enter ticket code: "CUST-12345" (from your PSA)</li>
  <li>Description: "Daily backup fails - server disk full"</li>
  <li>Active from date: Select the date of the first failure</li>
  <li>Create the ticket</li>
  <li>The job now shows 🎫 in Daily Jobs, indicating it's being tracked</li>
</ol>

<h3>Adding a Remark for Planned Maintenance</h3>

<ol>
  <li>Customer notifies you of planned maintenance on Friday</li>
  <li>Go to Daily Jobs → Friday's date</li>
  <li>Click on the customer's backup job</li>
  <li>Click <strong>Create Remark</strong></li>
  <li>Body: "Planned maintenance - server will be offline from 18:00-22:00. Backup failures expected."</li>
  <li>Create the remark</li>
  <li>On Friday, the job shows 💬, reminding you maintenance is planned</li>
  <li>After Friday, resolve the remark</li>
</ol>

<h3>Resolving a Ticket After Customer Action</h3>

<ol>
  <li>Customer confirms they've freed up disk space</li>
  <li>Monitor Daily Jobs - backup succeeds for 2+ days</li>
  <li>Go to <strong>Tickets</strong> page</li>
  <li>Find the ticket for this issue</li>
  <li>Click <strong>Resolve</strong></li>
  <li>The 🎫 indicator disappears from the job in Daily Jobs</li>
</ol>

<h3>Reviewing Historical Tickets</h3>

<ol>
  <li>Go to <strong>Tickets</strong> page</li>
  <li>Change Status filter to "All"</li>
  <li>Review resolved tickets to identify patterns (recurring issues, common problems)</li>
  <li>Use this data to improve backup configurations or create preventive overrides</li>
</ol>

<h2>Best Practices</h2>

<ul>
  <li><strong>Create tickets promptly:</strong> Don't wait for issues to escalate - create tickets when problems first appear</li>
  <li><strong>Use descriptive ticket codes:</strong> Reference your PSA system for easy correlation</li>
  <li><strong>Set accurate "Active from" dates:</strong> This ensures the ticket shows on the correct historical runs</li>
  <li><strong>Resolve tickets promptly:</strong> Don't leave stale tickets active after issues are fixed</li>
  <li><strong>Use remarks for temporary issues:</strong> Don't create formal tickets for short-term problems</li>
  <li><strong>Link tickets to multiple runs:</strong> As the same issue affects new runs, link them to the existing ticket</li>
  <li><strong>Review ticket list monthly:</strong> Identify long-running issues that need escalation</li>
  <li><strong>Use remarks for documentation:</strong> If you investigate an alert and determine it's not an issue, add a remark explaining why</li>
</ul>

<h2>Integration with Autotask</h2>

<p>If Autotask integration is enabled, you can manually create tickets in Autotask PSA for backup failures. When creating a ticket from the Run Checks modal, BackupChecks can create a corresponding ticket in Autotask and maintain a link between the internal ticket record and the Autotask ticket ID.</p>

<p>BackupChecks monitors Autotask for ticket status changes and can automatically resolve internal tickets when the corresponding Autotask ticket is resolved or deleted.</p>

<p>See <a href="{{ url_for('documentation.page', section='autotask', page='setup-configuration') }}">Autotask Integration</a> for details on setup and PSA ticket synchronization.</p>

<h2>Troubleshooting</h2>

<h3>Ticket Indicator Not Showing on Job</h3>

<ul>
  <li>Verify the ticket is <strong>Active</strong> (not resolved)</li>
  <li>Check the ticket's <strong>Active from date</strong> - it must be on or before the date you're viewing</li>
  <li>Verify the ticket scope matches the job (check customer, backup software, or job in the scope)</li>
  <li>Refresh the Daily Jobs page</li>
</ul>

<h3>Cannot Create Ticket or Remark</h3>

<ul>
  <li>Verify you have <strong>Admin</strong> or <strong>Operator</strong> role (Viewers cannot create tickets/remarks)</li>
  <li>Ensure all required fields are filled (ticket code, description, active from date)</li>
</ul>

<h3>Ticket Scope Affecting Wrong Jobs</h3>

<ul>
  <li>Review the ticket scopes on the ticket detail page</li>
  <li>Scopes may be broader than intended (e.g., customer scope affects all jobs for that customer)</li>
  <li>Edit the ticket (if supported) or resolve it and create a more specific ticket</li>
</ul>

<div class="doc-callout doc-callout-warning">
  <strong>⚠️ Ticket Editing:</strong><br>
  Based on the code, ticket editing is currently disabled. To modify a ticket, resolve the old ticket and create a new one with the correct information.
</div>

<h2>Next Steps</h2>

<ul>
  <li><a href="{{ url_for('documentation.page', section='backup-review', page='daily-jobs') }}">Daily Jobs View</a> - See how ticket and remark indicators appear in daily monitoring</li>
  <li><a href="{{ url_for('documentation.page', section='backup-review', page='run-checks-modal') }}">Run Checks Modal</a> - Create tickets and remarks while reviewing job runs</li>
  <li><a href="{{ url_for('documentation.page', section='backup-review', page='overrides') }}">Overrides & Exceptions</a> - Handle known issues with automated rules</li>
  <li><a href="{{ url_for('documentation.page', section='autotask', page='setup-configuration') }}">Autotask Integration</a> - Learn about PSA integration and ticket synchronization</li>
</ul>

{% endblock %}