Managing schedules

Create, update, query, and delete JSCalendar-aligned schedules compatible with RFC 5545 (iCalendar).

Navixy GraphQL API is a work in progress. This documentation is published for preview purposes only and doesn't reflect a stable release. Structure, field names, and behaviors are subject to change.

Schedules in Business Data Repository (BDR) define time-based rules for your fleet operations, maintenance windows, work hours, restrictions, and more.

The schedule data structure follows JSCalendar (RFC 8984), a JSON format for calendar data, and converts to RFC 5545 (iCalendar) and back without losing information. If you've worked with iCalendar concepts like RRULE, EXDATE, and VTIMEZONE, the model will be familiar: the field names and JSON structure come from JSCalendar, while the repeat rules behave as in iCalendar. If you haven't, that's fine. This guide explains everything you need.

This guide walks you through creating, configuring, updating, and deleting schedules.

Prerequisites

To work with a schedule, you need your workspace's ID. It comes with your access credentials and is carried in your access token. See Authentication for how tokens work and where the workspace ID comes from.

How schedule data works

A schedule consists of metadata (title and workspace) and calendar data stored in the scheduleData field, which accepts a value of ScheduleData, a structured JSON object validated on every write.

Top-level fields

The JSON structure follows the JSCalendar conventions:

Field	Required	Description
timeZone		IANA timezone identifier (e.g., Europe/Berlin, America/New_York, UTC). Defines how the API interprets all date-time values in timed events.
events		Non-empty array of time slots, each with a start time, end time or duration, and an optional recurrence rule
active		Boolean. When false, the schedule is disabled without deleting it. Defaults to true.
description		Free-text description. The schedule's display name is the entity title, not this field.

How timezone works

All date-time values in events (start, end, excludedDates, additionalDates, and recurrenceRule.until) are local time with no UTC offset or Z suffix. The timeZone field tells the API how to interpret them.

For example, for "timeZone": "Europe/Berlin":

• "start": "2025-01-06T06:00:00" means 6:00 AM Berlin time.

• The API handles daylight saving time (DST) changes automatically, so a recurring event at 06:00:00 stays at 6 AM local time year-round.

All-day events (where showWithoutTime: true) use date strings instead of date-times (2025-06-10, not 2025-06-10T00:00:00) and are timezone-independent.

Event fields

Each event in the events array can include:

Field	Required	Description
start	Yes	Start date-time for timed events (2025-01-06T06:00:00) or date for all-day events (2025-01-06). Seconds required. No fractional seconds. No offset or Z.
end	Conditional	End date-time (or date for all-day). Can't be combined with duration. A timed event needs exactly one of end or duration. An all-day event may omit both.
duration	Conditional	Duration in ISO 8601 format (e.g., PT9H, PT30M, P1D). Can't be combined with end. Must be positive. For all-day events, must be whole days (e.g., P1D, P2W) with no time component. Preferred over end for recurring events because it stays stable across DST changes.
showWithoutTime	No	When true, the event is all-day: start and end are dates, and the event ignores timeZone. All-day recurrence rules must not use byHour, byMinute, or bySecond.
recurrenceRule	No	Recurrence rule defining the repeat pattern. Absent means a single occurrence at start.
excludedDates	No	Array of local date-times to exclude from recurrence (iCalendar EXDATE). Values must exactly match generated occurrence date-times, including the time component.
additionalDates	No	Array of local date-times to add as one-off occurrences (iCalendar RDATE).
uid	No	Stable string identifier for the slot. Useful when tracking individual events across updates.
title	No	Display label for this event slot (maps to VEVENT SUMMARY).

Recurrence rule fields

The recurrenceRule property supports these fields:

Field	Type	Description
frequency	String	Required. One of: secondly, minutely, hourly, daily, weekly, monthly, yearly. Lowercase.
interval	Integer	Repeat every N periods. Must be ≥ 1. Defaults to 1.
count	Integer	Stop after N occurrences. Can't be combined with until.
until	String	Stop after this local date-time. Must be ≥ start. Can't be combined with count.
byDay	Object[]	Days of the week. Each entry is { "day": "<mo|tu|we|th|fr|sa|su>", "nthOfPeriod": <integer> }. The optional nthOfPeriod sets an ordinal (e.g., { "day": "mo", "nthOfPeriod": 1 } = first Monday of the period) and is only valid for monthly or yearly frequency.
byMonth	Integer[]	Months: 1–12.
byMonthDay	Integer[]	Days of the month: 1–31, or -31 to -1 from the end (-1 = last day).
byYearDay	Integer[]	Days of the year: 1–366, or -366 to -1 from the end.
byWeekNo	Integer[]	Weeks of the year: 1–53, or -53 to -1. Valid only with yearly frequency.
byHour	Integer[]	Hours: 0–23. Must not be used on all-day events.
byMinute	Integer[]	Minutes: 0–59. Must not be used on all-day events.
bySecond	Integer[]	Seconds: 0–60 (60 is valid for leap seconds). Must not be used on all-day events.
firstDayOfWeek	String	First day of the week for week calculations. One of mo–su. Defaults to mo. (iCalendar WKST.)

Validation

scheduleData is validated on every write against the following rules:

• required fields

• pairs that can't be combined (end/duration, count/until)

• date-time format (local time only, no offset or Z)

• recurrence constraints (byWeekNo only with yearly, ordinal byDay only with monthly/yearly, no byHour/byMinute/bySecond on all-day events)

• field types

If the input breaks any of these rules, the API rejects the whole write with a validation error that names the problem field. The rules apply only to writes. Reading is never validated, so schedules saved before a rule existed can still be read.

Example scenario: Fleet maintenance schedule

TransLog GmbH needs to schedule weekly maintenance for their vehicle fleet. The maintenance provider works every Monday from 6:00 to 10:00 (Europe/Berlin timezone). Over time, requirements will change: holidays need to be excluded, the contract has an end date, and the maintenance window gets split to accommodate a break.

1

Create the schedule

Start with a weekly recurring event. The scheduleData field requires a timeZone and at least one event with a start and either end or duration.

version is optional in all mutations. If you leave it out, an update always applies, even when someone else changed the record after you last read it. Include it to catch such conflicts, as the examples in this scenario do. See Optimistic locking for details.

Run this mutation:

mutation CreateMaintenanceSchedule {
  bdr {
    scheduleCreate(input: {
      workspaceId: "7c9e6679-7425-40de-944b-e07fc1f90ae7"
      title: "Weekly fleet maintenance"
      scheduleData: {
        timeZone: "Europe/Berlin"
        events: [
          {
            start: "2025-01-06T06:00:00"
            duration: "PT4H"
            recurrenceRule: {
              frequency: "weekly"
              byDay: [{ day: "mo" }]
            }
          }
        ]
      }
    }) {
      schedule {
        id
        version
        title
      }
    }
  }
}

Note the following:

• timeZone is Europe/Berlin. All date-times in this schedule are Berlin local time: no Z, no offset.

• start: "2025-01-06T06:00:00" is a Monday, which matches the byDay: [{ day: "mo" }] rule. Always make start match your repeat rule, otherwise the first occurrence may not land where you expect.

• duration: "PT4H" defines a 4-hour window (06:00–10:00). Using duration instead of end keeps the window stable across DST changes.

• frequency: "weekly" with byDay: [{ day: "mo" }] means the event repeats every Monday.

The response confirms creation:

{
  "data": {
    "bdr": {
      "scheduleCreate": {
        "schedule": {
          "id": "019a6b2f-793e-807b-8001-555345529b44",
          "version": 1,
          "title": "Weekly fleet maintenance"
        }
      }
    }
  }
}

Save the id and version. You'll need them for updating the schedule.

2

Verify the schedule

Query the schedule to confirm it was created correctly:

query GetMaintenanceSchedule {
  bdr {
    schedule(id: "019a6b2f-793e-807b-8001-555345529b44") {
      id
      version
      title
      scheduleData
    }
  }
}

The scheduleData field returns the full JSON structure you provided. Use it to verify the configuration before making further changes.

3

Exclude holidays

The maintenance provider doesn't work on public holidays. Several holidays in the year fall on Mondays. Add these as exception dates using excludedDates. This requires updating the schedule with scheduleUpdate.

When updating scheduleData, you must provide the complete value, as the API replaces the entire field. Include all existing configuration alongside your changes.

An entry in excludedDates must exactly match the date and time of the occurrence it removes, not just the date. This event's occurrences start at 06:00:00, so every excluded date ends with the same T06:00:00.

Run this mutation:

mutation AddHolidayExceptions {
  bdr {
    scheduleUpdate(input: {
      id: "019a6b2f-793e-807b-8001-555345529b44"
      version: 1
      scheduleData: {
        timeZone: "Europe/Berlin"
        events: [
          {
            start: "2025-01-06T06:00:00"
            duration: "PT4H"
            recurrenceRule: {
              frequency: "weekly"
              byDay: [{ day: "mo" }]
            }
            excludedDates: [
              "2025-04-21T06:00:00",
              "2025-05-05T06:00:00",
              "2025-06-09T06:00:00",
              "2025-10-06T06:00:00"
            ]
          }
        ]
      }
    }) {
      schedule {
        id
        version
        scheduleData
      }
    }
  }
}

For all-day events (showWithoutTime: true), use date-only values in excludedDates, for example, "2025-04-21" instead of "2025-04-21T06:00:00".

The response shows the incremented version:

{
  "data": {
    "bdr": {
      "scheduleUpdate": {
        "schedule": {
          "id": "019a6b2f-793e-807b-8001-555345529b44",
          "version": 2,
          "scheduleData": { "..." : "..." }
        }
      }
    }
  }
}

4

Set an end date

The maintenance contract runs through December 31, 2025. Add an until date to the recurrence rule so the schedule stops repeating after that date.

mutation SetContractEndDate {
  bdr {
    scheduleUpdate(input: {
      id: "019a6b2f-793e-807b-8001-555345529b44"
      version: 2
      scheduleData: {
        timeZone: "Europe/Berlin"
        events: [
          {
            start: "2025-01-06T06:00:00"
            duration: "PT4H"
            recurrenceRule: {
              frequency: "weekly"
              byDay: [{ day: "mo" }]
              until: "2025-12-31T23:59:59"
            }
            excludedDates: [
              "2025-04-21T06:00:00",
              "2025-05-05T06:00:00",
              "2025-06-09T06:00:00",
              "2025-10-06T06:00:00"
            ]
          }
        ]
      }
    }) {
      schedule {
        id
        version
      }
    }
  }
}

until is inclusive: the last occurrence can fall on this date. It must be ≥ start and can't be combined with count. The schedule's version is now 3.

5

Split the schedule into two windows

The maintenance team requests a break from 8:00 to 8:30. Replace the single 4-hour event with two events: 6:00–8:00 and 8:30–10:00.

Each event needs its own excludedDates array with times matching that event's start. Run this mutation:

mutation SplitMaintenanceWindow {
  bdr {
    scheduleUpdate(input: {
      id: "019a6b2f-793e-807b-8001-555345529b44"
      version: 3
      scheduleData: {
        timeZone: "Europe/Berlin"
        events: [
          {
            start: "2025-01-06T06:00:00"
            duration: "PT2H"
            recurrenceRule: {
              frequency: "weekly"
              byDay: [{ day: "mo" }]
              until: "2025-12-31T23:59:59"
            }
            excludedDates: [
              "2025-04-21T06:00:00",
              "2025-05-05T06:00:00",
              "2025-06-09T06:00:00",
              "2025-10-06T06:00:00"
            ]
          },
          {
            start: "2025-01-06T08:30:00"
            duration: "PT1H30M"
            recurrenceRule: {
              frequency: "weekly"
              byDay: [{ day: "mo" }]
              until: "2025-12-31T23:59:59"
            }
            excludedDates: [
              "2025-04-21T08:30:00",
              "2025-05-05T08:30:00",
              "2025-06-09T08:30:00",
              "2025-10-06T08:30:00"
            ]
          }
        ]
      }
    }) {
      schedule {
        id
        version
      }
    }
  }
}

The schedule's version is now 4.

6

Delete the schedule

When the contract ends and you no longer need the schedule, run this mutation to delete it:

mutation DeleteMaintenanceSchedule {
  bdr {
    scheduleDelete(input: {
      id: "019a6b2f-793e-807b-8001-555345529b44"
      version: 4
    }) {
      deletedId
    }
  }
}

Response:

{
  "data": {
    "bdr": {
      "scheduleDelete": {
        "deletedId": "019a6b2f-793e-807b-8001-555345529b44"
      }
    }
  }
}

Including version ensures you don't accidentally delete a schedule that someone else has modified. If the version doesn't match, you'll receive a conflict error. See Optimistic locking for details on when to omit it.

Listing schedules

To retrieve all schedules for a workspace:

query ListSchedules {
  bdr {
    schedules(
      workspaceId: "7c9e6679-7425-40de-944b-e07fc1f90ae7"
      first: 20
    ) {
      nodes {
        id
        title
        scheduleData
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}

For details on pagination, see Pagination.

Handling version conflicts

If you include version in your mutation and the entity has been modified since you last fetched it, the API returns a conflict error:

{
  "errors": [
    {
      "message": "Entity has been modified by another request",
      "extensions": {
        "code": "CONFLICT",
        "status": 409,
        "expectedVersion": 3,
        "currentVersion": 4
      }
    }
  ]
}

To resolve this:

1. Query the schedule to get the current version and data

2. Merge your changes with the current state

3. Retry the mutation with the correct version

For more details on version conflicts, see Optimistic locking.

Common patterns

The snippets below show the recurrenceRule object in isolation. In practice, each belongs inside an event in the events array alongside start and end or duration.

Single-parameter patterns

Every weekday (standard work hours):

{
  "frequency": "weekly",
  "byDay": [
    { "day": "mo" }, { "day": "tu" }, { "day": "we" },
    { "day": "th" }, { "day": "fr" }
  ]
}

Every other week on Monday (bi-weekly team meetings):

{
  "frequency": "weekly",
  "interval": 2,
  "byDay": [{ "day": "mo" }]
}

First and fifteenth of each month (payroll processing):

{
  "frequency": "monthly",
  "byMonthDay": [1, 15]
}

Last day of each month (monthly reports deadline):

{
  "frequency": "monthly",
  "byMonthDay": [-1]
}

First Monday of each month (monthly fleet review):

{
  "frequency": "monthly",
  "byDay": [{ "day": "mo", "nthOfPeriod": 1 }]
}

Multi-parameter patterns

Every hour during weekday business hours (hourly check-ins):

{
  "frequency": "hourly",
  "byDay": [
    { "day": "mo" }, { "day": "tu" }, { "day": "we" },
    { "day": "th" }, { "day": "fr" }
  ],
  "byHour": [8, 9, 10, 11, 12, 13, 14, 15, 16, 17]
}

byHour, byMinute, and bySecond work with any frequency. Their only restriction is that an all-day event (showWithoutTime: true) must not use them.

Every Monday in January, April, July, and October (quarterly inspections):

{
  "frequency": "yearly",
  "byMonth": [1, 4, 7, 10],
  "byDay": [{ "day": "mo" }]
}

Complete examples

Warehouse work hours

Standard weekday schedule with a lunch break, excluding company holidays:

{
  "timeZone": "Europe/Berlin",
  "events": [
    {
      "start": "2025-01-06T08:00:00",
      "duration": "PT4H",
      "recurrenceRule": {
        "frequency": "weekly",
        "byDay": [
          { "day": "mo" }, { "day": "tu" }, { "day": "we" },
          { "day": "th" }, { "day": "fr" }
        ]
      },
      "excludedDates": [
        "2025-01-01T08:00:00",
        "2025-12-25T08:00:00",
        "2025-12-26T08:00:00"
      ]
    },
    {
      "start": "2025-01-06T13:00:00",
      "duration": "PT4H",
      "recurrenceRule": {
        "frequency": "weekly",
        "byDay": [
          { "day": "mo" }, { "day": "tu" }, { "day": "we" },
          { "day": "th" }, { "day": "fr" }
        ]
      },
      "excludedDates": [
        "2025-01-01T13:00:00",
        "2025-12-25T13:00:00",
        "2025-12-26T13:00:00"
      ]
    }
  ]
}

Refrigerated truck temperature monitoring

Different temperature thresholds for day and night operation:

{
  "timeZone": "Europe/Moscow",
  "events": [
    {
      "start": "2025-01-06T06:00:00",
      "duration": "PT16H",
      "recurrenceRule": { "frequency": "daily" }
    },
    {
      "start": "2025-01-06T22:00:00",
      "duration": "PT8H",
      "recurrenceRule": { "frequency": "daily" }
    }
  ]
}

Equipment rental periods

Non-recurring schedule for specific rental dates:

{
  "timeZone": "America/New_York",
  "events": [
    {
      "start": "2025-02-10",
      "end": "2025-02-15",
      "showWithoutTime": true
    },
    {
      "start": "2025-03-01",
      "end": "2025-03-10",
      "showWithoutTime": true
    }
  ]
}

Attaching schedules to other entities

A schedule on its own is just calendar data. To put it to work, link it to the entity it governs, such as the asset it defines maintenance windows for. The link is a REFERENCE custom field on the asset type, with refEntityTypeCode: "schedule" fixing what the field may point at. The same pattern links entities to tags and catalog items — only the refEntityTypeCode changes.

1

Define the reference field

Add the field definition to the asset type. See Implementing custom fields for the full definition workflow:

mutation AddMaintenanceScheduleField {
  bdr {
    assetTypeUpdate(input: {
      id: "b1ffcd00-0d1c-5f29-cc7e-7cc0ce491b22"
      version: 2
      customFieldDefinitions: [
        {
          create: {
            code: "cf_maintenance_schedule"
            title: "Maintenance Schedule"
            fieldType: REFERENCE
            params: { reference: { refEntityTypeCode: "schedule", isRequired: false } }
          }
        }
      ]
    }) {
      assetType {
        id
        version
      }
    }
  }
}

The response returns the type with its incremented version, as in the earlier update examples.

2

Attach the schedule to an asset

Set the field on the asset, using the schedule's ID as the value. isPrimary is required on every reference value, so state it explicitly:

mutation AttachScheduleToTruck {
  bdr {
    assetUpdate(input: {
      id: "019a6b2f-793e-807b-8001-555345529b44"
      version: 2
      customFields: {
        set: [
          {
            code: "cf_maintenance_schedule"
            value: { reference: { id: "019a7c3e-88a1-807b-8001-777567741c66", isPrimary: false } }
          }
        ]
      }
    }) {
      asset {
        id
        version
      }
    }
  }
}

The response confirms the update with the asset's new version.

3

Read the schedule back from the asset

Select the field and use inline fragments, first on the value type, then on Schedule:

query GetTruckSchedule {
  bdr {
    asset(id: "019a6b2f-793e-807b-8001-555345529b44") {
      title
      customFields(codes: ["cf_maintenance_schedule"]) {
        code
        ... on ReferenceCustomFieldValue {
          refs {
            ... on Schedule {
              id
              title
              scheduleData
            }
          }
        }
      }
    }
  }
}

Response:

{
  "data": {
    "bdr": {
      "asset": {
        "title": "Truck B-44 (Hamburg–Berlin)",
        "customFields": [
          {
            "code": "cf_maintenance_schedule",
            "refs": [
              {
                "id": "019a7c3e-88a1-807b-8001-777567741c66",
                "title": "Weekly maintenance",
                "scheduleData": {
                  "timeZone": "Europe/Berlin",
                  "events": [
                    {
                      "start": "2025-01-06T06:00:00",
                      "duration": "PT4H",
                      "recurrenceRule": { "frequency": "weekly" }
                    }
                  ]
                }
              }
            ]
          }
        ]
      }
    }
  }
}

refs is always a list, and a single-value field returns one element. An element is null when the referenced schedule was deleted after being linked, so handle that case when reading.

To detach the schedule, remove the field with unset: ["cf_maintenance_schedule"] in assetUpdate, the same way device fields are unlinked in Working with assets.

See also

• Schedules: Complete reference for all schedule operations and types

• Implementing custom fields: Define custom fields and store your own data on entities

• Working with assets: Create and manage assets such as vehicles and equipment