API Documentation

Shifts are the work periods you need employees for. Each shift specifies when and where work happens, whether it's required or optional, and can guide the solver toward specific employees.

Shift structure

{
  "id": 101,
  "name": "Morning shift - ER",
  "spot": 5,
  "start": "2024-03-15T06:00:00Z",
  "end": "2024-03-15T14:00:00Z",
  "importance": "MANDATORY",
  "suggestedEmployees": [],
  "dislikedEmployees": [],
  "allowedCollisionSpots": [],
  "fixed": false,
  "historic": false,
  "employee": null,
  "foreignInt": null
}

Most fields are required. Let's break them down.

Basic fields

• id - Unique identifier for this shift
• name - Optional human-readable label (helpful for debugging)
• spot - The spot ID where this shift takes place (links to your spots array)
• start / end - ISO 8601 timestamps defining when the shift occurs
• importance - Either MANDATORY or OPTIONAL

Mandatory vs. Optional shifts

Mandatory shifts must be filled. The solver will assign someone even if it means violating soft constraints. Use this for critical coverage needs.

Optional shifts will be filled only if a good assignment exists. If filling this shift would significantly hurt the solution quality, the solver leaves it empty. Use this for "nice to have" coverage or when understaffing is acceptable.

Employee preferences

Guide the solver toward or away from specific employees for this shift:

{
  "suggestedEmployees": [12, 34],
  "dislikedEmployees": [56]
}

• suggestedEmployees - The solver prefers assigning these employees (if they're qualified and available)
• dislikedEmployees - The solver avoids these employees (but may assign them if no alternative exists)

These are soft constraints-the solver weighs them against other factors based on your settings.

Fixed and historic shifts

{
  "fixed": true,
  "historic": true,
  "employee": 42
}

• fixed - When true and employee is set, this assignment cannot change. Use for shifts that are already scheduled and locked in.
• historic - Marks shifts from a previous schedule period. The solver uses these to maintain consistency when generating new schedules.
• employee - When set with fixed: true, specifies who's assigned to this shift

These fields support re-planning scenarios where you're adjusting an existing schedule rather than creating one from scratch.

Shift collisions

{
  "allowedCollisionSpots": [7, 8]
}

Sometimes an employee needs to cover multiple spots simultaneously-for example, a supervisor who's "on call" for multiple areas. List the spot IDs where overlap is permitted.

If this shift (at spot 5) is assigned to the same employee working a concurrent shift at spot 7, the solver won't penalize it as a conflict.

See Shift collisions for more details.

Foreign key tracking

{
  "foreignInt": 98765
}

Use foreignInt to track your system's identifier for this shift. The solver returns this value unchanged in the solution, letting you correlate solved shifts back to your database.

Example shifts

A mandatory morning shift with a suggested employee:

{
  "id": 200,
  "name": "Reception - Morning",
  "spot": 10,
  "start": "2024-03-20T07:00:00Z",
  "end": "2024-03-20T15:00:00Z",
  "importance": "MANDATORY",
  "suggestedEmployees": [15],
  "dislikedEmployees": [],
  "allowedCollisionSpots": [],
  "fixed": false,
  "historic": false,
  "foreignInt": 5432
}

An optional evening shift that's already assigned and locked:

{
  "id": 201,
  "spot": 10,
  "start": "2024-03-20T15:00:00Z",
  "end": "2024-03-20T23:00:00Z",
  "importance": "OPTIONAL",
  "suggestedEmployees": [],
  "dislikedEmployees": [],
  "allowedCollisionSpots": [],
  "fixed": true,
  "historic": true,
  "employee": 12,
  "foreignInt": 5433
}