Demands

Demand is the need for workforce and defines how many employees you need at work at any given time in the planning period. Specifying demands in the payload is done using the Demands property.

Demand schema

object

Show properties

object

List of days in the schedule.

Show days – properties

array of date (date)

List of dates in the schedule. Only allowed in CALENDAR payloads.

array of dayIndex

List of day indices in the schedule. Only allowed in RECURRING payloads.

array of dayOfWeek

List of days of the week. Will apply to all days in the schedule that match any of the specified weekdays.

array of object

List of shift demands that exist on the days specified in the days field.

Show shiftDemands – item structure

string

Id of the single shift that must fulfill this demand. Specify exactly one of shiftId or shifts.

object

Filters entities by id and label.

Show shifts – properties

array of string

Entity ids to match.

array of string

Entity labels to match.

object

Show matchTypes – properties

string (enum: NONE | ANY | ALL)

Used to indicate how to apply the id filters. For example, if set to NONE, entities with the specified ids will be excluded. Default: “ANY”.

string (enum: NONE | ANY | ALL)

Used to indicate how to apply the label filters. For example, if set to ANY, entities that have any of the specified labels will be included. Default: “ANY”.

integer

Minimum number of employees needed to cover the demand. We will try to cover the demand with at least this number of employees. If not specified, will be equal to ideal.

integer

required

Ideal number of employees needed to cover the demand. We prefer to cover the demand with exactly this number of employees.

integer

Maximum number of employees needed to cover the demand. We will never assign more employees to cover the demand than this number. If not specified, will be equal to ideal.

array of object

List of requirements on the attributes that an employee must meet to be eligible to cover this shift demand.

Show attributeRequirementGroups – item structure

array of object

Show attributeRequirements – item structure

string

The category of the attribute.

array of string

The targeted values for this requirement.

string (enum: NONE | ANY | ALL)

Default: “ALL”.

integer

Minimum number of required employees that match the requirement.

number

Priority of this demand. Increasing a demand’s priority will make it prioritized compared to other demands, but also compared to rules. Default: 1.

array of object

List of time demands that exist on the days specified in the days field.

Show timeDemands – item structure

string

required

Id of the time slot for which there is demand.

integer

Minimum number of employees needed to cover the demand. We will try to cover the demand with at least this number of employees. If not specified, will be equal to ideal.

integer

required

Ideal number of employees needed to cover the demand. We prefer to cover the demand with exactly this number of employees.

integer

Maximum number of employees needed to cover the demand. We will never assign more employees to cover the demand than this number. If not specified, will be equal to ideal.

number

Priority of this demand. Increasing a demand’s priority will make it prioritized compared to other demands, but also compared to rules. Default: 1.

The Automatic Rostering API allows you to define demand for workforce in two different ways:

ShiftDemand allows you to specify demand by stating which shifts you need on which days, and how many people you need working those shifts.
TimeDemand allows you to specify demand by stating how many employees you need at different times of day throughout your schedule. The API will then assign shifts to cover the demand at those times.

A request to the Automatic Rostering API should either specify all demand as ShiftDemand, or all demand as TimeDemand. A combination of both is currently not supported.

Choose which type of demand suits your needs, then find below some pointers on how to configure the Demands object for your use case.

ShiftDemand

If you have already configured Shifts in your request, then using these to specify ShiftDemand is very simple. Consider the following example.

The following shows how to specify that on days 1 and 2 you require 2 people to work Shift A and 2 people to work Shift B, while on day 3 you only require 2 people working Shift B.

{
  "demands": [
    {
      "days": {
        "dayIndices": [0, 1]
      },
      "shiftDemands": [
        {
          "shiftId": "shift-a",
          "ideal": 2
        },
        {
          "shiftId": "shift-b",
          "ideal": 2
        }
      ]
    },
    {
      "days": {
        "dayIndices": [2]
      },
      "shiftDemands": [
        {
          "shiftId": "shift-b",
          "ideal": 2
        }
      ]
    }
  ]
}

A ShiftDemand must contain exactly one of shiftId or shifts. Use shiftId when one specific shift must fulfill the demand, like the example above. Use shifts when any shift matching the supplied IDs and labels may fulfill the same demand. Employees assigned across the alternative shifts count toward the same min, ideal, and max levels. When the eligible shifts have different durations, minute-based shortage metrics use the shortest eligible shift duration.

This demand can be fulfilled by any shift with the early label.

{
  "demands": [
    {
      "days": {
        "dayIndices": [0]
      },
      "shiftDemands": [
        {
          "shifts": {
            "labels": ["early"]
          },
          "ideal": 2
        }
      ]
    }
  ]
}

Attribute requirements

In principle, all employees assigned to a demand must be compatible with the attribute requirements on that demand. However, it is also possible to specify a minimum number of assigned employees that must be compatible.

The first demand requires all employees to be able to drive. For the second demand, at least one of the assigned employees should be a nurse.

{
  "demands": [
    {
      "shiftDemands": [
        {
          "shiftId": "shift1",
          "ideal": 2,
          "attributeRequirementGroups": [
            {
              "attributeRequirements": [
                {
                  "category": "competences",
                  "values": ["driving"]
                }
              ]
            }
          ]
        },
        {
          "shiftId": "shift2",
          "ideal": 2,
          "attributeRequirementGroups": [
            {
              "attributeRequirements": [
                {
                  "category": "personnelGroup",
                  "values": ["nurses"]
                }
              ],
              "min": 1
            }
          ]
        }
      ]
    }
  ]
}

Demand coverage

By default, each assigned shift covers one compatible shift demand. This is equivalent to omitting context.demandCoverageType, or setting it to SINGLE. Set context.demandCoverageType to MULTIPLE when one assignment should cover every shift demand on the same day shift that is compatible with the assigned employee and role. This is useful when several demand lines describe staffing needs that can be fulfilled by the same physical shift. MULTIPLE is only supported for ShiftDemand.

TimeDemand

When demand is defined as the time periods for when employees are needed, the solver assigns employees to the shifts that are able to cover this demand.

Getting started

Entities

Concepts

Reasoning

Status updates

Demand schema

ShiftDemand

Attribute requirements

Demand coverage

TimeDemand