Skip to main content

Timespans

Timespans define periods of time.

There are three types of timespans:

Absolute Timespans​

  • Format: <RFC3339-Timestamp>-<RFC3339-Timestamp> or <RFC3339-Timestamp> - <RFC3339-Timestamp>
  • Example: 2024-07-29T08:30:00Z - 2024-07-29T16:00:00+02:00

See RFC3339 Timestamps for more information

Relative Timespans​

  • Format: <Weekday-From>-<Weekday-To> <Time-Of-Day-From>-<Time-Of-Day-To> <Timezone>

  • Examples:

    Mon-Fri 08:00-20:00 Asia/Tokyo          # From Monday to Friday: from 08:00 to 20:00
    Sat-Sun 00:00-24:00 UTC                 # On The Weekend: the entire day
    Mon-Fri 20:00-08:00 Australia/Sydney    # From Monday to Friday: from Midnight to 08:00 and from 20:00 until end of day
    Mon-Sun 00:00-00:00 America/New_York    # The timespan never matches, this would not do anything
    Mon-Tue 20:00-24:00 Africa/Johannesburg # On Monday and Tuesday: from 20:00 to midnight
    Mon-Tue 20:00-00:00 Europe/Amsterdam    # On Monday and Tuesday: from 20:00 to midnight

You can reverse the times (example: 20:00-08:00). This makes the timespan match the time from start of day until 08:00 and from 20:00 until the end of day.

Relative timespans can also be defined without a timezone, without a week frame or with both missing. This setup however requires a global timezone and/or week frame to be set, otherwise the timespan would not be valid and scaling will result in an error.

  • Format: <Time-Of-Day-From>-<Time-Of-Day-To> <Timezone>
  • Requires: DEFAULT_WEEKFRAME environment variable to be set
  • Examples:
    08:00-20:00 Asia/Tokyo                # On the days defined in the global week frame: from 08:00 to 20:00
    00:00-24:00 UTC                       # On the days defined in the global week frame: the entire day
  • Format: <Weekday-From>-<Weekday-To> <Time-Of-Day-From>-<Time-Of-Day-To>
  • Requires: DEFAULT_TIMEZONE environment variable to be set
  • Examples:
    Mon-Fri 08:00-20:00                   # From Monday to Friday: from 08:00 to 20:00 in the timezone defined in the global timezone
    Sat-Sun 00:00-22:00                   # On the weekend: from 08:00 to 22:00 in the timezone defined in the global timezone
    08:00-20:00                           # On the days defined in the global weekframe: from 08:00 to 20:00 defined in the global timezone
    00:00-14:00                           # On the days defined in the global weekframe: from 00:00 to 14:00 defined in the global timezone

Valid Values​

Weekdays​

Case-insensitive:

  • Mon
  • Tue
  • Wed
  • Thu
  • Fri
  • Sat
  • Sun

Timezones​

The timezones are from the IANA Time Zone database.

note

The IANA Time Zone database mainly supports regional/city timezones (example: Europe/Berlin, America/Los_Angeles) instead of abbreviations (example: CEST, PST, PDT). It supports some abbreviations like CET, MET and PST8PDT but these (not including UTC) shouldn't be used, and only exist for backwards compatibility.

Time of Day​

Values from: 00:00 - 24:00

Always/Never/True/False​

Case-insensitive:

  • Always/True: always matches
  • Never/False: never matches, acts as a non-unset state
tip

Never/False and other non-unset states can be useful for disabling the value if set by less specific scopes.

Complex Timespans​

Sometimes its not enough to have just one timespan, in those cases you can define multiple.

  • Syntax: <TIMESPAN>,<TIMESPAN>,<TIMESPAN> or <TIMESPAN>, <TIMESPAN>, <TIMESPAN>
  • Example: Sat-Sun 00:00-24:00 Europe/Berlin, Mon-Fri 20:00-08:00 Europe/Berlin - This expression matches the time over the weekend and at night.

You can mix any type of timespan.

note

Although you could mix boolean timespans with the other ones, this is not a valid use case and might be changed to a compatibility conflict in the future.