Calendars

A calendar is a named set of time periods that can be attached to a scheduled task to control when its executions are triggered.

Calendars address the inherent limitations of cron expressions, which cannot natively express rules such as “skip public holidays”, “run only during a fiscal quarter or audit window”, or “execute only on working days for a given country”.

Calendars can be defined at two levels:

  • Global level: created and managed by administrators, available to all projects.
  • Project level: created and managed by project managers, available only to the tasks of that project.

Calendar modes

When a calendar is attached to a scheduled task, it operates in one of two modes:

Exclude

Scheduled executions whose trigger time falls within a calendar period are skipped.

This is useful for defining blackout windows, such as:

  • Public holidays
  • Maintenance freeze periods

For example, attaching a “Public holidays” calendar in Exclude mode to a daily report task will prevent it from running on those days.

Restrict

Scheduled executions are only triggered when their time falls within a calendar period.

This is useful for constraining tasks to specific windows, such as:

  • Variable business hours (e.g. Monday–Thursday 9 AM–6 PM, Friday 9 AM–5 PM)
  • A specific maintenance slot

For example, attaching a “Business hours” calendar in Restrict mode to a task scheduled every 5 minutes will ensure it only runs during the defined time windows (including asymmetric schedules like shorter Fridays) without needing multiple cron expressions.

Calendar types

Two types of calendars are available:

  • Internal: periods are managed directly within CTFreak. They can be imported in bulk from an iCal file (recommended), or entered manually one by one.
  • URL: periods are synchronized from a remote iCal feed. This lets CTFreak stay in sync with an external calendar: Google Calendar, Outlook, Nextcloud, or any service publishing a standard iCal feed URL.

Internal calendar

Create an internal calendar

To create an internal calendar, go to Calendars → New calendar and select Internal.

Fill in the following fields:

  • Name: the name of the calendar.
  • Description: an optional description in markdown format.

Add periods manually

Once the calendar is created, go to its detail page and use New period to add a time period by specifying a start date/time and an end date/time.

Import from an iCal file

You can also populate the calendar by importing a standard iCal file (.ics).

On the calendar detail page, use Import iCal to upload your file. CTFreak will extract the events and add them as periods to the calendar.

See iCal import and synchronization for details on how iCal data is handled.

Generate an iCal file with an AI assistant

AI assistants such as Claude or ChatGPT can generate valid .ics files from a plain-language description. This is particularly useful for custom or one-off calendars that are not available online.

Ask the assistant to produce an iCal file and import it using Import iCal.

Example prompts:

Generate public holidays for a country and year:

Generate a valid iCal file (.ics) containing all public holidays in France for 2026, timezone Europe/Paris.

Generate a recurring maintenance window:

Generate a valid iCal file (.ics) with a recurring event every first Sunday of the month
from 5:00 AM to 7:00 AM, for the year 2026 and 2027, timezone America/New_York.

Generate asymmetric business hours:

Generate a valid iCal file (.ics) with weekly recurring events for the next 5 years,
timezone Australia/Sydney:
- Monday to Thursday: 9:00 AM to 6:00 PM
- Friday: 9:00 AM to 5:00 PM

URL calendar

Create a URL calendar

To create a URL calendar, go to Calendars → New calendar and select URL.

Fill in the following fields:

  • Name: the name of the calendar.
  • Description: an optional description in markdown format.
  • URL: the iCal feed URL to synchronize from.
  • Scheduled sync: enable automatic synchronization on a cron schedule.
  • Cron expression (if scheduled sync is enabled): the synchronization frequency, using this format.

For example, to synchronize the feed every 4 hours:

0 */4 * * *

Manual synchronization

Regardless of the scheduled sync setting, you can trigger a synchronization at any time from the calendar detail page using the Sync button.

Sync status

After each synchronization attempt, CTFreak reports the result:

  • DONE: the feed was fetched and the periods were updated successfully.
  • FAILED: the synchronization failed (network error, invalid feed, etc.). The previously synchronized periods remain in place.

See iCal import and synchronization for details on how iCal data is handled.

iCal import and synchronization

The following rules apply both when importing an iCal file into an internal calendar and when synchronizing a URL calendar from a remote feed.

Supported iCal features

  • All-day events
  • Floating times (events without an explicit timezone)
  • X-WR-TIMEZONE calendar property for default timezone

Time window

Only periods that fall within a window of 30 days in the past to 10 years in the future are kept. A period is kept if its end date is after today − 30 days and its start date is before today + 10 years. Periods outside this window are ignored.

This limit also applies to recurring events: only occurrences expanded within the window are kept.

Overlapping periods

Overlapping periods are automatically merged into a single continuous period. The calendar always stores a minimal, non-overlapping set of periods sorted by start time.

Useful resources

Free iCal files or feeds are widely available online. Here are a few sources:

  • Office Holidays: public holidays for most countries, downloadable as iCal files. Useful for building country-specific blackout calendars.
  • CalendarLabs: national + regional/local holidays + financial market holidays (NYSE, LSE, Euronext, TSX, ASX, etc.)
  • WorldPublicHoliday: iCal feeds for 252 countries, downloadable or subscribable
  • data.gouv.fr