DevOps Intermediate

AutoSys Calendars: The 1 Schedule That Stops Jobs at Year-End

Q: How do I create an AutoSys calendar?

Use the autocal_asc command to create, update, and manage calendar definitions. You can run it interactively or redirect a calendar definition file to it. The WCC web interface also has a calendar management section.

Q: What is exclude_calendar in AutoSys?

exclude_calendar specifies dates on which the job should NOT run, even if those dates are in the run_calendar or match days_of_week. It's commonly used to exclude public holidays from a business day schedule.

Q: What happens when both days_of_week and run_calendar are set?

When both are set, the job runs on days that satisfy BOTH conditions — the day must be in the run_calendar AND must be one of the specified days_of_week. This is typically not intended; usually you set one or the other.

Q: Do AutoSys calendars need to be updated each year?

Yes, if you're using standard calendars with explicit date lists, they must be updated to include the new year's dates. Many organisations automate this as an annual administrative task at year-end. Extended calendars (logical rules) never need date updates.

Q: What's the difference between standard and extended calendars?

Standard calendars are explicit date lists (e.g., dates: 20260101, 20260102). Extended calendars are logical rules (e.g., last_weekday_of_month: jan,feb,mar). Extended calendars are more maintainable because they don't require annual updates. Use extended for recurring patterns (month-end, quarter-end), standard for one-off or static date lists.

📅 March 19, 2026 ⏱ 3 min read 🎯 Intermediate

Where developers are forged. · Structured learning · Free forever.

📍 Part of: AutoSys → Topic 15 of 30

AutoSys run_calendar explained with real outage stories.

⚙️ Intermediate — basic DevOps knowledge assumed

In this tutorial, you'll learn

AutoSys run_calendar explained with real outage stories.

AutoSys calendars are named date lists that let you schedule jobs on business days, holidays, or any custom date pattern.
Use run_calendar to specify which days to run; use exclude_calendar to skip specific dates like public holidays.
Calendars are created and managed with the autocal_asc command.

thecodeforge.io

Calendar-Based Scheduling

Autosys Calendars Run Calendar

✦ Plain-English analogy ✦ Real code with output ✦ Interview questions

⚡Quick Answer

AutoSys calendar = named date list for scheduling jobs on business days, holidays, or custom patterns — standard (explicit dates) or extended (logical rules)
Key components: run_calendar (run on these dates), exclude_calendar (skip these dates), autocal_asc (calendar management command)
Performance: Calendar lookup is O(1) hash check per job evaluation; 10,000 jobs with calendars = minimal overhead
Production trap: Calendar with explicit dates not updated at year-end — jobs scheduled on expired calendar never run again
Biggest mistake: Setting both days_of_week AND run_calendar — runs only on intersection (days that satisfy both), often unintended, causes jobs to never run

🚨 START HERE

Calendar Debug Cheat Sheet

Fast diagnostics for calendar issues in production AutoSys environments.

🟡

Job not running on expected date — INACTIVE

Immediate ActionCheck if run_calendar contains today's date

Commands

autorep -J job_name -d | grep -E 'run_calendar|exclude_calendar'

autocal_asc -r $(autorep -J job_name -q | grep run_calendar | awk '{print $2}')

Fix NowIf calendar expired (no dates for current year), create new calendar with current year dates and update job. Or use extended calendar with business day logic.

🟡

Job runs on holiday — expected skip

Immediate ActionCheck if exclude_calendar is set and contains holiday date

Commands

autorep -J job_name -d | grep exclude_calendar

autocal_asc -r exclude_calendar_name | grep $(date +%Y%m%d)

Fix NowAdd holiday date to exclude_calendar: `autocal_asc` interactive mode to insert date. Or create separate holiday calendar and apply to job.

🟡

Job runs on weekend — unexpected

Immediate ActionCheck if run_calendar or days_of_week includes weekend

Commands

autorep -J job_name -d | grep -E 'run_calendar|days_of_week'

autocal_asc -r calendar_name | grep -E 'Saturday|Sunday'

Fix NowRemove weekend dates from run_calendar. If using days_of_week, change to mon-fri only. If both set, job runs on intersection (harder to debug).

🟡

autocal_asc error 'Duplicate date'

Immediate ActionCheck calendar for duplicate dates

Commands

autocal_asc -r calendar_name | sort | uniq -d

echo 'Dates must be unique and sorted in ascending order'

Fix NowDelete duplicate dates using autocal_asc delete mode. Recreate calendar with unique dates. Ensure dates are in YYYYMMDD format and sorted.

🟡

Calendar not found — JIL error on update

Immediate ActionCheck case-sensitivity and existence

Commands

autocal_asc -r % | grep -i calendar_name

echo 'Calendar names are case-sensitive. Business_Days != business_days'

Fix NowRecreate calendar with consistent lowercase name. Update job with correct case. Use exact name from `autocal_asc -r %` output.

Production Incident

The Calendar That Died on December 31st

A critical financial job was scheduled with run_calendar: business_days_2025. On January 2, 2026, the job didn't run. The calendar only contained 2025 dates. No one had updated it for the new year. The finance team discovered the missing reconciliation on January 5th.

SymptomThe monthly reconciliation job normally ran on the first business day of every month. On January 2, 2026 (first business day of the year), the job remained INACTIVE. autorep showed the job with run_calendar: business_days_2025. The operator assumed the job was ON_HOLD or had a condition issue. After 2 hours of checking dependencies, they realised the calendar name itself was year-specific.

AssumptionThe team assumed that 'business_days_2025' was a dynamic calendar that updated automatically. They didn't know that standard calendars are static date lists that must be manually refreshed. The previous admin had left the company 6 months ago, and no one knew the calendar needed annual maintenance. The team also didn't have monitoring for calendar expiry.

Root causeThe calendar business_days_2025 was created as a standard calendar with explicit dates for 2025. On January 1, 2026, the calendar had no dates. The job's date condition checked the run_calendar, found no match, and remained INACTIVE. No alarm fired because the job didn't fail — it just never started. The team had no automated process to update calendars annually. The calendar naming convention included the year, but no reminder or audit existed to create business_days_2026 before January 1.

Fix1. Created new calendar business_days_2026 with 2026 business dates. 2. Updated job JIL: update_job: monthly_recon run_calendar: business_days_2026. 3. Automated calendar creation: added a scheduled AutoSys job that runs on December 15 each year to create next year's business day calendar using a script that calculates business dates (excluding weekends and holidays). 4. Added a monitoring alert: weekly check for any job with run_calendar containing previous year's dates, flagging them for review. 5. Changed naming convention to business_days (without year) for dynamic calendars using extended calendar logic (when available).

Key Lesson

Standard calendars are static date lists. They do not auto-update. You must refresh them annually.Calendar names with years (e.g., business_days_2025) are a ticking time bomb. Use year-less names and update the calendar content, not the name.A job that never starts is worse than a job that fails — there's no alarm, no error log, just silence.Automate calendar creation before year-end. A scheduled job that runs in December can create next year's calendars automatically.

Production Debug Guide

Symptom → Action mapping for common calendar failures in production AutoSys environments.

Job not running on expected date — status INACTIVE, no failure→Check run_calendar: does it include today's date? autorep -J job_name -d | grep run_calendar. Then verify calendar contents: autocal_asc -r calendar_name. If calendar is year-specific (e.g., 2025), it may have expired.

Job runs on holiday when it should skip→Check exclude_calendar: is holiday calendar applied? autorep -J job_name -d | grep exclude_calendar. Verify exclude_calendar contains the holiday date: autocal_asc -r exclude_calendar_name.

Job runs on weekend but should only run weekdays→Check if run_calendar includes weekends. Verify calendar definition. Also check if days_of_week is set — if both run_calendar and days_of_week are set, job runs on intersection, not union.

Calendar creation fails — autocal_asc errors→Check for duplicate calendar name: autocal_asc -r calendar_name. Ensure date format is YYYYMMDD. For standard calendars, dates must be sorted. Check for trailing commas in date list.

Job runs but shouldn't — calendar logic wrong→Verify run_calendar and exclude_calendar combination. A date in exclude_calendar overrides run_calendar. Check if exclude_calendar is empty (no dates). Ensure calendar names are case-sensitive and spelled correctly in JIL.

Time-based scheduling with days_of_week covers most simple cases, but enterprise batch processing often needs more nuanced scheduling. Month-end jobs that only run on the last business day. Jobs that must skip public holidays. Quarter-end runs. AutoSys calendars solve exactly this.

There are two calendar types: standard calendars (a list of dates) and extended calendars (built from logical rules). Both are defined using the autocal_asc command or through the WCC UI.

But calendars are dangerous. A calendar with explicit dates for 2025 will stop working on January 1, 2026. Jobs that depend on it will never run again. The intersection between days_of_week and run_calendar is another trap — if you set both, the job runs only on days that satisfy BOTH conditions, which is rarely what you intend.

By the end you'll know exactly how to create and manage calendars, use run_calendar and exclude_calendar correctly, avoid the year-end trap, and debug why a job isn't running on days you expect it to.

Standard calendars — a list of dates

A standard calendar is simply a named list of dates. Jobs with run_calendar: your_calendar_name will run on those dates and only those dates.

io/thecodeforge/autosys/create_calendar.sh · BASH

1234567891011121314

# Create a standard calendar using autocal_asc (interactive or file mode)
autocal_asc << 'EOF'
insert_calendar: business_days_2026
calendar_type: standard
dates: 20260102, 20260105, 20260106, 20260107, 20260108, 20260109
/* ... continuing for all business days in 2026 ... */
EOF

# Create a holiday exclusion calendar
autocal_asc << 'EOF'
insert_calendar: uk_public_holidays_2026
calendar_type: standard
dates: 20260101, 20260403, 20260406, 20260504, 20260525, 20260831, 20261225, 20261228
EOF

📊 Production Insight

Standard calendars with explicit dates are simple but require annual maintenance. Date lists must be sorted and contain no duplicates.

For large calendars (all business days of the year), creating them manually is error-prone. Automate generation with a script that calculates dates from business rules.

Rule: For long-term maintainability, use extended calendars (calendars built from logical rules like 'last business day of month') instead of explicit date lists.

🎯 Key Takeaway

Standard calendars are explicit date lists. Simple to understand but require annual updates.

Use extended calendars (logical rules) for dynamic date patterns like 'last business day of month'.

Rule: Automate calendar generation with scripts. Never maintain 365-date calendars by hand.

Using run_calendar and exclude_calendar

Once calendars are defined, apply them to jobs with run_calendar (run on these days) and exclude_calendar (don't run on these days).

io/thecodeforge/autosys/calendar_job.jil · BASH

1234567891011121314151617181920

/* Run on all business days in 2026, but skip UK public holidays */
insert_job: daily_settlement
job_type: CMD
command: /scripts/settlement.sh
machine: finance-server
owner: finuser
date_conditions: 1
start_times: "18:00"
run_calendar: business_days_2026
exclude_calendar: uk_public_holidays_2026

/* Month-end job: runs only on last business day of each month */
insert_job: month_end_close
job_type: CMD
command: /scripts/month_end.sh
machine: finance-server
owner: finuser
date_conditions: 1
start_times: "20:00"
run_calendar: month_end_2026

🔥Calendars need to be updated annually

Standard calendars with explicit dates need to be refreshed each year. Most enterprises have an automated process or a dedicated admin task to update business day and holiday calendars at the start of each year.

📊 Production Insight

exclude_calendar overrides run_calendar. A date in exclude_calendar will never run, regardless of run_calendar.

When both run_calendar and days_of_week are set, the job runs only on the INTERSECTION (dates that satisfy both). This is rarely intended.

Rule: Use run_calendar OR days_of_week, never both. If you need both, it usually means your calendar logic is wrong.

🎯 Key Takeaway

run_calendar specifies which days to run; exclude_calendar skips specific dates (e.g., holidays).

exclude_calendar overrides run_calendar. A date in exclude_calendar never runs.

Rule: Avoid setting both days_of_week and run_calendar — the job runs only on the intersection, which is rarely intended.

Viewing and managing existing calendars

You can query, list, and report on existing calendars using autocal_asc in report mode. This is useful when you need to audit which jobs are using which calendars, or verify a calendar's dates before a major batch run.

io/thecodeforge/autosys/manage_calendars.sh · BASH

12345678910111213

# List all calendars in the AutoSys instance
autocal_asc -r %

# View dates in a specific calendar
autocal_asc -r business_days_2026

# Delete an obsolete calendar
autocal_asc << 'EOF'
delete_calendar: old_2025_holidays
EOF

# Find all jobs using a specific calendar
autorep -J % -q | grep -B5 'run_calendar: business_days_2026'

🔥Calendar names are case-sensitive

If you define a calendar as 'Business_Days_2026' but reference it in JIL as 'business_days_2026', AutoSys won't find it. Keep calendar names lowercase with underscores to match standard JIL naming conventions.

📊 Production Insight

autocal_asc -r % lists all calendars, but doesn't show which jobs use them. Use autorep -J % -q to find jobs referencing a calendar.

Audit quarterly: list calendars and check for any with year-old dates (e.g., 2025 calendars in 2026). These should be archived.

Rule: Implement a weekly job that runs autorep -J % -q | grep run_calendar | grep 2025 to alert on expired calendars before they cause job failures.

🎯 Key Takeaway

autocal_asc -r lists calendars and their dates. Use it to verify calendar contents before batch runs.

autorep -J % -q finds jobs using a specific calendar; essential for impact analysis before deleting a calendar.

Rule: Calendar names should be lowercase with underscores. Case-sensitivity is a common source of 'calendar not found' errors.

🗂 AutoSys Scheduling Methods

Choose based on scheduling complexity — days_of_week for simple, calendars for custom date patterns

Scheduling Method	Use When...	Attributes Used	Maintenance Burden	Example
days_of_week	Simple day-of-week rules (every weekday, every weekend)	days_of_week: mon-fri	Low (no annual updates)	Run every weekday
run_calendar	Custom date lists (business days, month-end, quarter-end)	run_calendar: calendar_name	High (requires annual calendar updates)	Run only on last business day of month
exclude_calendar	Skip specific dates (public holidays)	exclude_calendar: calendar_name	Medium (update holiday list annually)	Run business days except holidays
Both run_calendar + exclude_calendar	Business days minus holidays	run_calendar + exclude_calendar	High (both calendars need updates)	Run business days, skip Christmas
Extended calendar (logical rules)	Dynamic date patterns (last weekday of month, nth day of month)	calendar_type: extended	Low (rules are static, no date updates)	Last business day of each month

🎯 Key Takeaways

AutoSys calendars are named date lists that let you schedule jobs on business days, holidays, or any custom date pattern.
Use run_calendar to specify which days to run; use exclude_calendar to skip specific dates like public holidays.
Calendars are created and managed with the autocal_asc command.
Standard calendars with explicit dates must be updated annually — automate this process to avoid job failures.
Never set both days_of_week and run_calendar on the same job — they intersect, not union, leading to unexpected missing runs.

⚠ Common Mistakes to Avoid

✕Not updating standard calendars at year-end — jobs stop running

Symptom

Job remains INACTIVE on first business day of new year. autorep shows run_calendar with previous year. No alarm, no failure — just silence.

Fix

Automate calendar creation: scheduled job that runs in December to create next year's calendars. Use extended calendars (logical rules) instead of explicit date lists where possible. Add monitoring for calendars with expired dates.

✕Setting both days_of_week AND run_calendar on same job

Symptom

Job runs on fewer days than expected. Example: run_calendar includes Monday, days_of_week: mon-fri — job runs on Monday only. Operator assumes calendar logic is wrong.

Fix

Use run_calendar OR days_of_week, never both. If you need both, it usually means your calendar logic should incorporate the day-of-week rule (create a calendar that already excludes weekends).

✕Forgetting to create exclude_calendar before referencing it in JIL

Symptom

Job fails with error 'Calendar calendar_name not found' when inserting or updating. The JIL references a calendar that doesn't exist yet.

Fix

Always create calendars before referencing them in job definitions. Order of operations: autocal_asc first, then jil insert/update. Use version control for calendar definitions.

✕Using standard calendars where extended calendars would be more maintainable

Symptom

Team spends days each year manually updating 500-date business calendars. Errors common, missing dates cause job failures.

Fix

Use extended calendars for logical rules: 'last business day of month', 'first Monday of month', etc. These never need date updates. Reserve standard calendars for truly one-off date lists.

✕Case mismatch between calendar definition and run_calendar attribute

Symptom

Job fails with 'Calendar Business_Days not found' even though calendar exists as 'business_days'. Calendar names are case-sensitive in AutoSys.

Fix

Adopt a naming convention: all lowercase, underscores for spaces. Use autocal_asc -r % to see exact case of existing calendars. Copy-paste calendar name into JIL.

Interview Questions on This Topic

QWhat is a run_calendar in AutoSys?JuniorReveal
run_calendar is a job attribute that specifies a named AutoSys calendar. The job will only run on the dates defined in that calendar, rather than using the standard days_of_week scheduling. Calendars can be standard (explicit date list) or extended (logical rules like 'last business day of month'). When run_calendar is set, the job ignores days_of_week. A date in exclude_calendar overrides run_calendar — the job will not run even if the date is in run_calendar.
QWhat is the difference between run_calendar and exclude_calendar?JuniorReveal
run_calendar specifies which dates the job should run on. exclude_calendar specifies dates the job should NOT run on, even if those dates are in run_calendar or match days_of_week. Usage: run_calendar = business_days_2026, exclude_calendar = uk_public_holidays_2026. The job runs on business days except public holidays. exclude_calendar overrides run_calendar. Both attributes can be used together, but run_calendar and days_of_week cannot be combined meaningfully (they intersect).
QHow do you create a calendar in AutoSys?Mid-levelReveal
Use the autocal_asc command to create, update, and manage calendar definitions. You can run it interactively, or redirect a calendar definition file to it. Example: autocal_asc << 'EOF' then insert_calendar: calendar_name calendar_type: standard dates: 20260101, 20260102 EOF. For extended calendars, use calendar_type: extended and define rules like last_weekday_of_month: jan,feb,mar. The WCC web interface also has a calendar management section. Calendars are stored in the Event Server database.
QWhat is the autocal_asc command used for?Mid-levelReveal
autocal_asc is the AutoSys command-line tool for managing calendars. You can insert new calendars (insert_calendar: name), update existing calendars (update_calendar: name), delete calendars (delete_calendar: name), and report on calendars (-r calendar_name or -r % for all). It supports both interactive input and file redirection. The command validates date formats (YYYYMMDD), checks for duplicates, and ensures dates are sorted in standard calendars. Report mode (-r) is useful for auditing calendar contents and verifying dates before batch runs.
QWhat happens if both days_of_week and run_calendar are set on a job?SeniorReveal
When both are set, the job runs on days that satisfy BOTH conditions — the intersection of days_of_week and run_calendar. For example, if run_calendar includes January 1 (a Thursday) and days_of_week: mon-fri, the job runs on that day. But if run_calendar includes a Saturday but days_of_week excludes Saturday, the job won't run. This is rarely intended — usually you set one or the other. Using both can cause confusion because the job runs on fewer days than expected. The AutoSys documentation recommends using only one method per job. If you need both, consider creating a calendar that already incorporates the day-of-week logic.

Frequently Asked Questions

What is run_calendar in AutoSys?

run_calendar is a job attribute that specifies a named AutoSys calendar. The job will only run on the dates defined in that calendar, rather than using the standard days_of_week scheduling.

How do I create an AutoSys calendar?

Use the autocal_asc command to create, update, and manage calendar definitions. You can run it interactively or redirect a calendar definition file to it. The WCC web interface also has a calendar management section.

What is exclude_calendar in AutoSys?

exclude_calendar specifies dates on which the job should NOT run, even if those dates are in the run_calendar or match days_of_week. It's commonly used to exclude public holidays from a business day schedule.

What happens when both days_of_week and run_calendar are set?

When both are set, the job runs on days that satisfy BOTH conditions — the day must be in the run_calendar AND must be one of the specified days_of_week. This is typically not intended; usually you set one or the other.

Do AutoSys calendars need to be updated each year?

Yes, if you're using standard calendars with explicit date lists, they must be updated to include the new year's dates. Many organisations automate this as an annual administrative task at year-end. Extended calendars (logical rules) never need date updates.

What's the difference between standard and extended calendars?

Standard calendars are explicit date lists (e.g., dates: 20260101, 20260102). Extended calendars are logical rules (e.g., last_weekday_of_month: jan,feb,mar). Extended calendars are more maintainable because they don't require annual updates. Use extended for recurring patterns (month-end, quarter-end), standard for one-off or static date lists.

🔥

Naren Founder & Author

Developer and founder of TheCodeForge. I built this site because I was tired of tutorials that explain what to type without explaining why it works. Every article here is written to make concepts actually click.

About Naren Get in touch

Forged with 🔥 at TheCodeForge.io — Where Developers Are Forged