Package google.research.optimization.v1.workforce

Index

• Break (message)
• BreakRule (message)
• BudgetRequirement (message)
• CoverageRequirement (message)
• CoverageRequirement.RoleRequirement (message)
• CoverageRequirement.SkillRequirement (message)
• DemandCoverageViolation (message)
• Employee (message)
• EmployeeDemand (message)
• EmployeeSchedule (message)
• EmployeeSchedule.ShiftWithEvents (message)
• EmployeeSchedule.ShiftWithEvents.Event (message)
• EventTemplate (message)
• HourlyContract (message)
• HourlyContract.OvertimePeriod (message)
• Priority (enum)
• ResourceConstraint (message)
• SchedulingConstraint (message)
• Shift (message)
• ShiftAssignment (message)
• ShiftGenerationSolutionStatus (enum)
• ShiftPreference (message)
• ShiftRequest (message)
• ShiftTemplate (message)
• SolutionStatus (enum)
• SolveParameters (message)
• SolverConfig (message)
• WorkStatus (enum)

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.