Uptime and downtime

Capacity blocks can be configured as uptime or downtime. Uptime is the period of time when a process is running which can include working hours and when resource groups are active. Downtime is the period of time when process is not running which can include idle time, holidays, and organizational downtime.

When an uptime capacity block is scheduled over or overlaps with a downtime block, admins have the option to override the downtime when scheduling uptime or keeping the existing downtime.

Recurring capacity blocks

Capacity blocks can be one-time blocks or scheduled to repeat daily, weekly, monthly, annually, or on a custom recurrence. User can define when the recurrence of the capacity block ends.

Types of capacity blocks

Capacity blocks can be created an an organization level for all-company holidays, working hours, or overarching time blocks. Capacity blocks can also be created at a resource group level so that uptime or downtime can be specific to work centers. Schedules for individual resources which can be users or assets can also be configured through capacity blocks.

Cron Expressions

Capacity blocks use a modified cron syntax to store recurring blocks. For advanced logic not achievable with the user interface, you can manually enter a cron expression.

By default, cron syntax is 5 or 6 fields separated by spaces. The fields are as follows:

# ┌───────────── second (0 - 59) (optional, missing for 5 fields)
# │ ┌───────────── minute (0 - 59)
# │ │ ┌───────────── hour (0 - 23)
# │ │ │ ┌───────────── day of the month (1 - 31)
# │ │ │ │ ┌───────────── month (1 - 12)
# │ │ │ │ │ ┌───────────── day of the week (0 - 6) (Sunday to Saturday)
# │ │ │ │ │ │
# │ │ │ │ │ │
# * * * * * *

Any 5 or 6 field expressions will be resolved with this logic. We have extended this syntax to include three more fields, any expression in excess of 6 fields:

# ┌───────────── year (1 - infinity)
# │ ┌───────────── days since epoch (0 - infinity) (0 = 1-Jan-1970)
# │ │ ┌───────────── months since epoch (1 - infinity) (1 = Jan 1970)
# │ │ │
# │ │ │
# * * *

The “year” field allows us to specify one-off events in cron, and every X years events. The “days/months since epoch” field allow us to specify every X days. Using some operations, we can make weeks since epoch, using grouping in cron.

Calculating days since epoch

The millisecond timestamp for the start of 1.1.1970 in the local timezone will be marked as localEpoch. This is not necessarily 0 in the unix epoch, due to timezones. For the moment of time we’re observing, labeled target, let us keep the date part, and replace the time part with noon. This way we have some leeway when calculating the timestamp delta, as DST switches can mess with exact alignment.

Logic:

const MILLIS_IN_DAY = 24 * 3600 * 1000;
const targetTimestamp = target.set({ hour:12, minute:0, second: 0, millisecond: 0}).toMillis();
const daysPassed = Math.floor((targetTimestamp - localEpoch) / MILLIS_IN_DAY);

Value groups

Assuming we mark literal values with V1 and V2, and step with S, the following are valid cron values:

• V1: that literal value

• V1-V2: all literal values in the given range, inclusively

• V1-V2/S: similar to above, but we move with a step of S; So 2-9/3 would cover 2,5,8

• *: all legal values, equivalent to minValue-maxValue

• */S: starting from the minimum legal value, with a step of S

The values can be comma separated, representing a union between the queries. A new shape we are adding is V1/S, where we start V1 and iterate with a step through all legal values. It is equivalent to V1-maxValue/S. This allows for expressing a starting point for infinite ranges, like years or days and months since epoch, while still working correctly for other fields too.

We have additionally added negative numbers, allowing you to specify things starting from the highest legal value. This is most relevant for end of the month behavior, but can be a convenient syntax for situations as well. For example, a cron of 0 0 12 -2 * * will trigger at noon of the second last day of the month - Jan 30th, Feb 27th (for non-leap years, 28th on leap years), Mar 30th, Apr 29th, etc.

Reference: example default cron expressions.