Upgrading to the latest versions

From 0.38.0 to 0.39.0

Added support for diminished returns termination

When submitting a new schedule with unspecified unimprovedSpentLimit in the run termination configuration, the run will use the new diminished returns termination.

Diminished returns termination is enabled by default when unimprovedSpentLimit isn’t present. For existing datasets, remove unimprovedSpentLimit to enable diminished returns termination.

Before:

{
  "config": {
    "run": {
      "name": "My run",
      "termination": {
        "spentLimit": "PT30M",
        "unimprovedSpentLimit": "PT1M"
    }
  }
}

After:

{
  "config": {
    "run": {
      "name": "My run",
      "termination": {
        "spentLimit": "PT30M"
    }
  }
}

If you were not setting the unimprovedSpentLimit and you need to keep the old behaviour, set the unimprovedSpentLimit to the value of spentLimit:

Before:

{
  "config": {
    "run": {
      "name": "My run",
      "termination": {
        "spentLimit": "PT30M"
    }
  }
}

After (only if you want to keep the old behaviour):

{
  "config": {
    "run": {
      "name": "My run",
      "termination": {
        "spentLimit": "PT30M",
        "unimprovedSpentLimit": "PT30M"
    }
  }
}

Affects the following REST endpoints:

POST /v1/schedules

From 0.32.1 to 0.33.0

Single-day shift pattern rules with REQUIRED satisfiability deprecated

Single-day shift pattern rules with REQUIRED satisfiability have been deprecated and should be replaced by a rule with PREFERRED satisfiability with a high pattern weight.

Affects all REST endpoints starting with /v1/schedules when the input dataset uses single-day pattern rules.

Before:

"singleDayShiftSequencePatternRules": [
{
    "id": "someRequiredPattern",
    "satisfiability": "REQUIRED",
    "pattern": [
      ...
    ]
  },
  {
    "id": "somePreferredPattern",
    "satisfiability": "PREFERRED",
    "pattern": [
      ...
    ]
  }
]

After:

"singleDayShiftSequencePatternRules": [
{
    "id": "someRequiredPattern",
    "satisfiability": "PREFERRED",
    "weight": 100,
    "pattern": [
      ...
    ]
  },
  {
    "id": "somePreferredPattern",
    "satisfiability": "PREFERRED",
    // the default weight is 1
    "pattern": [
      ...
    ]
  }
]

Zone Offset Deprecation

zoneOffset on employees is now deprecated in favour of timeZoneId.

Before:

{
"employees":
      {
        "id": "Carl",
        "contracts": [
          "Carl's Contract"
        ],
        "timezoneOffset": "+01:00"
      }
}

After:

{
"employees":
      {
        "id": "Carl",
        "contracts": [
          "Carl's Contract"
        ],
        "timeZoneId": "Europe/Brussels"
      }
}

From 0.28.0 to 0.29.0

Multi-day shift pattern rules with REQUIRED satisfiability deprecated

Multi-day shift pattern rules with REQUIRED satisfiability have been deprecated and should be replaced by a rule with PREFERRED satisfiability with a high pattern weight.

Affects all REST endpoints starting with /v1/schedules when the input dataset uses multi-day pattern rules.

Before:

"multiDayShiftSequencePatternRules": [
{
    "id": "someRequiredPattern",
    "satisfiability": "REQUIRED",
    "pattern": [
      ...
    ]
  },
  {
    "id": "somePreferredPattern",
    "satisfiability": "PREFERRED",
    "pattern": [
      ...
    ]
  }
]

After:

"multiDayShiftSequencePatternRules": [
{
    "id": "someRequiredPattern",
    "satisfiability": "PREFERRED",
    "weight": 100,
    "pattern": [
      ...
    ]
  },
  {
    "id": "somePreferredPattern",
    "satisfiability": "PREFERRED",
    // the default weight is 1
    "pattern": [
      ...
    ]
  }
]

From 0.25.0 to 0.26.2

Justifications retrieved for a completed run are limited to 100 per constraint

The number of justifications that is stored and can be retrieved for a completed run has been limited to 100 per each constraint.

Affects the following REST endpoints:

GET /v1/schedules/{id}/score-analysis?includeJustifications=true

To get the full list of justifications, use the following endpoint:

POST /v1/schedules/score-analysis?includeJustifications=true

From 0.24.0 to 0.25.0

Shift’s assignmentPriority attribute has been deprecated in favor of the priority attribute.

See Unassigned shift rule for more information.

From 0.18.0 to 0.19.0

The version 0.19.0 introduces changes to the API. The changes are not backward compatible and require changes to the client code.

Local date time replaced by date time with offset to UTC

All ISO 8601 local date time types have been replaced by ISO 8601 local date time with offset to UTC (Coordinated Universal Time) to support multiple time zones.

Affects all REST endpoints starting with /v1/schedules.

before (start and end are just examples, all date time attributes are affected):

{
    "start": "2024-01-01T08:00:00",
    "end": "2024-01-01T12:00:00"
}

after (assuming the original local date time values are in UTC):

{
    "start": "2024-01-01T08:00:00Z",
    "end": "2024-01-01T12:00:00Z"
}

From 0.17.0 to 0.17.1

The version 0.17.1 introduces changes to the API. The changes are not backward compatible and require changes to the client code.

Model output shift format changed

The employee object in the shift has been replaced by a string attribute. The attribute represents the identifier of the employee.

Affects the following REST endpoints:

GET /v1/schedules/{id}
DELETE /v1/schedules/{id}

Before:

"modelOutput": {
  "shifts": [
    {
      "id": "7",
      "employee": {
        "id": "John Doe"
      }
    },
    ...
    ]
}

After:

"modelOutput": {
  "shifts": [
    {
      "id": "7",
      "employee": "John Doe"
    },
    ...
    ]
}

From 0.16.0 to 0.17.0

The version 0.17.0 introduces changes to the API. The changes are not backward compatible and require changes to the client code.

Model output format changed

The model output object now only contains shifts collection. The shift object now only contains the id and employee attributes. This helps to reduce the size of the response.

Affects the following REST endpoints:

GET /v1/schedules/{id}
DELETE /v1/schedules/{id}

Before:

"modelOutput": {
  "contracts": [
    ...
  ],
  "shifts": [
    {
      "id": "7",
      "start": "2024-06-10T09:00:00",
      "end": "2024-06-10T17:00:00",
      "requiredSkills": [
          "Supervisor"
      ]
      "employee": "John Doe"
    },
    ...
    ],
    ...
}

After:

"modelOutput": {
  "shifts": [
    {
      "id": "7",
      "employee": {
        "id": "John Doe"
      }
    },
    ...
    ]
}

From 0.13.0 to 0.14.0

The version 0.14.0 introduces changes to the API. The changes are not backward compatible and require changes to the client code.

Submit schedule request input format changed

Submit schedule request introduces a new structure to separate the schedule from the configuration:

schedule object is now included in the modelInput attribute.
scheduleParametrization.constraintConfiguration has been moved to config.model.overrides.
termination has been moved to config.run.termination.

Affects the following REST endpoints:

POST /v1/schedules/

Before:

{
  "contracts": [
    ...
  ],
  "employees": [
    ...
  ],
  "termination": {
    "spentLimit": "PT10M",
    "unimprovedSpentLimit": "PT5M"
  }
  ...
}

After:

{
  {
  "modelInput": {
    "contracts": [
      ...
    ],
    "employees": [
      ...
    ],
  },
  "config": {
    "run": {
      "name": "ICU dataset 01-01-2024",
      "termination": {
        "spentLimit": "PT10M",
        "unimprovedSpentLimit": "PT5M"
      }
    },
    "model": {
      "overrides": {
        "preferredEmployeeAssignedWeight": 10
      }
    }
  }
}

Schedule output format changed

Get schedule request introduces a new structure to separate the result schedule from the run information:

status object is now replaced by run object.
schedule object is now included in the modelOutput attribute.

Affects the following REST endpoints:

GET /v1/schedules/
DELETE /v1/schedules/

Before:

{
  "contracts": [
    ...
  ],
  "employees": [
    ...
  ],
  "status": {
    "id": "dd9b4560-be61-4124-a4cf-fae993ee1a31",
    "submitDateTime": "2024-04-23T09:16:55.188848+02:00",
    ...
}

After:

{
  "run": {
    "id": "dd9b4560-be61-4124-a4cf-fae993ee1a31",
    "name": "Run-2024-04-23T09:16:55.188848+02:00",
    "submitDateTime": "2024-04-23T09:16:55.188848+02:00",
    ...
  },
  "modelOutput": {
    "contracts": [
      ...
    ],
    "employees": [
      ...
    ],
  },
  "kpis": {
    "unassignedShifts": 0
  }
}

Schedule status request replaced by run request

The schedule status request has been replaced by the run request.

Affects the following REST endpoints:

GET /v1/schedules/{id}/status

Before:

GET /v1/schedules/{id}/status

After:

GET /v1/schedules/{id}/run

Score analysis request input format changed

Score analysis request introduces a new structure to separate the schedule from the configuration:

schedule object is now included in the modelInput attribute.
scheduleParametrization.constraintConfiguration has been moved to config.model.overrides.

Affects the following REST endpoints:

POST /v1/schedules/score-analysis

Before:

{
  "contracts": [
    ...
  ],
  "employees": [
    ...
  ],
  "scheduleParametrization": {
    "constraintConfiguration": {
      "preferredEmployeeAssignedWeight": 10
    }
  }
  ...
}

After:

{
  {
  "modelInput": {
    "contracts": [
      ...
    ],
    "employees": [
      ...
    ],
  },
  "config": {
    "model": {
      "overrides": {
        "preferredEmployeeAssignedWeight": 10
      }
    }
  }
}

Recommend employees request input format changed

Recommend employees request introduces a new structure to separate the schedule from the configuration:

schedule object is now included in the modelInput attribute.
scheduleParametrization.constraintConfiguration has been moved to config.model.overrides.

Affects the following REST endpoints:

POST /v1/schedules/recommendations/recommend-employees

Before:

{
  "maxNumberOfRecommendations": 5,
  "fitShiftId": "99999",
  "contracts": [
    ...
  ],
  "employees": [
    ...
  ],
  "scheduleParametrization": {
    "constraintConfiguration": {
      "preferredEmployeeAssignedWeight": 10
    }
  }
  ...
}

After:

{
  "maxNumberOfRecommendations": 5,
  "fitShiftId": "99999",
  "modelInput": {
    "contracts": [
      ...
    ],
    "employees": [
      ...
    ],
  },
  "config": {
    "preferredEmployeeAssignedWeight": 10
  }
}

Employee now supports declaring multiple contracts

This is useful when a single employee works in multiple institutions and each institution has different limits.

Affects the following REST endpoints:

POST /v1/schedules/
POST /v1/schedules/score-analysis
POST /v1/schedules/{id}/recommendations/recommend-employees
GET /v1/schedules/{id}
DELETE /v1/schedules/{id}

Before:

{
  ...
  "employees": [
    {
      "id": "Elsa Green",
      "contract": "ICU contract",
      ...
    }
  ]
}

After:

{
  ...
  "employees": [
    {
      "id": "Elsa Green",
      "contracts": [
        "Hospital 1 contract",
        "Hospital 2 contract"
      ],
      ...
    }
  ]
}

Default values and non-required attributes are no longer included in the response schedule

GET /v1/schedules/{id}
DELETE /v1/schedules/{id}

Before:

{
  ...
  {
    "periodRules": [
      {
        "id": "Maximum 40 hours a week",
        "period": "WEEK",
        "satisfiability": "REQUIRED",
        "includeShiftTags": null,
        "excludeShiftTags": null,
        "shiftTagMatches": "ALL",
        "minutesWorkedMin": null,
        "minutesWorkedMax": 2400,
        "shiftsWorkedMin": null,
        "shiftsWorkedMax": null,
        "daysWorkedMin": null,
        "daysWorkedMax": null,
        "shiftTypesTagCategories": null,
        "shiftTypesWorkedMin": null,
        "shiftTypesWorkedMax": null
      }
      ...
}

After:

{
  ...
  {
    "periodRules": [
      {
        "id": "Maximum 40 hours a week",
        "period": "WEEK",
        "minutesWorkedMax": 2400
      }
      ...
}

Collection attributes in the input schedule are no longer nullable

Affects the following REST endpoints:

POST /v1/schedules/
POST /v1/schedules/score-analysis
POST /v1/schedules/{id}/recommendations/recommend-employees

If included, the collection attributes now require a non-null value.

Before:

{
  "periodRules": [
    {
      "id": "Maximum 40 hours a week",
      "period": "WEEK",
      "includeShiftTags": null,
      "excludeShiftTags": null
      ...
}

After:

{
  "periodRules": [
    {
      "id": "Maximum 40 hours a week",
      "period": "WEEK",
      "includeShiftTags": [],
      "excludeShiftTags": []
      ...
}