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

{% block doc_content %}
<h1>Job Schedules</h1>

<p class="lead">
  Understand how BackupChecks automatically learns backup job schedules and uses them to predict expected runs.
</p>

<h2>Overview</h2>

<p>BackupChecks does <strong>not</strong> require you to manually configure backup schedules. Instead, the system <strong>automatically learns</strong> when backups are expected to run by analyzing historical backup run patterns.</p>

<p>This learned schedule information is used to:</p>

<ul>
  <li>Display jobs in <strong>Daily Jobs</strong> on days they are expected to run</li>
  <li>Identify missing backups (job expected today but hasn't run)</li>
  <li>Provide schedule visibility on the Jobs page</li>
  <li>Help operators focus on jobs that should have run</li>
</ul>

<div class="doc-callout doc-callout-info">
  <strong>💡 Key Concept:</strong><br>
  Schedules are <strong>learned automatically</strong> by analyzing backup run history. You do not configure schedules manually. After a few backup runs, BackupChecks will infer the schedule pattern.
</div>

<h2>How Schedule Learning Works</h2>

<p>BackupChecks uses historical backup run data to infer schedules through the following process:</p>

<ol>
  <li><strong>Data Collection:</strong> As backup reports arrive and create runs, the system records the date and time of each backup</li>
  <li><strong>Pattern Analysis:</strong> After several runs, the system analyzes the dates to identify patterns (e.g., daily, specific weekdays, monthly)</li>
  <li><strong>Schedule Inference:</strong> Once a pattern is detected, a schedule is assigned to the job</li>
  <li><strong>Continuous Learning:</strong> The schedule is updated as more runs are received to maintain accuracy</li>
</ol>

<h3>Minimum Data Required</h3>

<p>To learn a schedule, BackupChecks needs:</p>

<ul>
  <li><strong>At least 3-5 successful backup runs</strong> to establish a pattern</li>
  <li>Runs should be <strong>spread across multiple days</strong> (not all on the same day)</li>
  <li>Runs should follow a <strong>consistent pattern</strong> (e.g., always on Mondays and Thursdays)</li>
</ul>

<div class="doc-callout doc-callout-tip">
  <strong>💡 Learning Time:</strong><br>
  For a daily backup, the system can learn the schedule after 3-5 days of successful runs. For weekly backups, it may take 2-3 weeks to establish a reliable pattern.
</div>

<h2>Schedule Types</h2>

<p>BackupChecks can learn and display the following schedule types:</p>

<table>
  <thead>
    <tr>
      <th>Schedule Type</th>
      <th>Pattern</th>
      <th>Display Example</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><strong>Daily</strong></td>
      <td>Runs every day</td>
      <td>"Daily"</td>
    </tr>
    <tr>
      <td><strong>Weekly</strong></td>
      <td>Runs on specific days of the week</td>
      <td>"Weekly: Mon, Wed, Fri"</td>
    </tr>
    <tr>
      <td><strong>Monthly</strong></td>
      <td>Runs on specific day(s) of the month</td>
      <td>"Monthly: 1st, 15th"</td>
    </tr>
    <tr>
      <td><strong>Irregular</strong></td>
      <td>No consistent pattern detected</td>
      <td>"Irregular" or no schedule shown</td>
    </tr>
  </tbody>
</table>

<h2>Viewing Job Schedules</h2>

<p>You can view a job's learned schedule in several places:</p>

<h3>1. Jobs Page</h3>

<p>The Jobs page displays the learned schedule in the "Schedule" column for each job.</p>

<ol>
  <li>Navigate to <strong>Jobs</strong></li>
  <li>Locate the job in the list</li>
  <li>The "Schedule" column shows the learned pattern (e.g., "Daily", "Weekly: Mon, Wed, Fri")</li>
</ol>

<h3>2. Job Detail Page</h3>

<p>The job detail page shows more detailed schedule information:</p>

<ol>
  <li>Navigate to <strong>Jobs</strong></li>
  <li>Click on a job name to open the detail page</li>
  <li>The "Schedule Information" section shows:
    <ul>
      <li>Learned schedule type and pattern</li>
      <li>Expected run days/times</li>
      <li>Last run date</li>
      <li>Next expected run (if predictable)</li>
    </ul>
  </li>
</ol>

<h3>3. Daily Jobs Page</h3>

<p>Jobs with learned schedules appear on the Daily Jobs page on days they are expected to run.</p>

<ol>
  <li>Navigate to <strong>Daily Jobs</strong></li>
  <li>Jobs expected to run today are listed here</li>
  <li>The schedule determines which jobs appear on this page</li>
</ol>

<div class="doc-callout doc-callout-info">
  <strong>💡 Daily Jobs Behavior:</strong><br>
  A job will <strong>only appear</strong> on the Daily Jobs page if:
  <ul>
    <li>The system has learned a schedule for the job</li>
    <li>Today matches the learned schedule pattern</li>
    <li>The job is active (not archived)</li>
    <li>The customer is active</li>
  </ul>
  New jobs without learned schedules will not appear on Daily Jobs until a pattern is established.
</div>

<h2>Cove Workstations: Missed-Run Detection Disabled</h2>

<p>
  Schedule-based missed-run detection (synthetic <code>Missed</code> rows for past slots
  without a real run) is <strong>not</strong> applied to Cove Data Protection workstation jobs.
  Workstation devices are routinely powered off outside business hours, which produced
  false-positive Missed alerts. Cove <em>Server</em> and <em>Microsoft 365</em> jobs continue
  to use the regular missed-run logic.
</p>

<p>
  For workstation inactivity, enable colorbar-based offline detection in
  <strong>Settings → Integrations → Cove</strong>. See
  <a href="{{ url_for('documentation.page', section='integrations', page='cove-data-protection') }}">Cove Data Protection</a>
  for details.
</p>

<h2>Schedule Accuracy</h2>

<p>Schedule learning is based on pattern recognition and may not be 100% accurate in all cases:</p>

<h3>High Accuracy Scenarios</h3>

<ul>
  <li><strong>Daily backups:</strong> Run every day at approximately the same time</li>
  <li><strong>Weekly backups:</strong> Run on the same weekdays every week (e.g., Monday, Wednesday, Friday)</li>
  <li><strong>Monthly backups:</strong> Run on the same day(s) of the month (e.g., 1st and 15th)</li>
</ul>

<h3>Lower Accuracy Scenarios</h3>

<ul>
  <li><strong>Irregular backups:</strong> Manual backups with no consistent schedule</li>
  <li><strong>Variable schedules:</strong> Backup days change frequently (e.g., "first weekday of the month")</li>
  <li><strong>Recent changes:</strong> Backup schedule was recently changed and the system is still learning the new pattern</li>
</ul>

<div class="doc-callout doc-callout-warning">
  <strong>⚠️ Schedule Changes:</strong><br>
  If a backup schedule changes (e.g., from daily to weekly), the learned schedule will <strong>gradually update</strong> as new runs are received. During this transition period, the displayed schedule may be inaccurate. Allow a few weeks for the system to relearn the new pattern.
</div>

<h2>No Schedule Displayed</h2>

<p>If a job shows no schedule or "No schedule learned", it means:</p>

<ul>
  <li>The job was recently approved and doesn't have enough run history yet</li>
  <li>The job has an irregular pattern that the system cannot predict</li>
  <li>The job hasn't received enough consistent backup runs to establish a pattern</li>
  <li><strong>Information jobs:</strong> Jobs like "SSL certificate updated" or one-time maintenance tasks that run irregularly</li>
</ul>

<div class="doc-callout doc-callout-info">
  <strong>💡 Information Jobs:</strong><br>
  Some jobs are informational in nature (e.g., SSL certificate renewals, system updates) and do not run on a regular schedule. These jobs will never learn a schedule pattern and will not appear on the Daily Jobs page.
</div>

<p>In these cases:</p>
<ul>
  <li>The job will <strong>not appear</strong> on the Daily Jobs page (since we don't know when it's expected)</li>
  <li>Individual runs will still appear in <strong>Run Checks</strong> as they arrive</li>
  <li>You can still view the job on the <strong>Jobs</strong> page</li>
</ul>

<h2>Schedule Override and Customization</h2>

<p>BackupChecks does <strong>not</strong> currently support manual schedule configuration or overrides. All schedules are automatically learned from historical data.</p>

<div class="doc-callout doc-callout-info">
  <strong>📝 Future Feature:</strong><br>
  Manual schedule configuration and schedule overrides may be added in a future version. For now, rely on the automatic learning system.
</div>

<h2>Using Schedules in Daily Jobs</h2>

<p>The Daily Jobs page uses learned schedules to show which jobs are expected to run today. Each scheduled time is displayed with a status indicator:</p>

<figure>
  <img src="{{ url_for('static', filename='images/documentation/schedule-indicators.png') }}"
       alt="Daily Jobs Schedule Indicators" />
  <figcaption>Figure 1: Daily Jobs schedule showing time slots with run status indicators and run count badges</figcaption>
</figure>

<h3>Status Indicators</h3>

<table>
  <thead>
    <tr>
      <th>Indicator</th>
      <th>Meaning</th>
      <th>Action Needed</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><strong>Green dot</strong></td>
      <td>Job ran successfully at this time</td>
      <td>No action needed</td>
    </tr>
    <tr>
      <td><strong>Red dot</strong></td>
      <td>Job ran but failed at this time</td>
      <td>Investigate failure, create ticket if needed</td>
    </tr>
    <tr>
      <td><strong>White dot</strong></td>
      <td>Job expected but not yet run (time hasn't arrived yet)</td>
      <td>Wait - job is not yet overdue</td>
    </tr>
    <tr>
      <td><strong>Gray dot</strong></td>
      <td>Job expected but overdue (time has passed, no run received)</td>
      <td>Investigate - job may have failed to start</td>
    </tr>
  </tbody>
</table>

<h3>Run Count Badges</h3>

<p>When a job has run, a badge appears next to the status indicator showing how many runs occurred:</p>

<table>
  <thead>
    <tr>
      <th>Badge</th>
      <th>Color</th>
      <th>Meaning</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><strong>1 run</strong></td>
      <td>Gray</td>
      <td>Single backup run received for this time slot</td>
    </tr>
    <tr>
      <td><strong>3 runs</strong></td>
      <td>Blue/Cyan</td>
      <td>Multiple backup runs received for this time slot (stands out for attention)</td>
    </tr>
  </tbody>
</table>

<div class="doc-callout doc-callout-tip">
  <strong>💡 Workflow Tip:</strong><br>
  Use the Daily Jobs page as your primary monitoring dashboard. Check it daily to ensure all expected backups have run successfully:
  <ul>
    <li><strong>White dots:</strong> Not yet due - wait</li>
    <li><strong>Gray dots:</strong> Overdue - investigate immediately</li>
    <li><strong>Green dots with badges:</strong> Completed successfully</li>
    <li><strong>Blue badges (3+ runs):</strong> Multiple runs detected - verify this is expected</li>
  </ul>
</div>

<h3>Multiple Runs Per Time Slot</h3>

<p>Some jobs run multiple times at the same scheduled time (e.g., multiple backup sets, parallel jobs):</p>

<ul>
  <li>Each time slot shows a green dot when runs are successful</li>
  <li>The run count badge shows how many runs were received (e.g., "1 run", "3 runs")</li>
  <li>Multiple runs (3+) are highlighted with a <strong>blue/cyan badge</strong> to stand out</li>
  <li>This helps you quickly identify jobs with unusual activity</li>
</ul>

<h2>Schedule Learning Best Practices</h2>

<p>To help BackupChecks learn accurate schedules:</p>

<ul>
  <li><strong>Maintain Consistent Backup Schedules:</strong> Configure your backup software to run on consistent days/times</li>
  <li><strong>Allow Learning Time:</strong> Give the system at least a week or two to learn new job patterns</li>
  <li><strong>Monitor Daily Jobs:</strong> Use the Daily Jobs page to verify schedule accuracy</li>
  <li><strong>Keep Jobs Active:</strong> Regular backup runs help maintain schedule accuracy</li>
  <li><strong>Archive Inactive Jobs:</strong> Archive jobs that no longer run to avoid false "missing backup" alerts</li>
</ul>

<h2>Troubleshooting Schedule Issues</h2>

<h3>Schedule Not Appearing</h3>

<p><strong>Possible causes:</strong></p>
<ul>
  <li>Not enough backup runs yet (need 3-5 successful runs)</li>
  <li>Runs are too irregular to establish a pattern</li>
  <li>All runs occurred on the same day (need runs spread across multiple days)</li>
</ul>

<p><strong>Solution:</strong> Wait for more backup runs to accumulate. Ensure the backup software is running on a consistent schedule.</p>

<h3>Schedule Is Inaccurate</h3>

<p><strong>Possible causes:</strong></p>
<ul>
  <li>Backup schedule was recently changed</li>
  <li>Backup runs have been irregular or skipped</li>
  <li>Manual backups are interfering with schedule pattern</li>
</ul>

<p><strong>Solution:</strong> Allow time for the system to relearn the pattern based on recent runs. Ensure backups run consistently going forward.</p>

<h3>Job Not Appearing on Daily Jobs</h3>

<p><strong>Possible causes:</strong></p>
<ul>
  <li>No learned schedule exists for the job</li>
  <li>Today doesn't match the learned schedule pattern</li>
  <li>Job or customer is archived/inactive</li>
</ul>

<p><strong>Solution:</strong> Check the Jobs page to see if a schedule is learned. If not, wait for more runs to establish a pattern.</p>

<h2>Next Steps</h2>

<ul>
  <li><a href="{{ url_for('documentation.page', section='backup-review', page='daily-jobs') }}">Daily Jobs</a> - Monitor jobs expected to run today</li>
  <li><a href="{{ url_for('documentation.page', section='backup-review', page='run-checks') }}">Run Checks</a> - Review individual backup runs</li>
  <li><a href="{{ url_for('documentation.page', section='customers-jobs', page='approved-jobs') }}">Approved Jobs</a> - View and manage all approved jobs</li>
  <li><a href="{{ url_for('documentation.page', section='customers-jobs', page='configuring-jobs') }}">Configuring Jobs</a> - Learn how jobs are created</li>
</ul>

{% endblock %}