Package google.research.optimization.v1.workforce

Index

Break

A time period in which an employee interrupts their work during a shift.

Fields
start_date_time

DateTime

The start time of a break.

duration_minutes

int32

Duration of the break in minutes.

BreakRule

A rule that determines when a break can start within a shift and its duration. The list of all possible breaks that are considered is determined in increments of rule_increment_minutes. For example, if a break rule is modeling a 30-minute break that can start between 10:00 and 11:00, and the rule increment is of 20 minutes, the list of breaks that are considered are: [10:00, 10:30], [10:20, 10:50], [10:40, 11:10], [11:00, 11:30].

Fields
earliest_start_time

DateTime

The earliest start time of the break (inclusive). Only hours and minutes can be set.

latest_start_time

DateTime

The latest start time of the break (inclusive). Only hours and minutes can be set.

duration_minutes

int32

Duration of the break in minutes.

rule_increment_minutes

int32

[Optional] Time increment in minutes for all the breaks that can be considered in this break rule. If not set, defaults to duration_minutes.

BudgetRequirement

Budget requirements for a given interval.

Fields
total_budget

double

Total budget for the given interval. A total budget must be given if the priority is PRIORITY_MANDATORY.

If total_budget is not set, then the total cost of the schedule is minimized according to the specified priority. For example, if the priority for the budget is PRIORITY_MEDIUM, then the solver will minimize the cost before reducing any constraint violation with priority PRIORITY_LOW.

start_date_time

DateTime

Start time for when this budget applies. If a start time is not specified, it is set to be the earliest start time of all given shifts.

end_date_time

DateTime

End time for when this budget applies. If an end time is not specified, it is set to be the latest end time of all given shifts.

priority

Priority

Priority level for meeting the budget requirement during the specified time window. The default priority is PRIORITY_LOW. If the priority is set to PRIORITY_MANDATORY, then total_budget must be set.

Note that if this priority is higher than other constraint priorities and if total_budget is tight, then the resulting schedule could significantly violate both employee constraints or coverage requirements.

CoverageRequirement

A coverage requirement specifies the number of employees required for a set of roles and/or skills during a particular time window and at a given location. DateTime intervals at a particular location cannot overlap. Alternatively, a list of shift IDs can be provided instead of a time window and a location. Only employees which can be assigned to the specific role (or that possess the specific skill) can meet this requirement.

For a given role and/or skill, the coverage requirement is fulfilled when at least target_employee_count number of employees are working at every moment in the time window (or for every shift in shift_ids). In contrast, the coverage requirement is violated if at any point in the time window (or for any of the shifts in shift_ids), there are fewer than target_employee_count number of employees working during the time window. More working employees than the target_employee_count still fulfills the requirement, but excessive staffing is minimized by the solver.

Fields
start_date_time

DateTime

The start time for the coverage requirement (inclusive). If set, shift_ids must be empty.

end_date_time

DateTime

The end time for the coverage requirement (exclusive). If set, shift_ids must be empty.

location_id

string

Location in which the employees are needed. shift_ids is not empty, this field must be empty.

shift_ids[]

string

If set, the role and skill requirements are applied individually to every shift ID in this list. If shift_ids are nonempty, then start_date_time, end_date_time, and location_id must be empty.

role_requirements[]

RoleRequirement

Required number of employees to be assigned to the specified roles during the time window. At most one role_requirement must be given for each role ID. The default priority level for each of the requirements is PRIORITY_MANDATORY. These constraints are violated if fewer than target_employee_count number of employees are assigned to the specified roles at any point during the time window.

skill_requirements[]

SkillRequirement

Required number of employees with the specified skills that are assigned to shifts during the time window. At most one skill_requirement must be given for each skill ID. The default priority level for each of the requirements is PRIORITY_LOW. These constraints are violated if fewer than target_employee_count number of employees possess the given skills at any point during the time window.

RoleRequirement

Required number of employees to be assigned to the specified role during the time window.

Fields
role_id

string

Role ID for the requirement.

target_employee_count

int32

Desired number of employees assigned to the role during the time window.

priority

Priority

Priority level for this requirement constraint. The default priority for all resource constraints is PRIORITY_MANDATORY.

SkillRequirement

Required number of employees that are working during the time window and possess the specified skill.

Fields
skill_id

string

Skill ID for the requirement.

target_employee_count

int32

Desired number of employees with the given skill that are working during the time window.

priority

Priority

Priority level for this requirement constraint. The default priority for all resource constraints is PRIORITY_LOW.

DemandCoverageViolation

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

Fields
start_date_time

DateTime

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

end_date_time

DateTime

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

coverage_violation

int32

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.

Employee

An employee from the workforce to be scheduled.

Fields
id

string

Unique ID assigned to this employee.

role_ids[]

string

Role IDs that this employee can perform. There must be at least one role specified. When an employee is assigned to a shift, they are also assigned to a single role from this list. The employee may be assigned to different roles during the scheduling window.

skill_ids[]

string

Skill IDs that this employee possesses. This list can be empty. When an employee is assigned to a shift, they use any subset of the skills listed here to cover skill requirements throughout the duration of the assigned shift.

shift_preferences[]

ShiftPreference

Shift preferences of this employee. The shifts specified here represent shifts the employee would prefer to be assigned to during the scheduling window. The shift IDs specified in shift_preferences must be unique. The solver will try to maximize the sum of the ShiftPreference.preference values over all shift_preferences that are satisfied.

scheduling_constraints[]

SchedulingConstraint

List of scheduling constraints for this employee. The default priority level for each of these constraints is PRIORITY_MEDIUM. See the Priority enum for more details.

resource_constraints[]

ResourceConstraint

Any additional scheduling constraints not specified in scheduling_constraints can be added here to resource_constraints. A ResourceConstraint is a more abstract representation for limiting resources for an employee. The default priority level for each of these constraints is PRIORITY_MEDIUM. See the Priority enum for more details.

shift_requests[]

ShiftRequest

List of shift requests for the employee. The request can be for an employee to be assigned or not assigned to specific shifts. Any fixed scheduling assignments for the employee can be represented with a ShiftRequest with priority PRIORITY_MANDATORY. A shift ID may appear in at most one scheduling request for this employee. The default priority level for each of these requests is PRIORITY_LOW. See the Priority enum for more details.

hourly_contract

HourlyContract

Contract that specifies regular and overtime hourly rates for the employee.

EmployeeDemand

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

Fields
start_date_time

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.

end_date_time

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.

employee_count

int32

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

EmployeeSchedule

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

Fields
shift_template_id

string

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

shifts[]

ShiftWithEvents

List of shifts to which employee_count 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.

employee_count

int32

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.

Fields
start_date_time

DateTime

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

end_date_time

DateTime

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

events[]

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.

Fields
event_template_id

string

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

start_date_time

DateTime

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

end_date_time

DateTime

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

EventTemplate

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

Fields
id

string

Unique ID of this template.

minimum_minutes_after_shift_start

int32

Minimum number of minutes after the beginning of a shift that this event can start.

maximum_minutes_after_shift_start

int32

Maximum number of minutes after the beginning of a shift that this event can start.

duration_minutes

int32

Fixed duration in minutes of this event.

start_time_increment_minutes

int32

The time increment (in minutes) used to generate the set of possible event start times between minimum_minutes_after_shift_start and maximum_minutes_after_shift_start. 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.

HourlyContract

Specifies a base hourly rate, rate differentials, and overtime multipliers to determine the compensation for an employee. Note regulations in different places might require a different computation of overtime compensation. The solver approximates the overtime compensation to either minimize a proxy of the total cost or meet a budget (see BudgetRequirement). It is not intended as a tool to compute payroll.

Fields
base_hourly_rate

double

The compensation for working a non-overtime hour. If multiple rates apply to the employee, rate differentials are applied relative to this base hourly rate. Additionally, if there are multiple rates, the base hourly rate should be the minimum of these rates.

hourly_rate_shift_differentials

map<string, double>

The hourly rate differential, paid on top of the base_hourly_rate. For example, if the base hourly rate is $30/hr, "shift_1" is paid at a rate of $40/hr and, "shift_2" is paid at a rate of $45/hr, then the proto representation is: base_hourly_rate: 30 hourly_rate_shift_differentials {key: "shift_1" value: 10} hourly_rate_shift_differentials {key: "shift_2" value: 15}.

overtime_periods[]

OvertimePeriod

A list of all periods for which overtime has to be computed. These periods must not overlap.

OvertimePeriod

A fixed and regularly recurring period (typically 168 hours or seven consecutive 24-hour periods) that is used to determine the amount of overtime compensation. Each period has an overtime multiplier (e.g., 1.5) relative to the base_hourly_rate and a limit on the number of hours that are considered regular (non-overtime) work. Any shift that overlaps with the start_date_time (inclusive) and end_date_time (exclusive) time window is counted towards the total number hours worked in the period. If the overlap is partial, only the overlapping hours are counted.

Fields
overtime_multiplier

double

Multiplier to compute the overtime hourly rate (must be greater or equal to 1.0). The overtime hourly rate will typically be computed as base_hourly_rate * overtime_multiplier. If there are multiple rates given through hourly_rate_shift_differentials, the solver approximates the overtime hourly rate with a simple average of the rates that are applicable during the overtime period. Note: regulations in different places might require a different computation of overtime compensation. The solver approximates the overtime compensation to either minimize a proxy of the total cost or meet a budget, but it is not intended as a tool to compute payroll.

start_date_time

DateTime

Start time for the overtime period. If a shift overlaps this time, the hours of such a shift are counted from start_date_time.

end_date_time

DateTime

End time for the overtime period. If a shift overlaps this time, the hours of such a shift are counted up to end_date_time.

maximum_regular_hours

double

Maximum number of working hours that are paid at a regular (non-overtime) rate. This quantity must be positive.

Priority

The priority level for any constraint on an employee's schedule or the coverage requirements. These include SchedulingConstraint, ResourceConstraint, ShiftRequest, and CoverageRequirement. Because there could be conflicting constraints, it is not always possible to satisfy every constraint. As such, each type of constraint has a priority (given by the user or a default) that informs the solver about the relative importance of all the constraints given to a complete schedule.

Enums
PRIORITY_UNSPECIFIED Unknown priority level.
PRIORITY_LOW The lowest priority level. Constraints with this priority are less important that the other constraints. They are the first to be considered for violation if a feasible solution cannot be found.
PRIORITY_MEDIUM Priority level medium. Constraints with this priority are more important than constraints with PRIORITY_LOW priority but less important than constraints with PRIORITY_HIGH priority. If a feasible solution cannot be found after relaxing all constraints with PRIORITY_LOW priority, then constraints of PRIORITY_MEDIUM priority are considered next for violation.
PRIORITY_HIGH The highest priority level. Constraints with this priority level are the most important. They are the last to be considered for violation if a feasible solution cannot be found after relaxing constraints of the lower priority levels.
PRIORITY_MANDATORY Priority level that represents something that cannot be violated by the solver. If the solver is returning SolutionStatus.INFEASIBLE, it may be due to too many PRIORITY_MANDATORY constraints.

ResourceConstraint

A general constraint that limits the amount of a certain "resource" used by an employee. This is an abstract version of the more specific SchedulingConstraint that is more flexible for the user. Many scheduling constraints that cannot be specified in the SchedulingConstraint.type can be specified using this message instead.

Fields
priority

Priority

Priority level of this resource constraint. The default priority for all resource constraints is PRIORITY_MEDIUM.

resource_usages

map<string, double>

Amount of resource used by shifts. For example, if this constraint applies to the minimum and maximum hours worked by an employee in a specific week, then this map will contain the shifts that occur in that week and the length of each shift in hours.

minimum_resource_usage

double

Minimum resource usage for a resource constraint to be satisfied.

maximum_resource_usage

double

Maximum resource usage for a resource constraint to be satisfied.

SchedulingConstraint

Specific scheduling constraint for a particular employee. The constraint specified is only applied during the given interval [start_date_time, end_date_time).

Fields
priority

Priority

Priority level for this scheduling constraint. The default priority for all scheduling constraints is PRIORITY_MEDIUM.

start_date_time

DateTime

The start time for when this scheduling constraint applies (inclusive).

end_date_time

DateTime

The end time for when this scheduling constraint applies (exclusive).

Union field type. The type of constraint being specified. Each constraint is only applied within the time window specified above. type can be only one of the following:
minimum_minutes

int32

Minimum number of minutes the employee can work. If the employee is assigned to a shift that overlaps (fully or partially) the time window, the number of minutes that the shift overlaps the time window is included in this count.

maximum_minutes

int32

Maximum number of minutes the employee can work in the time window. If the employee is assigned to a shift that overlaps (fully or partially) the time window, the number of minutes that the shift overlaps the time window is included in this count.

minimum_consecutive_work_days

int32

Minimum number of consecutive days the employee can work. An employee works on a specific day if they are assigned to a shift that starts during that day. Any shift that the employee is assigned to that begins in the time window is included in this count.

maximum_consecutive_work_days

int32

Maximum number of consecutive days the employee can work. An employee works on a specific day if they are assigned to a shift that starts during that day. Any shift that the employee is assigned to that begins in the time window is included in this count.

minimum_shift_count

int32

Minimum number of shifts the employee can work. Any shift that the employee is assigned to that fully overlaps with the time window is included in this count.

maximum_shift_count

int32

Maximum number of shifts the employee can work. Any shift that the employee is assigned to that fully overlaps with the time window is included in this count.

minimum_rest_minutes

int32

Minimum number of minutes the employee must rest after the end of one shift before being assigned to another shift. This constraint applies to every pair of shifts that are fully included in [start_date_time, end_date_time].

Shift

A shift specifies a fixed time window in which employees can work.

Fields
id

string

Unique ID assigned to this shift.

location_id

string

Location ID in which this shift is worked. This can be empty.

start_date_time

DateTime

The start time of the shift (inclusive).

end_date_time

DateTime

The end time of the shift (exclusive). Currently, the solver only allows for shifts that are less than 24hrs in length.

break_rules[]

BreakRule

A list of break rules that occur during the shift. Employees doing this shift are assigned a break per break_rule, during which they do not cover the demand for the role they are fulfilling. Each BreakRule time window must be fully included within this shift's time window.

ShiftAssignment

An employee to shift-role assignment.

Fields
employee_id

string

The employee ID being assigned.

shift_id

string

Shift ID assigned to the employee.

role_id

string

Role ID the employee is assigned to for the shift.

breaks[]

Break

List of breaks for this shift assignment.

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.

ShiftPreference

A numeric preference for a particular shift ID.

Fields
shift_id

string

Shift ID for which the preference is specified.

preference

int32

Larger values of preference denote a more desirable shift.

ShiftRequest

An employee's request to be assigned or not be assigned to specific shifts.

Fields
priority

Priority

Priority level of this scheduling request. The default priority for all scheduling requests is PRIORITY_LOW.

shift_ids[]

string

The shift IDs of the scheduling request.

type

WorkStatus

Request type, e.g., whether the request is be assigned or not be assigned to the set of shifts.

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.

Fields
id

string

Unique ID of this template.

earliest_start_time

TimeOfDay

Earliest time in the day that a shift can start. This value is specified with hours and minutes; seconds and nanos are ignored.

latest_start_time

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 earliest_start_time, then a shift generated by this template may start before or after midnight.

duration_minutes

int32

Fixed duration of a shift generated by this template.

start_time_increment_minutes

int32

The time increment (in minutes) used to generate the set of possible start times between earliest_start_time and latest_start_time. 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.

days_off_count_per_week

int32

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.

event_templates[]

EventTemplate

Rules for generating events for each shift. Exactly one event will be included in each shift for each Event specified.

minimum_interevent_gap_minutes

int32

Minimum minutes between the end of one event and the start of the next.

maximum_employee_count

int32

Maximum number of employees that can be assigned to all shifts generated by this template.

SolutionStatus

Solution (i.e., a schedule) status provided in the response of a solver.

Enums
SOLUTION_STATUS_UNSPECIFIED Unspecified status for the response.
FEASIBLE The returned schedule is feasible, but might not be optimal.
OPTIMAL The returned schedule is optimal.
INFEASIBLE No feasible schedule exists for the given constraints. The solver may return this value if any subset of the constraints with priority level PRIORITY_MANDATORY cannot be satisfied.
NOT_SOLVED No schedule was found.
NOT_SOLVED_DEADLINE_EXCEEDED No schedule was found within the time limit given.

SolveParameters

Parameters that control a single solve of the shift scheduling problem.

Fields
time_limit

Duration

Maximum time the solver should spend on the problem. If not set, defaults to 1 minute.

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.

SolverConfig

Specifies additional parameters for solving the Shift Generation problem.

Fields
time_limit

Duration

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.

multi_day_schedule

bool

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.

shift_events_can_change

bool

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 multi_day_schedule is false. Setting this parameter to true may result in longer solve times. Default is false.

WorkStatus

Whether an employee is working or not.

Enums
WORK_STATUS_UNSPECIFIED Unknown work status.
STATUS_WORK Status representing a working employee.
STATUS_NOT_WORK Status representing a non-working employee.