Migrating from previous versions

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": []
      ...
}