Shift planning

The shift planning app is available in two modeling languages as a Mixed Integer Problem (MIP). You can also choose to make customizations to the model by instantiating the app first.

OR-Tools
- Default solver: SCIP
- Marketplace subscription app IDs
  - Python: nextmv-shift.plan.ortools

Bash

nextmv community clone -a python-ortools-shiftplanning

Pyomo
- Default solver: CBC
- Marketplace subscription app IDs
  - Python: nextmv-shift.plan.pyomo

Bash

nextmv community clone -a python-pyomo-shiftplanning

Once you have the code locally, you can customize the model, run it locally and deploy it to Nextmv Platform.

Input

The format for timestamps should be RFC3339, e.g.: "2023-01-01T00:00:00Z".

The input schema is a JSON payload defining the available workers and the required demand to satisfy for a shift scheduling problem. Nextmv's tools are designed to operate directly on business data (in JSON) to produce decisions that are actionable by software systems. This makes decisions more interpretable and easier to test. It also makes integration with data warehouses and business intelligence platforms significantly easier. An input contains the following components:

Field name	Required	Data type	SI Unit	Description	Example
`shifts`	Yes	`array` of `shift`	NA	Possible shifts with additional properties to select from.	See `shift`
`demands`	Yes	`array` of `demand`	NA	A predicted need of workers at certain times.	See `demand`
`options`	No	`array` of `option`	NA	A set of options to solve the problem.	See `option`

Here you can find a sample .json with the input schema:

JSON

{
  "options": {
    "under_supply_cost": 1000,
    "over_supply_cost": 100
  },
  "shifts": [
    {
      "id": "welder",
      "qualification": "welding",
      "min_workers": 1,
      "max_workers": 4,
      "cost": 100,
      "times": [
        {
          "id": "monday-early",
          "start_time": "2023-11-20T06:00:00+02:00",
          "end_time": "2023-11-20T14:00:00+02:00"
        },
        {
          "id": "monday-late",
          "start_time": "2023-11-20T14:00:00+02:00",
          "end_time": "2023-11-20T22:00:00+02:00"
        },
        {
          "id": "monday-night",
          "start_time": "2023-11-20T22:00:00+02:00",
          "end_time": "2023-11-21T06:00:00+02:00",
          "max_workers": 2,
          "cost": 150
        }
      ]
    },
    {
      "id": "normal",
      "min_workers": 0,
      "max_workers": 10,
      "cost": 50,
      "times": [
        {
          "id": "monday-early",
          "start_time": "2023-11-20T06:00:00+02:00",
          "end_time": "2023-11-20T14:00:00+02:00"
        },
        {
          "id": "monday-late",
          "start_time": "2023-11-20T14:00:00+02:00",
          "end_time": "2023-11-20T22:00:00+02:00"
        },
        {
          "id": "monday-night",
          "start_time": "2023-11-20T22:00:00+02:00",
          "end_time": "2023-11-21T06:00:00+02:00",
          "cost": 100
        }
      ]
    }
  ],
  "demands": [
    {
      "start_time": "2023-11-20T06:00:00+02:00",
      "end_time": "2023-11-20T14:00:00+02:00",
      "count": 3,
      "qualification": "welding"
    },
    {
      "start_time": "2023-11-20T14:00:00+02:00",
      "end_time": "2023-11-20T22:00:00+02:00",
      "count": 2,
      "qualification": "welding"
    },
    {
      "start_time": "2023-11-20T11:00:00+02:00",
      "end_time": "2023-11-20T17:00:00+02:00",
      "count": 8
    }
  ]
}

Shift

A shift is used in the input schema.

Field name	Required	Data type	Description	Example
`id`	Yes	`string`	ID for the shift.	`{"id": "1"}`
`qualification`	No	`string`	The qualification needed for the shift.	`{"qualification": "1"}`
`min_workers`	No	`int`	The minimum number of workers for the shift.	`{"min_workers": 1}`
`max_workers`	No	`int`	The maximum number of workers for the shift.	`{"max_workers": 1}`
`cost`	No	`int`	The cost for the shift.	`{"cost": 1}`
`times`	Yes	`array` of `time`	The time windows covered by this shift.	See `time`

Time

Time is used in the shift schema.

Field name	Required	Data type	SI Unit	Description	Example
`id`	Yes	`string`	ID for the time window.	`{"id": "1"}`
`start_time`	Yes	`timestamp`	NA	The start time of this time window.	`{"start_time": "2023-01-01T00:00:00Z"}`
`end_time`	Yes	`timestamp`	NA	The end time of this time window.	`{"end_time": "2023-01-01T00:00:00Z"}`

Demand

Demand is used in the input schema.

Field name	Required	Data type	Description	Example
`start_time`	Yes	`timestamp`	NA	The start time of the predicted demand.
`end_time`	Yes	`timestamp`	NA	The end time of the predicted demand.
`count`	Yes	`int`	The amount of predicted demand.	`{"count": 1}`
`qualification`	No	`string`	The qualification needed for the demand.	`{"qualification": "1"}`

Option

Option is used in the input schema.

Field name	Required	Data type	Description	Example
`over_supply_cost`	No	`int`	The cost for oversupplying a demand.	`{"over_supply_cost": 1}`
`under_supply_cost`	No	`int`	The cost for shortfalling a demand.	`{"under_supply_cost": 1}`

Output

The output schema defines the solution to the shift planning problem in JSON format. The output schema contains the following components.

Field name	Always present	Data type	SI Unit	Description	Example
`solutions`	Yes	`array` of `solution`	NA	Solutions to the shift planning problem.	`{"solutions": []}`
`statistics`	Yes	`statistics`	NA	Summary statistics of the solution.	`{"statistics": {"total_cost": 123}}`

JSON

{
  "options": {
    "duration": 30,
    "input": "input.json",
    "output": "output.json",
    "provider": "SCIP"
  },
  "solution": {
    "planned_shifts": [
      {
        "count": 3,
        "end_time": "2023-11-20T14:00:00+02:00",
        "id": "welder_monday-early",
        "qualification": "welding",
        "shift_id": "welder",
        "start_time": "2023-11-20T06:00:00+02:00",
        "time_id": "monday-early"
      },
      {
        "count": 2,
        "end_time": "2023-11-20T22:00:00+02:00",
        "id": "welder_monday-late",
        "qualification": "welding",
        "shift_id": "welder",
        "start_time": "2023-11-20T14:00:00+02:00",
        "time_id": "monday-late"
      },
      {
        "count": 1,
        "end_time": "2023-11-21T06:00:00+02:00",
        "id": "welder_monday-night",
        "qualification": "welding",
        "shift_id": "welder",
        "start_time": "2023-11-20T22:00:00+02:00",
        "time_id": "monday-night"
      },
      {
        "count": 8,
        "end_time": "2023-11-20T14:00:00+02:00",
        "id": "normal_monday-early",
        "qualification": "",
        "shift_id": "normal",
        "start_time": "2023-11-20T06:00:00+02:00",
        "time_id": "monday-early"
      },
      {
        "count": 8,
        "end_time": "2023-11-20T22:00:00+02:00",
        "id": "normal_monday-late",
        "qualification": "",
        "shift_id": "normal",
        "start_time": "2023-11-20T14:00:00+02:00",
        "time_id": "monday-late"
      }
    ]
  },
  "statistics": {
    "result": {
      "custom": {
        "constraints": 7,
        "over_supply": 154,
        "over_supply_cost": 15400,
        "planned_count": 22,
        "planned_shifts": 5,
        "shift_cost": 1450,
        "status": "optimal",
        "under_supply": 0,
        "under_supply_cost": 0,
        "variables": 13
      },
      "duration": 0.123,
      "value": 16850
    },
    "run": {
      "duration": 0.123
    },
    "schema": "v1"
  }
}

Solution

Field name	Always present	Data type	SI Unit	Description	Example
`planned_shifts`	Yes	`array` of `planned_shift`	NA	Solution to the shift scheduling problem.	`{"planned_shifts": []}`

Planned shift

Field name	Always present	Data type	SI Unit	Description	Example
`start_time`	Yes	`timestamp`	NA	Start time of the worker's shift	`{"start_time": "2023-01-01T00:00:00Z"}`
`end_time`	Yes	`timestamp`	NA	End time of the worker's shift	`{"end_time": "2023-01-01T00:00:00Z"}`
`id`	Yes	`string`	NA	The ID of the planned shift.	`{"id": "1"}`
`shift_id`	Yes	`string`	NA	The ID of the used shift.	`{"shift_id": "1"}`
`time_id`	Yes	`string`	NA	The ID of used time of the shift.	`{"time_id": "1"}`
`qualification`	Yes	`string`	NA	The needed qualification to work the shift.	`{"qualification": "1"}`
`count`	Yes	`int`	NA	Count describes how of this shift/time combination is needed.	`{"count": "1"}`

Statistics

Field name	Always present	Data type	SI Unit	Description	Example
`result`	No	`result`	NA	Final result of the solutions.	See `result`
`run`	Yes	`run`	NA	Information about the run.	See `run`
`schema`	Yes	`string`	NA	Schema of the statistics.	`{"schema": "v1"}`

Here you can find additional definitions used in the statistics schema:

result

Field name	Always present	Data type	SI Unit	Description	Example
`duration`	Yes	`float`	`seconds`	Time duration to get to the final result.	`{"duration": 0.123}`
`value`	Yes	`float`	NA	Value of the final result.	`{"value": 0.123}`
`custom`	Yes	`any`	NA	Custom solver metrics.	See `custom`

run
Field name Always present Data type SI Unit Description Example
duration Yes float seconds Time duration of the run. {"duration": 0.123}

Field name	Always present	Data type	SI Unit	Description	Example
`duration`	Yes	`float`	`seconds`	Time duration of the run.	`{"duration": 0.123}`

custom

Field name	Always present	Data type	SI Unit	Description	Example
`constraints`	Yes	`int`	NA	Number of constraints.	`{"constraints": 123}`
`provider`	Yes	`string`	NA	Solver provider.	`{"provider": "highs"}`
`status`	Yes	`string`	NA	Solver status.	`{"status": "optimal"}`
`variables`	Yes	`int`	NA	Number of variables.	`{"variables": 123}`

Run options

These are the default options that are available with shift planning.

Bash (OR-Tools)
Bash (Pyomo)

usage: main.py [options]

Options for main.py. Use command-line arguments (highest precedence) or
environment variables.

options:
  -h, --help            show this help message and exit
  -input INPUT, --input INPUT
                        [env var: INPUT] (default: ) (type: str): Path to
                        input file. Default is stdin.
  -output OUTPUT, --output OUTPUT
                        [env var: OUTPUT] (default: ) (type: str): Path to
                        output file. Default is stdout.
  -duration DURATION, --duration DURATION
                        [env var: DURATION] (default: 30) (type: int): Max
                        runtime duration (in seconds).
  -provider PROVIDER, --provider PROVIDER
                        [env var: PROVIDER] (default: SCIP) (type: str):
                        Solver provider.

A how-to guide for specifying the input and output schemas in shift planning.