DHTMLX Planning Engine Documentation

CalendarData#

A working calendar: daily working hours, working weekdays and per-date exceptions. Calendars are sent in the calendars array of ProjectData, and tasks and resources point to one by calendar_id. Without any calendars, the project uses the built-in "global" calendar: Monday to Friday, 08:00-12:00 and 13:00-17:00.

How tasks and resources pick a calendar, and how to turn calendars off, is covered in Working time and calendars and SchedulingConfig (calendar_mode, use_calendars).

Fields#

Field Type Required Default Description
id Id yes - Calendar id. "global" replaces the built-in default calendar. Must be unique within calendars.
worktime object | null no built-in hours and days Working time of the calendar. Omitted or null gives Monday to Friday, 08:00-12:00 and 13:00-17:00.

Unknown fields are ignored. The record must be a JSON object.

Worktime fields#

The working time of one calendar. Each field is optional; an omitted or null field keeps its default.

Field Type Required Default Description
hours string[] no ["8:00-12:00", "13:00-17:00"] Working hour ranges of a working day, each "H:MM-H:MM". "24:00" is the only accepted hour-24 value. A range that ends before it starts crosses midnight.
days (boolean | number)[] no Monday to Friday Working weekdays. Exactly 7 entries, index 0 is Sunday. true or a non-zero number marks a working day; false or 0 a day off.
dates { "YYYY-MM-DD": boolean | number | string[] } no {} Exceptions for single dates. Each key is a date, each value a date rule. A date rule overrides days for that date.

customWeeks and custom_weeks aren't supported. Sending either field fails the call with validation ("customWeeks is not supported yet").

Note

A malformed hour range fails the whole call with a validation error that has no path. In apply, this means no operation from that change set is applied.

Date rules#

The value of one dates entry.

Value Meaning
true or a non-zero number Working day with the calendar's hours
false or 0 Day off
string[] Working day with these hour ranges, in the same "H:MM-H:MM" format as hours

Errors#

Errors come back in the response envelope of the call that received the data. See Error handling for the error fields.

Error When
kind: "parse" The record or worktime isn't a JSON object, id is missing, or a days entry isn't a boolean or number.
kind: "validation", path: null Malformed hour range, days without exactly 7 entries, a dates key that isn't YYYY-MM-DD, or customWeeks / custom_weeks present.
kind: "validation", path: "calendars[i]" Duplicate calendar id, or a calendar with no working time.

Used by#

Calendars can't be added or edited through JsonProject.apply. To change them, send full data to solve.

Example#

A calendar with 09:00-18:00 working days, a public holiday and one Saturday with morning hours:

{
  "id": "office",
  "worktime": {
    "hours": ["9:00-13:00", "14:00-18:00"],
    "days": [false, true, true, true, true, true, false],
    "dates": {
      "2026-12-25": false,
      "2026-12-19": ["9:00-13:00"]
    }
  }
}