Controlling When Jobs Run with Time Settings

Understanding Time Settings

Jobs can run:

As soon as possible : No time constraint, runs when resources available

At specific time : Earliest time job may run

Repeating : Automatically reschedules after each run

Setting Run Time

Command line:

bash

# Run tomorrow at 3:00 AM
btr -t "03:00 tomorrow" script.sh

# Run on specific date
btr -t "2026-02-15 14:30" script.sh

# Run at specific time today
btr -t "18:00" script.sh

In btq:

1. Select job
2. Press T (time)
3. Navigate to time/date fields
4. Edit values
5. Press Q to save

Repeat Specifications

Jobs can repeat in units of:

Minutes : Every N minutes

Hours : Every N hours (default unit)

Days : Every N days

Weeks : Every N weeks

Monthsb (relative to beginning) : Every N months on specific day of month : Day 1-31 from month start

Monthse (relative to end) : Every N months on specific day before month end : Useful for "last working day" scenarios

Years : Every N years (1-99)

Simple Repeat Examples

Every 10 minutes:

bash

btr -r Minutes:10 script.sh

Every 2 hours:

bash

btr -r Hours:2 script.sh

Every day at same time:

bash

# Set time and repeat daily
btr -t "03:00" -r Days:1 backup.sh

Every 2 weeks:

bash

btr -t "09:00 Monday" -r Weeks:2 report.sh

Monthly Repeats

Months relative to beginning:

Run on specific day of each month:

bash

# Run on 5th day of every month
btr -t "10:00 2026-02-05" -r Monthsb:1:5 invoice.sh

# Run every 3 months on 15th
btr -t "14:00 2026-02-15" -r Monthsb:3:15 quarterly.sh

Months relative to end:

Run specific days before month end:

bash

# Run on last day of month
# If Feb (28 days), use 28
btr -t "23:00 2026-02-28" -r Monthse:1:28 month-end.sh

# Run on 2nd-to-last day of month
# If Feb (28 days), use 27
btr -t "23:00 2026-02-27" -r Monthse:1:27 pre-month-end.sh

Important: Day number for Monthse depends on current month's length. February (28 days) vs January (31 days) requires different day numbers.

Repeat Time Calculation

For most repeat types (Minutes/Hours/Days/Weeks/Years):

Next run time = Last run time + Repeat interval

Example - every 2 hours:

First run:  10:00
Next run:   12:00  (10:00 + 2 hours)
Next run:   14:00  (12:00 + 2 hours)

For monthly repeats:

Next run calculated from last run month, but uses specified day number.

Example - every month on 15th:

First run:  Feb 15 10:00
Next run:   Mar 15 10:00  (same day, next month)
Next run:   Apr 15 10:00  (same day, next month)

Avoiding Days

Jobs can skip specific days of week and holidays:

Available days to avoid:

• Sunday (Sun)
• Monday (Mon)
• Tuesday (Tue)
• Wednesday (Wed)
• Thursday (Thu)
• Friday (Fri)
• Saturday (Sat)
• Holidays (Hday) - from holiday calendar

Command line:

bash

# Run daily except weekends
btr -t "09:00" -r Days:1 -a "Sat,Sun" daily-job.sh

# Run every hour except weekends and holidays
btr -r Hours:1 -a "Sat,Sun,Hday" frequent.sh

# Run Monday-Friday only
btr -t "08:00" -r Days:1 -a "Sat,Sun" weekday.sh

In btq:

1. Select job
2. Press T (time)
3. Navigate to "Avoiding" row
4. Press Y to set day, N to unset
5. Press Q to save

Avoid Days Behavior

When next run falls on avoided day, job moves forward (or backward for Monthse):

Standard behavior (Minutes/Hours/Days/Weeks/Monthsb/Years):

Skip to next acceptable day:

Schedule: Daily 09:00, avoid Sat/Sun
Friday:     09:00 - Runs
Saturday:   09:00 - Skipped
Sunday:     09:00 - Skipped  
Monday:     09:00 - Runs (first acceptable day)

Monthse behavior:

Select earlier day in month:

Schedule: Last working day (Monthse:1:31), avoid Sat/Sun/Hday
Month ends Saturday (avoid): Use Friday instead
Month ends Sunday (avoid): Use Friday instead
Month ends holiday (avoid): Use previous working day

This makes "last working day of month" scheduling straightforward.

Working Day Patterns

Every working day at 8 AM:

bash

btr -t "08:00" -r Days:1 -a "Sat,Sun,Hday" daily-report.sh

Last working day of month:

bash

# Use Monthse with avoid days
btr -t "17:00 2026-02-28" -r Monthse:1:28 -a "Sat,Sun,Hday" month-end.sh

First working day of month:

bash

# Use Monthsb with avoid days
btr -t "08:00 2026-02-01" -r Monthsb:1:1 -a "Sat,Sun,Hday" month-start.sh

Every Monday:

bash

btr -t "09:00 Monday" -r Weeks:1 weekly.sh

Time Advancement on Error

Controls what happens to scheduled time when job fails:

Advance time (default behavior):

Next scheduled time advanced to next repeat interval even if job fails.

bash

# Job scheduled for 10:00, fails
# Next run still scheduled for 11:00 (if hourly repeat)
btr -r Hours:1 -E script.sh

Do not advance time:

Next scheduled time stays in past until job succeeds.

bash

# Job scheduled for 10:00, fails
# Next run still 10:00 until job succeeds
btr -r Hours:1 script.sh  # Default: advance time flag is NOT set

Enable "advance time on error" with -E flag:

bash

btr -r Hours:1 -E script.sh

Use cases:

Advance time: When job can be skipped if fails (non-critical monitoring) Don't advance: When job must succeed before continuing (critical data processing)

If Not Possible Options

When repeat time blocked by condition, job can:

Skip : Skip this iteration, advance to next repeat

Delay current : Wait until condition met, then run, keep same next repeat time

Delay all : Wait until condition met, then run, push all future repeats forward

Catch up : Run immediately when condition met, try to catch up missed repeats

Example scenarios:

bash

# Hourly job, blocked 2 hours by condition

Skip:         Miss 10:00, 11:00, next at 12:00
Delay current: Run at 11:30 (when unblocked), next at 12:00
Delay all:     Run at 11:30 (when unblocked), next at 12:30
Catch up:      Run 10:00, 11:00 immediately, back on schedule at 12:00

Retention

Jobs can be retained after running instead of deleted:

Run once and delete (default):

Job runs, then deleted from queue.

Run once and retain:

bash

btr -N script.sh

Job runs, state changes to "Done", remains on queue. Can be manually restarted.

Auto-delete after retention:

bash

# Delete 24 hours after last run
btr -N -D 24 script.sh

Complete Scheduling Examples

Daily Backup (Weekdays Only)

bash

btr -t "02:00" \
    -r Days:1 \
    -a "Sat,Sun,Hday" \
    -A "backup_status = Running @ Job start" \
    -A "backup_status = Complete @ Job completed" \
    -A "backup_status = Failed @ Job error" \
    /usr/local/bin/backup.sh

Month-End Processing

bash

# Last working day at 6 PM
btr -t "18:00 2026-02-28" \
    -r Monthse:1:28 \
    -a "Sat,Sun,Hday" \
    /usr/local/bin/month-end-close.sh

Frequent Monitoring (Every 5 Minutes, 24/7)

bash

btr -r Minutes:5 \
    /usr/local/bin/monitor-system.sh

Quarterly Report (Every 3 Months on 1st)

bash

btr -t "09:00 2026-03-01" \
    -r Monthsb:3:1 \
    -a "Sat,Sun,Hday" \
    /usr/local/bin/quarterly-report.sh

Best Practices

Always set time for repeating jobs:

Don't rely on "as soon as possible" - set explicit start time.

Use appropriate repeat units:

• Minutes: Very frequent monitoring (< hourly)
• Hours: Regular monitoring/processing
• Days: Daily operations
• Weeks: Weekly reports
• Months: Month-end, billing cycles
• Years: Annual processes

Consider avoid days:

For business processes, always avoid weekends and holidays.

Test monthly schedules:

Monthse with different month lengths can be tricky - test carefully.

Document special cases:

Comment jobs with unusual schedules:

bash

btr -t "18:00 2026-02-28" \
    -r Monthse:1:28 \
    -a "Sat,Sun,Hday" \
    -T "Month-end close - last working day" \
    month-end.sh