Migrating to Rules & Assignments

This guide covers legacy fields that are being phased out in favor of the newer Rules, Demands, Patterns, and Assignments system.

Breaking Changes

Employee Changes

contracts and periodRules on Employee are not deprecated — they remain fully supported today. The newer rules system is offered as an alternative for teams that prefer request-level, tag-scoped constraints instead of per-employee contracts.

Legacy field	Alternative	Notes
`periodRules`	`rules`	`rules` are applied globally to all employees (no per-employee targeting yet); use `shifts` tag filters to scope by shift type. `periodRules` remains a supported, per-employee option.
`contracts`	`rules`	`rules` can express similar labor constraints at the request level. `contracts` remains a supported, per-employee option.

Shift Changes

Deprecated	Replacement	Notes
`value`	`min` and `max`	Specify exact staffing range
`critical`	`min` and `max`	Use `min` for required staffing
`employees`	`assignments`	Pre-assign with Assignment objects
`locked`	`assignments`	Set `locked: true` in Assignment
`blacklist`	`blocklist`	Renamed for inclusive terminology

New field tags added to shifts for grouping in rules (e.g., EARLY, NIGHT).

New Features

Rules

Rules replace period rules and contracts with a more flexible system for counters and sequences.

{
  "period": {
    "from": "2024-03-06T08:00:00",
    "to": "2024-03-10T17:00:00"
  },
  "maxWorkingDays": 4
}

{
  "period": {
    "from": "2024-03-06T08:00:00",
    "to": "2024-03-10T17:00:00"
  },
  "constraint": "COUNTER",
  "type": "DAYS_WORKED",
  "max": 4
}

Use shifts in rules (a list of shift tags, e.g. "shifts": ["EARLY"]) to apply constraints to specific shift types only.

See Rules documentation for complete examples.

Patterns

Define preferred or prohibited sequences of shifts across single or multiple days.

Pattern Example

{
  "type": "MULTI_DAY",
  "satisfy": "PROHIBITED",
  "elements": [
    { "type": "ON", "tags": ["LATE"] },
    { "type": "ON", "tags": ["EARLY"] }
  ]
}

See Patterns documentation for complete examples.

Demands

Specify staffing requirements independent of shift structure, allowing flexible coverage optimization.

Demand Example

{
  "demands": [
    {
      "name": "Peak hours",
      "from": "2022-01-01T14:00:00",
      "to": "2022-01-01T18:00:00",
      "skills": [{ "name": "general" }],
      "min": 3,
      "max": 5
    }
  ]
}

See Demands documentation for complete examples.

Assignments

Granularly specify pre-defined shift assignments with optional locking.

Assignment Example

{
  "assignments": [
    {
      "shift": "morning-1",
      "employee": "Alice",
      "locked": true
    }
  ]
}

See Lock Plan documentation for complete examples.

Migration Checklist

Update shift definitions

Replace value with min and max properties:

// Before
{ "value": 2 }

// After
{ "min": 2, "max": 2 }

Convert contracts to rules (optional)

contracts and periodRules remain fully supported on Employee — you do not need to migrate. If you’d rather define constraints once at the request level (tag-scoped, shared across employees), migrate contract-based constraints to the new Rule format with constraint and type fields.

Update employee references (optional)

If you migrated to request-level rules in the previous step, you can remove contracts and periodRules from employees. This is optional — both fields can be left in place and continue to work.

Rename blacklist to blocklist

Update any blacklist fields on shifts to blocklist.

Convert locked shifts to assignments

Replace employees and locked on shifts with the assignments array.

Platform

VRP API

Fill API

Migrating to Rules & Assignments

Breaking Changes

Employee Changes

Shift Changes

New Features

Rules

Patterns

Demands

Assignments

Migration Checklist

​Breaking Changes

​Employee Changes

​Shift Changes

​New Features

​Rules

​Patterns

​Demands

​Assignments

​Migration Checklist

Breaking Changes

Employee Changes

Shift Changes

New Features

Rules

Patterns

Demands

Assignments

Migration Checklist