Shift assignment

The shift assignment 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.assign.ortools

Bash

nextmv community clone -a python-ortools-shiftassignment

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

Bash

nextmv sdk init -t python-pyomo-shiftassignment

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
`workers`	Yes	`array` of `worker`	NA	Workers to assign.	See `worker`
`shifts`	Yes	`array` of `shift`	NA	Available shifts with some additional properties.	See `shift`
`rules`	Yes	`array` of `rule`	NA	Defines a set of rules to obey.	See `rule`

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

JSON

{
  "workers": [
    {
      "id": "Louis Hardy",
      "qualifications": ["welding"],
      "rules": "standard",
      "preferences": {
        "welder_monday-early": 1,
        "welder_monday-late": 1
      },
      "availability": [
        {
          "start_time": "2023-11-20T00:00:00+02:00",
          "end_time": "2023-11-21T00:00:00+02:00"
        },
        {
          "start_time": "2023-11-21T00:00:00+02:00",
          "end_time": "2023-11-22T00:00:00+02:00"
        }
      ]
    },
    {
      "id": "Jacob Cunningham",
      "qualifications": ["welding"],
      "rules": "standard",
      "preferences": {
        "welder_monday-early": 1,
        "normal_monday-early": 1
      },
      "availability": [
        {
          "start_time": "2023-11-20T00:00:00+02:00",
          "end_time": "2023-11-21T00:00:00+02:00"
        },
        {
          "start_time": "2023-11-21T00:00:00+02:00",
          "end_time": "2023-11-22T00:00:00+02:00"
        }
      ]
    },
    {
      "id": "Ray Heard",
      "qualifications": ["welding"],
      "rules": "standard",
      "preferences": {
        "welder_monday-early": 1,
        "normal_monday-early": 1
      },
      "availability": [
        {
          "start_time": "2023-11-20T00:00:00+02:00",
          "end_time": "2023-11-21T00:00:00+02:00"
        },
        {
          "start_time": "2023-11-21T00:00:00+02:00",
          "end_time": "2023-11-22T00:00:00+02:00"
        }
      ]
    },
    {
      "id": "Mark Leath",
      "qualifications": [],
      "rules": "standard",
      "preferences": {
        "normal_monday-late": 1
      },
      "availability": [
        {
          "start_time": "2023-11-20T00:00:00+02:00",
          "end_time": "2023-11-21T00:00:00+02:00"
        },
        {
          "start_time": "2023-11-21T00:00:00+02:00",
          "end_time": "2023-11-22T00:00:00+02:00"
        }
      ]
    },
    {
      "id": "Dylan Mccormack",
      "qualifications": [],
      "rules": "standard",
      "availability": [
        {
          "start_time": "2023-11-20T00:00:00+02:00",
          "end_time": "2023-11-21T00:00:00+02:00"
        },
        {
          "start_time": "2023-11-21T00:00:00+02:00",
          "end_time": "2023-11-22T00:00:00+02:00"
        }
      ]
    }
  ],
  "rules": [
    {
      "id": "standard",
      "min_rest_hours_between_shifts": 11
    }
  ],
  "shifts": [
    {
      "id": "welder_monday-early",
      "shift_id": "welder",
      "time_id": "monday-early",
      "start_time": "2023-11-20T06:00:00+02:00",
      "end_time": "2023-11-20T14:00:00+02:00",
      "qualification": "welding",
      "count": 1
    },
    {
      "id": "welder_monday-late",
      "shift_id": "welder",
      "time_id": "monday-late",
      "start_time": "2023-11-20T14:00:00+02:00",
      "end_time": "2023-11-20T22:00:00+02:00",
      "qualification": "welding",
      "count": 1
    },
    {
      "id": "normal_monday-early",
      "shift_id": "normal",
      "time_id": "monday-early",
      "start_time": "2023-11-20T06:00:00+02:00",
      "end_time": "2023-11-20T14:00:00+02:00",
      "qualification": "",
      "count": 2
    },
    {
      "id": "normal_monday-late",
      "shift_id": "normal",
      "time_id": "monday-late",
      "start_time": "2023-11-20T14:00:00+02:00",
      "end_time": "2023-11-20T22:00:00+02:00",
      "qualification": "",
      "count": 1
    }
  ]
}

Worker

A worker is used in the input schema.

Field name	Required	Data type	Description	Example
`availability`	Yes	`array` of `availability`	The availability times of the worker	See `availability`
`id`	Yes	`string`	ID for the worker.	`{"id": "1"}`
`rules`	Yes	`string`	ID of a rule to comply with (see rule).	`{"rules": ["foo", "bar"]}`
`qualifications`	Yes	`array` of `string`	A set of qualifications/skills a worker has.	`{"qualifications": ["foo", "bar"]}`
`preferences`	Yes	`map` of `string` to `int`	Defines preferred shifts, a higher number means more important.	`"preferences": {"shift1": "1"}`

Availability

Availability is used in the worker schema.

Field name	Required	Data type	SI Unit	Description	Example
`start_time`	Yes	`timestamp`	NA	The start of an availability time window for a worker.	`{"start_time": "2023-01-01T00:00:00Z"}`
`end_time`	Yes	`timestamp`	NA	The end of an availability time window for a worker.	`{"end_time": "2023-01-01T00:00:00Z"}`

Shift

Shift is used in the input schema.

Field name	Required	Data type	Description	Example
`start_time`	Yes	`timestamp`	The start time of a shift.	`{"start": "2023-01-01T00:00:00Z"}`
`end_time`	Yes	`timestamp`	The end time of a shift.	`{"end": "2023-01-01T00:00:00Z"}`
`count`	Yes	`int`	The number of workers needed for the shift.	`{"count": 1}`
`shift_id`	Yes	`string`	ID of the shift type.	`{"shift_id": "1"}`
`time_id`	Yes	`string`	ID of the shift type and time combination.	`{"time_id": "1"}`
`qualification`	Yes	`string`	The qualification needed to work this shift.	`{"qualification": "1"}`

Rule

Rule is used in the input schema.

Field name	Required	Data type	Description	Example
`id`	Yes	`string`	ID of the rule.	`{"id": "1"}`
`min_rest_hours_between_shifts`	Yes	`integer`	Defines the number of hours a worker must rest between shifts.	`{"min_rest_hours_between_shifts": 1}`

Output

The output schema defines the solution to the shift assignment 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 assignment problem.	`{"solutions": []}`
`statistics`	Yes	`statistics`	NA	Summary statistics of the solution.	`{"statistics": {"total_cost": 123}}`

JSON

{
  "assets": [],
  "options": {
    "duration": 30,
    "factor_balance_total_hours": 0,
    "factor_maximize_preferences": 1,
    "factor_maximize_weekly_hours_per_worker": 0,
    "input": "input.json",
    "output": "output.json",
    "provider": "SCIP"
  },
  "solution": {
    "assigned_shifts": [
      {
        "end_time": "2023-11-20T22:00:00+02:00",
        "shift_id": "welder_monday-late",
        "start_time": "2023-11-20T14:00:00+02:00",
        "worker_id": "Louis Hardy"
      },
      {
        "end_time": "2023-11-20T14:00:00+02:00",
        "shift_id": "welder_monday-early",
        "start_time": "2023-11-20T06:00:00+02:00",
        "worker_id": "Jacob Cunningham"
      },
      {
        "end_time": "2023-11-20T14:00:00+02:00",
        "shift_id": "normal_monday-early",
        "start_time": "2023-11-20T06:00:00+02:00",
        "worker_id": "Ray Heard"
      },
      {
        "end_time": "2023-11-20T22:00:00+02:00",
        "shift_id": "normal_monday-late",
        "start_time": "2023-11-20T14:00:00+02:00",
        "worker_id": "Mark Leath"
      },
      {
        "end_time": "2023-11-20T14:00:00+02:00",
        "shift_id": "normal_monday-early",
        "start_time": "2023-11-20T06:00:00+02:00",
        "worker_id": "Dylan Mccormack"
      }
    ]
  },
  "statistics": {
    "result": {
      "custom": {
        "active_workers": 5,
        "constraints": 59,
        "mean_hours_worked": 8,
        "preferences_matched": 4,
        "status": "optimal",
        "total_workers": 5,
        "variables": 30,
        "variance_hours_worked": 0
      },
      "duration": 0.123,
      "value": 4
    },
    "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 shift	`{"start_time": "2023-01-01T00:00:00Z"}`
`end_time`	Yes	`timestamp`	NA	End time of the shift	`{"end_time": "2023-01-01T00:00:00Z"}`
`id`	Yes	`string`	NA	The ID of shift, time and qualification combination.	`{"id": "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": "SCIP"}`
`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 assignment.

Bash

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.
  -factor-maximize-weekly-hours-per-worker FACTOR_MAXIMIZE_WEEKLY_HOURS_PER_WORKER, --factor-maximize-weekly-hours-per-worker FACTOR_MAXIMIZE_WEEKLY_HOURS_PER_WORKER
                        [env var: FACTOR-MAXIMIZE-WEEKLY-HOURS-PER-WORKER]
                        (default: 0.0) (type: float): Weight to apply for
                        maximizing total weekly hours per worker (up to
                        allowed maximum).
  -factor-balance-total-hours FACTOR_BALANCE_TOTAL_HOURS, --factor-balance-total-hours FACTOR_BALANCE_TOTAL_HOURS
                        [env var: FACTOR-BALANCE-TOTAL-HOURS] (default: 0.0)
                        (type: float): Weight to apply for balancing worker
                        hours.
  -factor-maximize-preferences FACTOR_MAXIMIZE_PREFERENCES, --factor-maximize-preferences FACTOR_MAXIMIZE_PREFERENCES
                        [env var: FACTOR-MAXIMIZE-PREFERENCES] (default: 1.0)
                        (type: float): Weight to apply for total preference
                        matches.

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