Migrating from previous versions

1. 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.

1.1. 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
      }
    }
  }
}

1.2. 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
  }
}

1.3. 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

1.4. 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
      }
    }
  }
}

1.5. 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
  }
}

1.6. 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"
      ],
      ...
    }
  ]
}

1.7. 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
      }
      ...
}

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