Method: scheduling.solveShiftGeneration

Solves a shift generation problem from the given SolveShiftGenerationRequest by generating shifts from given shift templates in order to cover the employee demand.

HTTP request

POST https://optimization.googleapis.com/v1/scheduling:solveShiftGeneration

The URL uses gRPC Transcoding syntax.

Request body

The request body contains data with the following structure:

JSON representation
{ "solverConfig": { object (`SolverConfig`) }, "shiftTemplates": [ { object (`ShiftTemplate`) } ], "employeeDemands": [ { object (`EmployeeDemand`) } ] }

Fields

Fields
`solverConfig`	`object (SolverConfig)` Optional. Parameters for the solver.
`shiftTemplates[]`	`object (ShiftTemplate)` Required. Set of shift templates specifying rules for generating shifts.
`employeeDemands[]`	`object (EmployeeDemand)` Required. Total employee demand that the shifts generated by `shiftTemplates` need to cover.

solverConfig

object (SolverConfig)

Optional. Parameters for the solver.

shiftTemplates[]

object (ShiftTemplate)

Required. Set of shift templates specifying rules for generating shifts.

employeeDemands[]

object (EmployeeDemand)

Required. Total employee demand that the shifts generated by shiftTemplates need to cover.

Response body

Response for the Shift Generation problem. If the solutionStatus returned is SOLVED, then a set of valid shifts generated by the solver are returned in employeeSchedules. For a valid shift schedule, the following properties hold:

Each shift generated in employeeSchedules adheres to the rules specified in the corresponding ShiftTemplate.
Each event selected in each shift adheres to the rules specified in the corresponding ShiftTemplate.Event.
The total number of employees assigned to the set of shifts generated from the same ShiftTemplate does not exceed maximumEmployeeCount of that template.
The set of assigned employees cover the demand at every given interval.

If successful, the response body contains data with the following structure:

JSON representation
{ "solutionStatus": enum (`ShiftGenerationSolutionStatus`), "employeeSchedules": [ { object (`EmployeeSchedule`) } ], "demandCoverageViolations": [ { object (`DemandCoverageViolation`) } ] }

Fields

Fields
`solutionStatus`	`enum (ShiftGenerationSolutionStatus)` Status of the returned solution. If `solutionStatus` is not `SOLVED`, `employeeSchedules` will be empty.
`employeeSchedules[]`	`object (EmployeeSchedule)` Set of shifts generated by the solver along with the number of employees assigned to each schedule.
`demandCoverageViolations[]`	`object (DemandCoverageViolation)` Demand coverage violations based on the assigned `employee_counts` in the given `employeeSchedules`. The `employeeDemands` given in the request are aggregated -- if two `employee_demand` intervals overlap, the demand is summed over the overlapping portion of the interval.

solutionStatus

enum (ShiftGenerationSolutionStatus)

Status of the returned solution. If solutionStatus is not SOLVED, employeeSchedules will be empty.

employeeSchedules[]

object (EmployeeSchedule)

Set of shifts generated by the solver along with the number of employees assigned to each schedule.

demandCoverageViolations[]

object (DemandCoverageViolation)

Demand coverage violations based on the assigned employee_counts in the given employeeSchedules. The employeeDemands given in the request are aggregated -- if two employee_demand intervals overlap, the demand is summed over the overlapping portion of the interval.

SolverConfig

Specifies additional parameters for solving the Shift Generation problem.

JSON representation
{ "timeLimit": string, "multiDaySchedule": boolean, "shiftEventsCanChange": boolean }

Fields

Fields
`timeLimit`	`string (Duration format)` Maximum time the solver should spend on the problem. If not set, defaults to 1 minute. The choice of a time limit should depend on the size of the problem. To give an example, when solving a 7-day instance with 2 `ShiftTemplates`, each with ~20 possible start times and holding 2 events with ~30 possible start times, and two days off per week, recommended values are: <10s for fast solutions (and likely suboptimal), (10s, 300s) for good quality solutions, and >300s for an exhaustive search. Larger instances may require longer time limits. This value is not a hard limit and it does not account for the communication overhead. The expected latency to solve the problem may slightly exceed this value. A duration in seconds with up to nine fractional digits, ending with '`s`'. Example: `"3.5s"`.
`multiDaySchedule`	`boolean` If true, the solver generates `EmployeeSchedule`s that include several shifts (e.g., to generate a week-long schedule). Otherwise, each `EmployeeSchedule` includes exactly one shift. Multi-day schedules assume that the start time of the shift is the same across days, and the number of days off in such a schedule is determined by the shift templates. Default is false.
`shiftEventsCanChange`	`boolean` If true, multi-day `EmployeeSchedule`s may include shifts for which the start and end time of their events vary across all days. Otherwise, all shifts of a particular `EmployeeSchedule` must have the same event's start and end times. In either case, all the shifts of a multi-day schedule have the same start and end time. As such this parameter is ignored if `multiDaySchedule` is false. Setting this parameter to true may result in longer solve times. Default is false.

timeLimit

string (Duration format)

Maximum time the solver should spend on the problem. If not set, defaults to 1 minute. The choice of a time limit should depend on the size of the problem. To give an example, when solving a 7-day instance with 2 ShiftTemplates, each with ~20 possible start times and holding 2 events with ~30 possible start times, and two days off per week, recommended values are: <10s for fast solutions (and likely suboptimal), (10s, 300s) for good quality solutions, and >300s for an exhaustive search. Larger instances may require longer time limits.

This value is not a hard limit and it does not account for the communication overhead. The expected latency to solve the problem may slightly exceed this value.

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".

multiDaySchedule

boolean

If true, the solver generates EmployeeSchedules that include several shifts (e.g., to generate a week-long schedule). Otherwise, each EmployeeSchedule includes exactly one shift. Multi-day schedules assume that the start time of the shift is the same across days, and the number of days off in such a schedule is determined by the shift templates. Default is false.

shiftEventsCanChange

boolean

If true, multi-day EmployeeSchedules may include shifts for which the start and end time of their events vary across all days. Otherwise, all shifts of a particular EmployeeSchedule must have the same event's start and end times. In either case, all the shifts of a multi-day schedule have the same start and end time. As such this parameter is ignored if multiDaySchedule is false. Setting this parameter to true may result in longer solve times. Default is false.

ShiftTemplate

Template specifying rules for generating shifts. A shift is a unit of work that specifies a start time, end time, and may contain events (i.e. lunch, breaks, etc). A shift will be assigned to a specific date in the response.

JSON representation

JSON representation
{ "id": string, "earliestStartTime": { object (`TimeOfDay`) }, "latestStartTime": { object (`TimeOfDay`) }, "durationMinutes": integer, "startTimeIncrementMinutes": integer, "daysOffCountPerWeek": integer, "eventTemplates": [ { object (`EventTemplate`) } ], "minimumIntereventGapMinutes": integer, "maximumEmployeeCount": integer }

{
  "id": string,
  "earliestStartTime": {
    object (TimeOfDay)
  },
  "latestStartTime": {
    object (TimeOfDay)
  },
  "durationMinutes": integer,
  "startTimeIncrementMinutes": integer,
  "daysOffCountPerWeek": integer,
  "eventTemplates": [
    {
      object (EventTemplate)
    }
  ],
  "minimumIntereventGapMinutes": integer,
  "maximumEmployeeCount": integer
}

Fields
`id`	`string` Unique ID of this template.
`earliestStartTime`	`object (TimeOfDay)` Earliest time in the day that a shift can start. This value is specified with hours and minutes; seconds and nanos are ignored.
`latestStartTime`	`object (TimeOfDay)` Latest time in the day that a shift can start. This value is specified with hours and minutes; seconds and nanos are ignored. If this value is less than the `earliestStartTime`, then a shift generated by this template may start before or after midnight.
`durationMinutes`	`integer` Fixed duration of a shift generated by this template.
`startTimeIncrementMinutes`	`integer` The time increment (in minutes) used to generate the set of possible start times between `earliestStartTime` and `latestStartTime`. For example, if the earliest start time is 8:00, the latest start time is 8:30, and the start time increment is 10 minutes, then all possible start times for this shift template are: 8:00, 8:10, 8:20, and 8:30.
`daysOffCountPerWeek`	`integer` Fixed number of days off per week. An employee has a given day off if they are not assigned to a shift that starts on that day. A week is 7 days and begins on Sunday.
`eventTemplates[]`	`object (EventTemplate)` Rules for generating events for each shift. Exactly one event will be included in each shift for each Event specified.
`minimumIntereventGapMinutes`	`integer` Minimum minutes between the end of one event and the start of the next.
`maximumEmployeeCount`	`integer` Maximum number of employees that can be assigned to all shifts generated by this template.

TimeOfDay

Represents a time of day. The date and time zone are either not significant or are specified elsewhere. An API may choose to allow leap seconds. Related types are google.type.Date and google.protobuf.Timestamp.

JSON representation
{ "hours": integer, "minutes": integer, "seconds": integer, "nanos": integer }

Fields
`hours`	`integer` Hours of day in 24 hour format. Should be from 0 to 23. An API may choose to allow the value "24:00:00" for scenarios like business closing time.
`minutes`	`integer` Minutes of hour of day. Must be from 0 to 59.
`seconds`	`integer` Seconds of minutes of the time. Must normally be from 0 to 59. An API may allow the value 60 if it allows leap-seconds.
`nanos`	`integer` Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999.

EventTemplate

Template specifying rules for generating a single event that occurs during a shift. An event may represent a meeting, break, lunch, etc.

JSON representation
{ "id": string, "minimumMinutesAfterShiftStart": integer, "maximumMinutesAfterShiftStart": integer, "durationMinutes": integer, "startTimeIncrementMinutes": integer }

Fields
`id`	`string` Unique ID of this template.
`minimumMinutesAfterShiftStart`	`integer` Minimum number of minutes after the beginning of a shift that this event can start.
`maximumMinutesAfterShiftStart`	`integer` Maximum number of minutes after the beginning of a shift that this event can start.
`durationMinutes`	`integer` Fixed duration in minutes of this event.
`startTimeIncrementMinutes`	`integer` The time increment (in minutes) used to generate the set of possible event start times between `minimumMinutesAfterShiftStart` and `maximumMinutesAfterShiftStart`. For example, if the minimum minutes after shift start are 30, maximum minutes after shift start are 45, and the start time increment is 5 minutes, the event can take place 30, 35, 40, or 45 minutes after the start of the shift.

EmployeeDemand

Specifies the number of employees required to cover the demand in the given DateTime interval.

JSON representation
{ "startDateTime": { object (`DateTime`) }, "endDateTime": { object (`DateTime`) }, "employeeCount": integer }

Fields

Fields
`startDateTime`	`object (DateTime)` Start of the time interval for the given demand (inclusive). These values are read down to the minute; seconds and all smaller units are ignored.
`endDateTime`	`object (DateTime)` End of the time interval for the given demand (exclusive). These values are read down to the minute; seconds and all smaller units are ignored.
`employeeCount`	`integer` Number of employees needed to cover the demand for this interval.

startDateTime

object (DateTime)

Start of the time interval for the given demand (inclusive). These values are read down to the minute; seconds and all smaller units are ignored.

endDateTime

object (DateTime)

End of the time interval for the given demand (exclusive). These values are read down to the minute; seconds and all smaller units are ignored.

employeeCount

integer

Number of employees needed to cover the demand for this interval.

ShiftGenerationSolutionStatus

Solution status provided in the response of a solver.

Enums
`SHIFT_GENERATION_SOLUTION_STATUS_UNSPECIFIED`	Unspecified status for the response.
`SHIFT_GENERATION_SOLVED`	The solver found a solution in the time limit provided.
`SHIFT_GENERATION_NOT_SOLVED`	An issue prevented the solver from generating shifts.
`SHIFT_GENERATION_NOT_SOLVED_DEADLINE_EXCEEDED`	Shifts could not be generated to cover the demand within the time limit given.

EmployeeSchedule

An ordered list of shifts corresponding to a single ShiftTemplate that is to be assigned to a number of employees.

JSON representation
{ "shiftTemplateId": string, "shifts": [ { object (`ShiftWithEvents`) } ], "employeeCount": integer }

Fields

Fields
`shiftTemplateId`	`string` ID of the template that was used to generate this set of shifts.
`shifts[]`	`object (ShiftWithEvents)` List of shifts to which `employeeCount` number of employees are assigned. Shifts and events selected for the schedule were generated from a single template. Shifts are sorted chronologically and do not overlap. If the `SolverConfig.multi_day_schedule` is true, a day off is represented implicitly by the absence of a shift starting on that day.
`employeeCount`	`integer` Number of employees that should be assigned to this set of shifts to cover the demand.

shiftTemplateId

string

ID of the template that was used to generate this set of shifts.

shifts[]

object (ShiftWithEvents)

List of shifts to which employeeCount number of employees are assigned. Shifts and events selected for the schedule were generated from a single template. Shifts are sorted chronologically and do not overlap. If the SolverConfig.multi_day_schedule is true, a day off is represented implicitly by the absence of a shift starting on that day.

employeeCount

integer

Number of employees that should be assigned to this set of shifts to cover the demand.

ShiftWithEvents

Specifies the start and end date along with a list of fixed events of a shift generated by the solver.

JSON representation
{ "startDateTime": { object (`DateTime`) }, "endDateTime": { object (`DateTime`) }, "events": [ { object (`Event`) } ] }

Fields

Fields
`startDateTime`	`object (DateTime)` Start date and time of the shift. This value is specified down to the minute; seconds and smaller units are not given.
`endDateTime`	`object (DateTime)` End date and time of the shift. This value is specified down to the minute; seconds and smaller units are not given.
`events[]`	`object (Event)` List of events included in this shift, mapped exactly to, and in the same order as, the `ShiftTemplate.Event`s. If `SolverConfig.shift_events_can_change` is true, the start and end times of the events may vary across all the `ShiftWithEvents` of this schedule.

startDateTime

object (DateTime)

Start date and time of the shift. This value is specified down to the minute; seconds and smaller units are not given.

endDateTime

object (DateTime)

End date and time of the shift. This value is specified down to the minute; seconds and smaller units are not given.

events[]

object (Event)

List of events included in this shift, mapped exactly to, and in the same order as, the ShiftTemplate.Events. If SolverConfig.shift_events_can_change is true, the start and end times of the events may vary across all the ShiftWithEvents of this schedule.

Event

Specifies the start and end DateTime of a specific event in a shift generated by the solver.

JSON representation
{ "eventTemplateId": string, "startDateTime": { object (`DateTime`) }, "endDateTime": { object (`DateTime`) } }

Fields

Fields
`eventTemplateId`	`string` ID of the template that was used to generate this event.
`startDateTime`	`object (DateTime)` Start date and time of the event. This value is specified down to the minute; seconds and smaller units are not given.
`endDateTime`	`object (DateTime)` End date and time of the event. This value is specified down to the minute; seconds and smaller units are not given.

eventTemplateId

string

ID of the template that was used to generate this event.

startDateTime

object (DateTime)

Start date and time of the event. This value is specified down to the minute; seconds and smaller units are not given.

endDateTime

object (DateTime)

End date and time of the event. This value is specified down to the minute; seconds and smaller units are not given.

DemandCoverageViolation

Specifies the demand coverage violation for the given interval. The employee demand is the same throughout the entire specified interval.

JSON representation
{ "startDateTime": { object (`DateTime`) }, "endDateTime": { object (`DateTime`) }, "coverageViolation": integer }

Fields

Fields
`startDateTime`	`object (DateTime)` Start date and time of the demand interval (inclusive). This value is specified down to the minute.
`endDateTime`	`object (DateTime)` End date and time of the demand interval (exclusive). This value is specified down to the minute.
`coverageViolation`	`integer` Coverage violation during the specified interval. A positive value indicates that the demand is overcovered, and a negative value indicates that the demand is undercovered.

startDateTime

object (DateTime)

Start date and time of the demand interval (inclusive). This value is specified down to the minute.

endDateTime

object (DateTime)

End date and time of the demand interval (exclusive). This value is specified down to the minute.

coverageViolation

integer

Coverage violation during the specified interval. A positive value indicates that the demand is overcovered, and a negative value indicates that the demand is undercovered.