> ## Documentation Index > Fetch the complete documentation index at: https://docs.automaticrostering.visma.net/llms.txt > Use this file to discover all available pages before exploring further. # Start a job ## OpenAPI ````yaml /openapi.yaml post /roster/start openapi: 3.1.0 info: title: Automatic Rostering API version: 2.0.0 description: >- Automatic Rostering acts as the modern intelligence layer for your workforce management product. license: name: Proprietary servers: - url: https://api-stage.automaticrostering.visma.net description: Stage environment - url: https://api.automaticrostering.visma.net description: Production environment security: - vismaConnectBearer: [] tags: - name: Roster description: Submit, monitor, stop, and fetch roster jobs. - name: Reason description: Configure integrator context used by Reasoning Engine capabilities. paths: /roster/start: post: tags: - Roster summary: Start a job operationId: startRoster requestBody: description: The data required to initialize a new roster job. required: true content: application/json: schema: $ref: '#/components/schemas/RosterStartRequest' responses: '202': $ref: '#/components/responses/JobId' '400': $ref: '#/components/responses/BadRequest' '500': $ref: '#/components/responses/InternalServerError' components: schemas: RosterStartRequest: type: object additionalProperties: false required: - context - demands - employees properties: context: description: High-level information about the job that is being started. type: object additionalProperties: false required: - planId - identity - horizon - demandType properties: planId: type: string description: >- Identifier of the plan this roster job belongs to. Used to provide context about retries on the same plan. identity: description: Information about the user that started the job. type: object additionalProperties: false required: - tenantId - userId properties: tenantId: type: string description: >- Identifier of the tenant the user belongs to (for example, an organization or company). userId: type: string description: Identifier of the person that started the job. horizon: description: The time horizon for which the schedule should be created. type: object additionalProperties: false required: - startDate - endDate - scheduleType properties: startDate: $ref: '#/components/schemas/Date' description: The first date of the schedule (YYYY-MM-DD). type: string endDate: $ref: '#/components/schemas/Date' description: The last date of the schedule (YYYY-MM-DD). type: string scheduleType: type: string description: Schedule type of the roster to be created. enum: - CALENDAR - RECURRING demandType: type: string description: Demand type of the roster to be created. enum: - TIME_DEMAND - SHIFT_DEMAND employees: type: array description: List of employees to be used in this roster. items: $ref: '#/components/schemas/Employee' demands: type: array description: List of demands used in this roster. items: $ref: '#/components/schemas/Demand' shifts: type: array description: List of shifts that employees can be assigned to. items: $ref: '#/components/schemas/Shift' timeSlots: type: array description: >- List of time slots for which demand can be specified (only if using TIME_DEMAND) items: $ref: '#/components/schemas/TimeSlot' rules: $ref: '#/components/schemas/Rules' extensions: $ref: '#/components/schemas/Extensions' statusOptions: $ref: '#/components/schemas/Status' description: >- Optional configuration for live status updates during the run, including metrics to track and return from the status endpoint. Date: type: string format: date description: >- Date specified in ISO8601 format (YYYY-MM-DD). Only available in CALENDAR schedules. Employee: type: object additionalProperties: false required: - id properties: id: $ref: '#/components/schemas/EmployeeId' labels: type: array description: >- List of labels assigned to this employee. Labels can be used in rules to group employees. items: type: string uniqueItems: true attributes: description: >- List of attributes that this employee has. Shifts, demands and tasks can have requirements on the attributes that an employee has. type: array items: $ref: '#/components/schemas/Attribute' roles: description: >- Optional list of roles that this employee can work. Each role can have additional attributes that the employee has when working that role. type: array items: type: object additionalProperties: false properties: id: type: string description: Unique identifier for this role. attributes: type: array description: >- List of additional attributes this employee has when they work in this role. items: $ref: '#/components/schemas/Attribute' preassignedShifts: type: array description: List of assignments that are pre-assigned to this employee. items: $ref: '#/components/schemas/PreassignedShift' isReadOnly: type: boolean description: >- If set to true, the employee will only work their preassigned shifts. These will not be altered, and we will not assign new shifts to this employee. default: false Demand: type: object additionalProperties: false properties: days: $ref: '#/components/schemas/Days' shiftDemands: description: >- List of shift demands that exist on the days specified in the days field. type: array items: $ref: '#/components/schemas/ShiftDemand' timeDemands: description: >- List of time demands that exist on the days specified in the days field. type: array items: $ref: '#/components/schemas/TimeDemand' Shift: type: object additionalProperties: false required: - id - intervals properties: id: $ref: '#/components/schemas/ShiftId' description: Unique identifier for the shift. labels: type: array description: >- List of labels assigned to this shift. Labels can be used in rules to group shifts. items: type: string uniqueItems: true isReadOnly: type: boolean description: >- If set to true, the shift will not be assigned by us. Read only shifts will not be used in new assignments by us, their use is limited to preassigned shifts. Read only shifts can still be used to cover demand. default: false canCoverDemand: type: boolean description: >- Only relevant for preassigned shifts. If set to false, assignments of this shift will not contribute towards demand coverage. Shifts that cannot cover demand will not be used in new assignments by us, their use is limited to preassigned shifts. default: true availableDays: $ref: '#/components/schemas/Days' description: >- Days on which this shift is available to be assigned. If not set, the shift is always available. intervals: type: array description: >- List of intervals that this shift consists of. The maximum duration of a shift is 72 hours. minItems: 1 items: $ref: '#/components/schemas/ShiftInterval' attributeRequirements: description: >- List of requirements on the attributes that an employee needs to be eligible to work this Shift. If an employee does not meet all of the requirements, the employee can not work this Shift. type: array items: $ref: '#/components/schemas/AttributeRequirement' TimeSlot: type: object additionalProperties: false required: - id - startTime - endTime properties: id: $ref: '#/components/schemas/TimeSlotId' startTime: $ref: '#/components/schemas/TimeStamp' description: Start time of this time slot. endTime: $ref: '#/components/schemas/TimeStamp' description: End time of this time slot. canBeShared: type: boolean description: >- Determines if the time slot can be "split" and covered by more than one employee. If set to false, the same employee has to cover the entire time slot from start to end. default: true workloadCategory: type: string description: >- If set, demands with this time slot can only be covered by shifts that have the same workload category. taskId: type: string description: >- Task id of the task to do during this time slot. The task needs to be defined in the configuration part of the payload. If an employee does not meet the requirements for the task, they can not cover this time slot. attributeRequirements: description: >- List of requirements on the attributes that an employee needs to be eligible to cover this time slot. If an employee does not meet all of the requirements, the employee can not cover this time slot. type: array items: $ref: '#/components/schemas/AttributeRequirement' Rules: type: object additionalProperties: false description: >- Rules that should be active. Used to specify all sorts of preferences and restrictions. properties: availabilityRules: description: >- Rules that specify when and for which shifts employees should be considered (un)available. type: array items: $ref: '#/components/schemas/AvailabilityRule' utilizationRules: description: >- Rules that specify targets and limits for how much employees should work (per period). type: array items: $ref: '#/components/schemas/UtilizationRule' cooldownRules: description: >- Rules that specify the minimum time between two kinds of work for employees. type: array items: $ref: '#/components/schemas/CooldownRule' consecutiveRules: description: >- Rules that limit the number of consecutive entities an employee can work. type: array items: $ref: '#/components/schemas/ConsecutiveRule' patternRules: description: >- Rules that specify patterns of shifts that are (un)desirable for employees to follow. type: array items: $ref: '#/components/schemas/PatternRule' periodicRestRules: description: >- Rules that specify targets for the amount of (continuous) rest employees get per period. type: array items: $ref: '#/components/schemas/PeriodicRestRule' periodDistributionRules: description: >- Rules that improve the distribution of work during undesired periods over employees. type: array items: $ref: '#/components/schemas/PeriodDistributionRule' layoutRules: description: >- Rules that improve the layout of shifts across the roster for employees. type: array items: $ref: '#/components/schemas/LayoutRule' rotationRules: description: >- Rules that specify targets for rotating employees through a series of periods. type: array items: $ref: '#/components/schemas/RotationRule' fairnessRules: description: >- Rules that improve distribution of (in)conveniences from other rules over employees. type: array items: $ref: '#/components/schemas/FairnessRule' Extensions: description: Extensions that can be helpful in more advanced rostering scenarios. type: object additionalProperties: false properties: labeling: $ref: '#/components/schemas/Labeling' timeAccounting: description: Settings related to how worked hours are to be counted. type: object additionalProperties: false properties: horizon: $ref: '#/components/schemas/TimeAccountingHorizon' bonusTimeSettings: $ref: '#/components/schemas/BonusTimeSettings' defaultTimeSettings: $ref: '#/components/schemas/DefaultTimeSettings' tasks: type: array description: List of tasks used in this roster. items: $ref: '#/components/schemas/Task' Status: type: object additionalProperties: false properties: metricScopes: $ref: '#/components/schemas/MetricScopes' description: >- Metrics to calculate during the roster run for numeric status responses and generated status messages. Omit this property to avoid tracking status metrics. messages: $ref: '#/components/schemas/Messages' description: >- Generated message updates to create during the roster run. Omit this property or set `isEnabled` to false to avoid generating messages. Error: type: object additionalProperties: false required: - code - message properties: code: type: string message: type: string EmployeeId: type: string description: Unique identifier for this employee. Attribute: type: object additionalProperties: false required: - values properties: category: type: string description: The category of the attribute. values: type: array items: type: string description: >- The values that the employee has for this attribute. For example, an employee could have the values "marketing" and "finance" for an attribute with the category "department". periods: $ref: '#/components/schemas/Periods' description: >- Validity periods for the attribute. The employee is only considered to have the attribute during these periods. PreassignedShift: type: object additionalProperties: false required: - shiftId - days properties: shiftId: $ref: '#/components/schemas/ShiftId' description: The id of the shift that is assigned to the employee. days: $ref: '#/components/schemas/Days' isLocked: type: boolean description: >- Whether the shift is locked. Locked shifts cannot be changed by us. For read-only employees, all shifts are automatically considered locked. default: false roleId: type: string description: >- The role id of the role that the employee has when working this shift. Needs to match a role id from the employee's list of roles. Days: description: List of days in the schedule. type: object additionalProperties: false minProperties: 1 maxProperties: 1 properties: dates: description: List of dates in the schedule. Only allowed in CALENDAR payloads. type: array uniqueItems: true items: $ref: '#/components/schemas/Date' dayIndices: description: >- List of day indices in the schedule. Only allowed in RECURRING payloads. type: array uniqueItems: true items: $ref: '#/components/schemas/DayIndex' daysOfWeek: description: >- List of days of the week. Will apply to all days in the schedule that match any of the specified weekdays. type: array uniqueItems: true items: $ref: '#/components/schemas/DayOfWeek' ShiftDemand: type: object additionalProperties: false required: - shiftId - ideal properties: shiftId: $ref: '#/components/schemas/ShiftId' description: Id of the shift for which there is demand. min: type: integer description: >- 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. ideal: type: integer description: >- Ideal number of employees needed to cover the demand. We prefer to cover the demand with exactly this number of employees. max: type: integer description: >- 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. attributeRequirementGroups: type: array description: >- List of requirements on the attributes that an employee must meet to be eligible to cover this shift demand. items: $ref: '#/components/schemas/AttributeRequirementGroup' priority: $ref: '#/components/schemas/DemandPriority' TimeDemand: type: object additionalProperties: false required: - timeSlotId - ideal properties: timeSlotId: $ref: '#/components/schemas/TimeSlotId' description: Id of the time slot for which there is demand. min: type: integer description: >- 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. ideal: type: integer description: >- Ideal number of employees needed to cover the demand. We prefer to cover the demand with exactly this number of employees. max: type: integer description: >- 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. priority: $ref: '#/components/schemas/DemandPriority' ShiftId: type: string description: Unique identifier for the shift. ShiftInterval: type: object additionalProperties: false description: >- Interval of a shift. When an employee is assigned to a shift, the employee will work all of its intervals. required: - startTime - endTime - dayIndicator properties: startTime: $ref: '#/components/schemas/TimeStamp' endTime: $ref: '#/components/schemas/TimeStamp' dayIndicator: $ref: '#/components/schemas/DayIndicator' description: >- Indicates which day this interval belongs to, relative to the day that the shift belongs to. -1 indicates the interval starts on the previous day, 0 on the same day, and 1 on the next day. workload: type: object additionalProperties: false properties: factor: type: number description: >- Factor by which the hours of this interval will be multiplied to calculate the total FTE hours of an employee. default: 1 minimum: 0 category: type: string description: >- Category of work carried out during the interval. Only relevant if using TIME_DEMAND. breakMinutes: type: integer description: >- Minutes of break in this interval. We do not plan the break at any specific time, but the break minutes are subtracted from the total FTE for the shift. default: 0 taskId: type: string description: >- Task id of the task that must be worked on during this interval. The task needs to be defined in the configuration part of the payload. AttributeRequirement: type: object additionalProperties: false properties: category: type: string description: The category of the attribute. values: type: array items: type: string description: The targeted values for this requirement. uniqueItems: true matchType: $ref: '#/components/schemas/AttributeMatchType' TimeSlotId: type: string description: Unique identifier for this time slot. TimeStamp: type: string description: >- TIME ISO 8601 format hh:mm. Equivalent to the 24h format of a single day. Use 00:00 to represent midnight. format: time AvailabilityRule: type: object additionalProperties: false description: >- Used to indicate when employees are strictly or preferably available or unavailable to work. required: - id - importance - isDesired properties: id: $ref: '#/components/schemas/RuleId' labels: $ref: '#/components/schemas/RuleLabels' importance: $ref: '#/components/schemas/Importance' isDesired: type: boolean description: >- If set to true, it will be considered preferable for employees to work the shifts that this rule applies to during the specified periods. If set to false, we will try to avoid assigning applicable shifts to employees during the specified periods. If importance is set to strict, this must be false. filters: $ref: '#/components/schemas/AvailabilityFilters' options: $ref: '#/components/schemas/AvailabilityOptions' periods: $ref: '#/components/schemas/Periods' UtilizationRule: description: >- Used to set targets and limits for the amount of hours or shifts worked by employees within given periods. type: object additionalProperties: false required: - id - importance - targets properties: id: $ref: '#/components/schemas/RuleId' labels: $ref: '#/components/schemas/RuleLabels' importance: $ref: '#/components/schemas/Importance' filters: $ref: '#/components/schemas/UtilizationFilters' targets: description: >- Specifies the target utilization for the rule. Targets can be specified in number of FTE hours, or in number of shifts worked during the period. type: object additionalProperties: false properties: minHours: type: number description: >- The minimum number of hours that should be worked by employees on shifts that match the rule in each period. This is treated as a target - it is not guaranteed that the number of hours worked will be greater than this value. idealHours: type: number description: >- The ideal number of hours that should be worked by employees on shifts that match the rule in each period. This is treated as a target - it is not guaranteed that the number of hours worked will be exactly this value. maxHours: type: number description: >- The maximum number of hours that should be worked by employees on shifts that match the rule in each period. This is treated as a hard limit - the number of hours worked will never exceed this value. minShifts: type: integer description: >- The minimum number of shifts that match the rule that an employee should work in each period. This is treated as a target - it is not guaranteed that the number of shifts worked will be greater than this value. idealShifts: type: integer description: >- The ideal number of shifts that match the rule that an employee should work in each period. This is treated as a target - it is not guaranteed that the number of shifts worked will be exactly this value. maxShifts: type: integer description: >- The maximum number of shifts that match the rule that an employee should work in each period. This is treated as a hard limit - the number of shifts worked will never exceed this value. options: $ref: '#/components/schemas/UtilizationOptions' periods: $ref: '#/components/schemas/Periods' description: >- The periods in which the rule should be applied. The minHours and maxHours will be applied to each period separately. CooldownRule: description: Used to define required or desired rest between working shifts. type: object additionalProperties: false required: - id - importance - targets properties: id: $ref: '#/components/schemas/RuleId' labels: $ref: '#/components/schemas/RuleLabels' importance: $ref: '#/components/schemas/Importance' filters: $ref: '#/components/schemas/CooldownFilters' targets: $ref: '#/components/schemas/CooldownTargets' description: >- Defines the desired minimum duration of the cooldown. Can be defined in either hours or days. periods: $ref: '#/components/schemas/Periods' description: >- Defines the periods in which the cooldown rule should be applied. If specified, cooldowns can only be triggered by work that occurs within the specified periods. The cooldown itself will remain active until the target duration has passed, regardless of whether it coincides with the specified periods. starts: $ref: '#/components/schemas/CooldownStartsOrEnds' description: >- Defines the types of work that will trigger a cooldown. Currently, only filters on shifts are supported as starts. ends: $ref: '#/components/schemas/CooldownStartsOrEnds' description: >- Defines the types of work that should be avoided during a cooldown. Currently, only filters on shifts are supported as ends. ConsecutiveRule: type: object additionalProperties: false description: >- Used to set targets and limits on the number of consecutive shifts that an employee works. required: - id - importance - targets properties: id: $ref: '#/components/schemas/RuleId' labels: $ref: '#/components/schemas/RuleLabels' importance: $ref: '#/components/schemas/Importance' filters: $ref: '#/components/schemas/RuleFilters' targets: $ref: '#/components/schemas/ConsecutiveTargets' PatternRule: description: Used to define patterns of shifts that employees should follow or avoid. type: object additionalProperties: false required: - id - importance - isDesired - patterns properties: id: $ref: '#/components/schemas/RuleId' labels: $ref: '#/components/schemas/RuleLabels' importance: $ref: '#/components/schemas/Importance' isDesired: description: >- If set to true, we will try to make employees follow the specified patterns. Else, we will try to avoid making employees follow any of the specified patterns. type: boolean filters: $ref: '#/components/schemas/PatternFilters' options: $ref: '#/components/schemas/PatternOptions' periods: $ref: '#/components/schemas/Periods' description: >- Defines the periods in which a pattern should be followed. Periods may not overlap, and are not applicable for undesired patterns. For desired patterns, we will try to make each employee follow exactly one of the available patterns in each period. Therefore, the patterns should be defined such that each instance of a pattern is always entirely within a single period. patterns: description: The patterns that should be followed or avoided. type: array items: type: object additionalProperties: false required: - patternDays properties: patternDays: type: array description: >- Defines the pattern that should be followed. Each element in the array represents a day in the pattern. Note that DAY_OFF is not allowed on strict undesired pattern rules. items: $ref: '#/components/schemas/PatternDay' startDays: $ref: '#/components/schemas/Days' description: >- Defines the days on which this pattern starts. Defaults to the first day of each period (if periods are specified), or to each day of the schedule (if periods are not specified). roles: $ref: '#/components/schemas/RuleFiltersRoles' description: >- Used to apply the rule only to patterns carried out in specific roles. isRepeating: type: boolean default: false description: >- If set to true, each instance of the pattern will be repeated from its start day until the end of the period that the instance falls within. Otherwise, the pattern is not repeated. startOffsets: type: integer default: 0 description: >- The offset that the pattern may start with on the start day. If set to 0, the pattern must start with the first pattern day on each start day. If set to 1, the pattern may start from any of its pattern days on the start day. If set to 7 (for example), the pattern may start with every 7th pattern day on the start day. The pattern is then continued as usual. PeriodicRestRule: description: Used to set targets for continuous rest within specific periods. type: object additionalProperties: false required: - id - importance - targets properties: id: $ref: '#/components/schemas/RuleId' labels: $ref: '#/components/schemas/RuleLabels' importance: $ref: '#/components/schemas/Importance' filters: $ref: '#/components/schemas/RuleFilters' targets: $ref: '#/components/schemas/PeriodicRestTargets' options: $ref: '#/components/schemas/PeriodicRestOptions' periods: $ref: '#/components/schemas/Periods' description: The periods in which the rule should be applied. PeriodDistributionRule: description: >- Used to define targets and limits for the distribution of periods (like weekends, holidays, nights). type: object additionalProperties: false required: - id - importance - targets properties: id: $ref: '#/components/schemas/RuleId' labels: $ref: '#/components/schemas/RuleLabels' importance: $ref: '#/components/schemas/Importance' filters: $ref: '#/components/schemas/RuleFilters' targets: $ref: '#/components/schemas/PeriodDistributionTargets' options: $ref: '#/components/schemas/PeriodDistributionOptions' periods: $ref: '#/components/schemas/Periods' LayoutRule: type: object additionalProperties: false required: - id - importance - objectives properties: id: $ref: '#/components/schemas/RuleId' labels: $ref: '#/components/schemas/RuleLabels' importance: $ref: '#/components/schemas/Importance' filters: $ref: '#/components/schemas/RuleFilters' objectives: $ref: '#/components/schemas/LayoutObjectives' description: >- Describes the targets for this rule. Targets can indicate whether small/large groups are preferred and whether groups should be placed close together or spread out. RotationRule: type: object additionalProperties: false required: - id - importance - targets - periods properties: id: $ref: '#/components/schemas/RuleId' labels: $ref: '#/components/schemas/RuleLabels' importance: $ref: '#/components/schemas/Importance' filters: $ref: '#/components/schemas/RotationFilters' targets: $ref: '#/components/schemas/RotationRuleTargets' periods: $ref: '#/components/schemas/Periods' description: The periods in which the rule should be applied. assignedRotations: type: array description: >- List of employees that have been assigned to specific rotations. We will try to ensure that these employees follow the specified rotations as much as possible. items: type: object additionalProperties: false required: - rotationIndex - employeeIds properties: rotationIndex: type: integer description: >- The index of the rotation that the employees are assigned to. Starts at 0. employeeIds: type: array description: List of employee ids that are assigned to the rotation. uniqueItems: true items: type: string assignedPeriods: type: array description: >- List of employees that have been assigned to specific periods already. We will try to ensure that these employees work during the specified periods as much as possible. items: type: object additionalProperties: false required: - employeeId - periodIndices properties: employeeId: type: string description: The id of the employee that is assigned to the period. periodIndices: type: array description: >- List of period indices that the employee is assigned to. Starts at 0. uniqueItems: true items: type: integer FairnessRule: type: object additionalProperties: false required: - id properties: id: $ref: '#/components/schemas/RuleId' labels: $ref: '#/components/schemas/RuleLabels' importance: $ref: '#/components/schemas/Importance' description: The importance of adhering to this fairness rule. filters: $ref: '#/components/schemas/FairnessFilters' applyRuleImportanceScaling: type: boolean description: >- If true, more importance is given to (in)conveniences for rules with a higher importance. default: true applyWorkloadScaling: type: boolean description: >- If true, the measured (in)conveniences are scaled proportionally to each employee's workload, ensuring fairness accounts for differences in hours worked. default: false ruleFactors: type: array description: >- Technical property. Contact dev team for information on how to use this. items: type: object additionalProperties: false properties: ruleId: type: string description: The id of the rule for which this factor should be applied. factor: type: number description: >- The factor to apply to the (in)conveniences of the specified rule when calculating fairness. minimum: 0 maximum: 2 Labeling: description: >- Define automatic assignment of labels to shifts and periods. These labels can be reused in rules. type: object additionalProperties: false properties: shifts: description: >- List of rules for automatically assigning labels to shifts based on their properties. type: array items: $ref: '#/components/schemas/ShiftLabelRule' periods: description: List of labeled periods that can be reused in rules. type: array items: $ref: '#/components/schemas/PeriodLabelRule' TimeAccountingHorizon: description: >- Defines the time period for which hours should be counted. Hours outside this period will not be counted. type: object additionalProperties: false properties: startDay: $ref: '#/components/schemas/Day' description: First day of the time accounting horizon. endDay: $ref: '#/components/schemas/Day' description: Last day of the time accounting horizon. includeFullShifts: type: boolean description: >- Whether to include hours outside the time accounting horizon if they are part of a shift that overlaps with it. BonusTimeSettings: description: >- List of rules for assigning bonus minutes to employees based on the times of the shifts they work. type: array items: type: object additionalProperties: false properties: bonusMinutesPerHour: type: integer description: >- The number of bonus minutes that an employee will receive for each hour worked during the specified periods. periods: $ref: '#/components/schemas/Periods' description: The periods in which the bonus minutes will be applied. DefaultTimeSettings: type: array items: type: object additionalProperties: false properties: defaultHoursPerDay: type: number employeeIds: type: array uniqueItems: true items: type: string periods: $ref: '#/components/schemas/Periods' Task: type: object additionalProperties: false minProperties: 1 properties: id: type: string description: Unique identifier. labels: type: array description: >- If id is specified, labels only indicate to which task groups this task belongs. Otherwise, the properties below define the defaults on the task groups corresponding to the labels. Each label can occur on at most one task entry without an id. items: type: string uniqueItems: true attributeRequirements: type: array description: >- List of requirements on the attributes that an employee needs to be eligible to carry out this task (group). If an employee does not meet all of the requirements, the employee can not carry out this task (group). items: $ref: '#/components/schemas/AttributeRequirement' minMinutes: type: integer minimum: 0 maximum: 10080 description: >- Minimum time in minutes an employee needs to work on this task (group) consecutively. maxMinutes: type: integer minimum: 5 maximum: 10080 description: >- Maximum time in minutes an employee is allowed to work on this task (group) consecutively. Afterwards, a cooldown is required. cooldownToSelf: type: integer minimum: 0 description: >- Time in minutes an employee needs to rest before working on the same task (group) again. cooldownToOthers: type: array description: >- Define different cooldowns that become active after working on this task (group). These prevent an employee from working on a task (group) for a certain amount of time. items: $ref: '#/components/schemas/TaskCooldownToOthers' MetricScopes: type: array description: The metric selections to track during a roster run. maxItems: 20 uniqueItems: true items: $ref: '#/components/schemas/MetricScope' Messages: type: object additionalProperties: false required: - isEnabled properties: isEnabled: type: boolean description: >- Whether generated message updates should be created during the roster run. language: $ref: '#/components/schemas/OutputLanguage' description: >- Language used for every generated message in this roster job. Defaults to English when omitted. default: en Periods: type: object additionalProperties: false minProperties: 1 maxProperties: 1 description: >- List of periods in the schedule. Periods can be defined explicitly or through a recurrent definition (for example, to generate weeks). properties: days: $ref: '#/components/schemas/DaysWithTime' customDefinitions: type: array description: >- List of custom period definitions. Each custom period definition defines one period in the schedule. items: $ref: '#/components/schemas/CustomPeriodDefinition' recurrentDefinition: $ref: '#/components/schemas/RecurrentPeriodDefinition' labels: type: array uniqueItems: true description: >- Provide labels to re-use periods that were defined in the configuration. items: type: string DayIndex: type: integer description: >- Day index relative to the horizon start day (starts at 0). Only available in RECURRING schedules. minimum: 0 DayOfWeek: type: string enum: - MON - TUE - WED - THU - FRI - SAT - SUN AttributeRequirementGroup: type: object additionalProperties: false properties: attributeRequirements: type: array items: $ref: '#/components/schemas/AttributeRequirement' min: type: integer description: Minimum number of required employees that match the requirement. minimum: 1 DemandPriority: type: number default: 1 minimum: 1 maximum: 2 description: >- Priority of this demand. Increasing a demand's priority will make it prioritized compared to other demands, but also compared to rules. DayIndicator: type: integer minimum: -1 maximum: 1 AttributeMatchType: type: string enum: - NONE - ANY - ALL default: ALL RuleId: type: string description: Unique identifier for the rule. RuleLabels: type: array description: >- Labels for the rule. Labels can be used to group rules together. For example, if multiple rules are related to the same shift type, they can all be labeled with the same label. uniqueItems: true items: type: string Importance: type: string enum: - NONE - VERY_LOW - LOW - MEDIUM - HIGH - VERY_HIGH - STRICT description: >- The importance of the rule. The higher the importance, the more it will be taking the rule into account. Under strict importance, the rule may never be violated. AvailabilityFilters: type: object additionalProperties: false description: >- Filters to determine the scope of the rule. Used to decide which employees and which shifts the rule should be applied to. Filters use logical OR filtering - an employee or shift is included as long as it is targeted by any of the filters. properties: employees: $ref: '#/components/schemas/RuleFiltersEmployees' shifts: $ref: '#/components/schemas/RuleFiltersShifts' work: $ref: '#/components/schemas/RuleFiltersWork' AvailabilityOptions: description: Additional options for how the rule should be applied. type: object additionalProperties: false properties: periodHandling: type: string enum: - PARTIAL - COMPLETE default: PARTIAL description: >- Used to indicate whether partial fulfillment per period is acceptable (PARTIAL) or not (COMPLETE). This setting can only be used for undesired rules. UtilizationFilters: type: object additionalProperties: false description: >- Filters to determine the scope of the rule. Used to decide which employees and which shifts the rule should be applied to. Filters use logical OR filtering - an employee or shift is included as long as it is targeted by any of the filters. properties: employees: $ref: '#/components/schemas/RuleFiltersEmployees' shifts: $ref: '#/components/schemas/RuleFiltersShifts' work: $ref: '#/components/schemas/RuleFiltersWork' UtilizationOptions: description: Additional options for how the rule should be applied. type: object additionalProperties: false properties: bonusTime: description: Settings to determine if and how bonus time rules affect the rule. type: object additionalProperties: false properties: includeBonusHours: type: boolean description: >- Whether or not bonus hours should be included in the calculation of an employee's total hours worked for the rule. default: true averageHoursThreshold: type: number description: >- If a threshold is provided, bonus hours will only be included in the calculation of an employee's total hours worked if the average bonus hours per period exceed this threshold. minimum: 0 averageHoursCap: type: number description: >- If a cap is provided, the average number of bonus hours per period will be capped at this value. The employee can be eligible for more bonus hours, but they will not be counted beyond this cap. minimum: 0 overlapSettings: $ref: '#/components/schemas/OverlapSettings' description: >- Specify when a scheduled shift should count towards the targets of this rule. If both minOverlapHours and minOverlapPercentage are specified, shifts will be counted if they satisfy either requirement. If the overlapSettings object is not defined, shifts are counted if they have any overlap with the rule. CooldownFilters: type: object additionalProperties: false description: >- Filters to determine the scope of the rule. Used to decide which employees and which work the rule should be applied to. properties: employees: $ref: '#/components/schemas/RuleFiltersEmployees' work: $ref: '#/components/schemas/RuleFiltersWork' CooldownTargets: type: object additionalProperties: false minProperties: 1 maxProperties: 1 properties: minHours: description: Minimum number of hours that the cooldown should last. type: number minimum: 1 minDays: description: Minimum number of days that the cooldown should last. type: integer minimum: 1 CooldownStartsOrEnds: type: object additionalProperties: false properties: shifts: $ref: '#/components/schemas/RuleFiltersShifts' RuleFilters: type: object additionalProperties: false description: >- Filters to determine the scope of the rule. Used to indicate what the rule should be applied to (which employees, which shifts, etc). Leaving this empty means that the rule always applies. properties: employees: $ref: '#/components/schemas/RuleFiltersEmployees' shifts: $ref: '#/components/schemas/RuleFiltersShifts' ConsecutiveTargets: description: >- Defines targets and limits on the number of consecutive shifts that an employee works. type: object additionalProperties: false properties: min: type: integer description: >- The minimum number of consecutive entities that an employee should ideally work. This cannot be set as a strict limit and will be treated as a target instead. minimum: 0 max: type: integer description: >- The maximum number of consecutive entities that an employee can work. Currently only supports importance STRICT. minimum: 0 PatternFilters: type: object additionalProperties: false description: >- Filters to determine the scope of the rule. Used to decide which employees the rule should be applied to. properties: employees: $ref: '#/components/schemas/RuleFiltersEmployees' PatternOptions: description: Additional options for how the rule should be applied. type: object additionalProperties: false properties: emptyDayBehaviours: description: >- Describes whether the pattern should skip over days that could be considered irrelevant for the pattern. type: object additionalProperties: false properties: dayOutsideSchedule: $ref: '#/components/schemas/EmptyDayBehaviour' description: >- Describes whether the pattern counts days outside the schedule period as days in the pattern. The pattern can either always include them (INCLUDE), skip over them (EXCLUDE) or only include them if the pattern allows for a day off on that day (MATCH). Takes priority over the dayWithoutDemand and dayOff properties. dayWithoutDemand: $ref: '#/components/schemas/EmptyDayBehaviour' description: >- Describes whether the pattern counts days without demand as days in the pattern. The pattern can either always include them (INCLUDE), skip over them (EXCLUDE) or only include them if the pattern allows for a day off on that day (MATCH). dayOff: $ref: '#/components/schemas/EmptyDayBehaviour' description: >- Describes whether the pattern counts days off as days in the pattern. The pattern can either always include them (INCLUDE), skip over them (EXCLUDE) or only include them if the pattern allows for a day off on that day (MATCH). PatternDay: type: object additionalProperties: false minProperties: 1 properties: shifts: $ref: '#/components/schemas/RuleFiltersShifts' keyword: $ref: '#/components/schemas/PatternDayKeyword' RuleFiltersRoles: description: Used to apply the rule only to work carried out in specific roles. type: object additionalProperties: false properties: ids: type: array items: type: string description: List of relevant role ids. uniqueItems: true PeriodicRestTargets: description: The target amounts of rest for each period. type: object additionalProperties: false properties: continuousRest: description: Target for a continuous amount of rest within each period. type: object additionalProperties: false properties: minHours: description: >- The minimum number of hours of continuous rest each period should have. type: number PeriodicRestOptions: description: Additional options for how the rule should be applied. type: object additionalProperties: false properties: blockedPeriods: $ref: '#/components/schemas/Periods' description: >- Periods that should never be considered as rest. For example, use this to indicate that public holidays should not be considered rest periods even when unworked. periodGroups: description: >- Groups of periods during which periodic rest should be met. The rule is considered satisfied if there is at least one period group for which the periodic rest is met for all of its periods. Cannot be used together with the regular 'periods' field. type: array items: $ref: '#/components/schemas/Periods' PeriodDistributionTargets: description: Defines targets and limits on the distribution of worked periods. type: object additionalProperties: false properties: minWorkedPeriods: type: integer description: >- The minimum amount of periods in which the employee should work. This is treated as a target instead of a strict limit. minimum: 0 maxWorkedPeriods: type: integer description: The maximum amount of periods in which the employee can work. minimum: 0 maxConsecutiveWorkedPeriods: type: integer description: >- The maximum amount of consecutive periods in which the employee can work. minimum: 1 minSurroundingFreePeriods: type: integer description: >- The minimum amount of non-worked periods both before and after a worked period. minimum: 0 PeriodDistributionOptions: description: Additional options for how the rule should be applied. type: object additionalProperties: false properties: overlapSettings: $ref: '#/components/schemas/OverlapSettings' description: Specify when a shift should count as working a period. LayoutObjectives: type: object additionalProperties: false minProperties: 1 properties: groupSize: $ref: '#/components/schemas/Objective' description: >- Indicates whether small/large groups are preferred (or whether this is not relevant). groupSeparation: $ref: '#/components/schemas/Objective' description: >- Indicates whether groups should be placed close together or spread out (or whether this is not relevant). RotationFilters: type: object additionalProperties: false description: >- Filters to determine the scope of the rule. Used to decide which employees the rule should be applied to. properties: employees: $ref: '#/components/schemas/RuleFiltersEmployees' RotationRuleTargets: type: object additionalProperties: false required: - rotationAmount properties: rotationAmount: type: integer minimum: 0 FairnessFilters: type: object additionalProperties: false properties: rules: $ref: '#/components/schemas/RuleFiltersRules' description: >- Used to filter which rules this fairness rule should be applied to. May only contain rules of the same type. ShiftLabelRule: type: object additionalProperties: false properties: label: type: string description: >- Unique identifier. The name of the shift label that is applied to shifts that adheres to the rules specified. startTimeWindow: $ref: '#/components/schemas/TimeWindow' description: If specified, the shift must start inside this time window. endTimeWindow: $ref: '#/components/schemas/TimeWindow' description: If specified, the shift must end inside this time window. includesTimeWindow: $ref: '#/components/schemas/TimeWindow' description: If specified, the shift must completely cover this time window. durationRange: $ref: '#/components/schemas/DurationInterval' description: >- If specified, the shift must have a duration that falls inside this range. gapRange: $ref: '#/components/schemas/DurationInterval' description: >- If specified, the shift must have a gap (between any two shift intervals) that falls inside this range. workloadCategories: type: array items: type: string description: >- If specified, the shift must have at least one of the workload categories specified in this list. uniqueItems: true PeriodLabelRule: type: object additionalProperties: false required: - label - periods properties: label: type: string description: The label to assign to the specified periods. periods: $ref: '#/components/schemas/PeriodsWithoutLabels' description: The periods to which the label should be applied. Day: description: Describes one day in the schedule. type: object additionalProperties: false minProperties: 1 maxProperties: 1 properties: date: $ref: '#/components/schemas/Date' dayIndex: $ref: '#/components/schemas/DayIndex' TaskCooldownToOthers: type: object additionalProperties: false required: - tasks - minutes properties: tasks: $ref: '#/components/schemas/TaskFilters' minutes: type: integer minimum: 0 MetricScope: type: object description: Selects one metric, optionally limited to rules with a matching label. additionalProperties: false required: - metricKey properties: metricKey: $ref: '#/components/schemas/MetricKey' description: The metric to track. ruleLabel: type: string minLength: 1 description: >- Limits the metric to rules whose labels include this exact, case-sensitive value. OutputLanguage: type: string description: Product-supported language for generated Reasoning Engine output. enum: - en - nb - nl - sv - lv DaysWithTime: description: >- List of days in the schedule. Each day will become one period. By default, each period will last the entire day. If a startTime and/or endTime are specified, these will apply to each period. type: object additionalProperties: false properties: dates: description: List of dates in the schedule. Only allowed in CALENDAR payloads. type: array uniqueItems: true items: $ref: '#/components/schemas/Date' dayIndices: description: >- List of day indices in the schedule. Only allowed in RECURRING payloads. type: array uniqueItems: true items: $ref: '#/components/schemas/DayIndex' daysOfWeek: description: >- List of days of the week. Will apply to all days in the schedule that match any of the specified weekdays. type: array uniqueItems: true items: $ref: '#/components/schemas/DayOfWeek' startTime: $ref: '#/components/schemas/TimeStamp' description: >- Time of day at which each period starts. If not specified, this defaults to 00:00. endTime: $ref: '#/components/schemas/TimeStamp' description: >- Time of day at which each period ends. If not specified, this defaults to end of day. CustomPeriodDefinition: type: object additionalProperties: false properties: startDay: $ref: '#/components/schemas/Day' description: >- The day in the schedule where the period starts. If not specified, this defaults to the first day of the schedule. endDay: $ref: '#/components/schemas/Day' description: >- The day in the schedule where the period ends. If not specified, this defaults to the last day of the schedule. startTime: $ref: '#/components/schemas/TimeStamp' description: >- Time of day at which each period starts. If not specified, this defaults to 00:00. endTime: $ref: '#/components/schemas/TimeStamp' description: >- Time of day at which each period ends. If not specified, this defaults to end of the day. applyTimeToAllDays: type: boolean description: >- If true, the startTime and endTime will be applied to each individual day in the period. If false, the startTime will apply to the first day and the endTime will apply to the last day. default: false RecurrentPeriodDefinition: type: object additionalProperties: false description: A recurrent definition to easily create a set of similar periods. required: - daysPerPeriod properties: daysPerPeriod: type: integer description: The number of days in each period. minimum: 1 daysBetweenStarts: type: integer description: >- The number of days between the start of each period. If not specified, this defaults to the value of daysPerPeriod, creating non-overlapping consecutive periods. Setting daysBetweenStarts to 1 will create a sliding window of periods. minimum: 1 startDay: $ref: '#/components/schemas/Day' description: >- The day in the schedule where the first period will start. If not specified, this defaults to the first day of the schedule. endDay: $ref: '#/components/schemas/Day' description: >- The day in the schedule where the last period will end. If not specified, this defaults to the last day of the schedule. startTime: $ref: '#/components/schemas/TimeStamp' description: >- Time of day at which each period starts. If not specified, this defaults to 00:00. endTime: $ref: '#/components/schemas/TimeStamp' description: >- Time of day at which each period ends. If not specified, this defaults to end of the day. applyTimeToAllDays: type: boolean description: >- If true, the startTime and endTime will be applied to each individual day in the period. If false, the startTime will apply to the first day and the endTime will apply to the last day. default: false RuleFiltersEmployees: type: object additionalProperties: false description: >- Used to filter which employees the rule should be applied to. If not specified, the rule applies to all employees. properties: ids: type: array items: type: string description: List of employee ids that the rule should be applied to. uniqueItems: true labels: type: array description: List of employee labels that the rule should be applied to. items: type: string uniqueItems: true matchTypes: $ref: '#/components/schemas/RuleFiltersEntityMatchTypes' RuleFiltersShifts: type: object additionalProperties: false description: >- Used to filter which shifts the rule should be applied to. If not specified, the rule applies to all shifts. properties: ids: type: array items: type: string description: List of shift ids that the rule should be applied to. uniqueItems: true labels: type: array description: List of shift labels that the rule should be applied to. items: type: string uniqueItems: true matchTypes: $ref: '#/components/schemas/RuleFiltersEntityMatchTypes' RuleFiltersWork: type: object additionalProperties: false description: >- Defines filtering for specific work that the rule should be applied to. For example, it can be used to apply the rule only to work carried out in specific roles. properties: roles: $ref: '#/components/schemas/RuleFiltersRoles' workloads: description: >- Used to apply the rule only to work carried out with specific workload categories. type: object additionalProperties: false properties: categories: type: array items: type: string description: >- If specified, the shift must have at least one of the workload categories specified in this list. uniqueItems: true OverlapSettings: description: >- Specifies overlap thresholds that a shift must meet with the rule's periods in order for it to be counted as relevant for the rule. type: object additionalProperties: false properties: minOverlapHours: type: integer description: >- The minimum number of hours that a shift must overlap with the rule in order to be counted as relevant for this rule. minimum: 1 minOverlapPercentage: type: integer description: >- The minimum percentage of the shift that must overlap with the rule in order to be counted as relevant for this rule. minimum: 1 maximum: 100 EmptyDayBehaviour: type: string default: INCLUDE enum: - INCLUDE - EXCLUDE - MATCH PatternDayKeyword: type: string description: >- A keyword to represent that a day must be a day off (DAY_OFF), must be a worked day (ANY_SHIFT), or that there are no requirements on this day (ANY). enum: - DAY_OFF - ANY_SHIFT - ANY Objective: type: string enum: - IGNORE - MINIMIZE - MAXIMIZE default: IGNORE RuleFiltersRules: type: object additionalProperties: false description: Used to filter which other rules this rule should be applied to. properties: ids: type: array items: type: string description: List of rule ids that this fairness rule should be applied to. uniqueItems: true labels: type: array description: List of rule labels that this fairness rule should be applied to. items: type: string uniqueItems: true TimeWindow: type: object additionalProperties: false description: >- Specifies an interval with start and end time. If the end time is before the start time, the time window is assumed to wrap around midnight. required: - start - end properties: start: $ref: '#/components/schemas/TimeStamp' end: $ref: '#/components/schemas/TimeStamp' DurationInterval: type: object additionalProperties: false description: >- An interval of time duration. Equivalent to saying a duration between 1 hour, 30 minutes and 2 hours, 45 minutes. Note that both min and max duration are required. For an interval that is shorter than 5 hours, set min = 0h and max = 5h. For an interval that is longer than 5 hours, set min = 5h and max = 99h. required: - min - max properties: min: $ref: '#/components/schemas/Duration' max: $ref: '#/components/schemas/Duration' PeriodsWithoutLabels: type: object additionalProperties: false minProperties: 1 maxProperties: 1 description: >- List of periods in the schedule. Periods can either be defined explicitly using custom definitions, or through a recurrent definition. A recurrent definition can be used to easily generate a list of similar periods (such as weeks, months, etc.). properties: days: $ref: '#/components/schemas/DaysWithTime' customDefinitions: type: array description: >- List of custom period definitions. Each custom period definition defines one period in the schedule. items: $ref: '#/components/schemas/CustomPeriodDefinition' recurrentDefinition: $ref: '#/components/schemas/RecurrentPeriodDefinition' TaskFilters: type: object additionalProperties: false properties: id: type: string description: Id of the task that the cooldown applies to. labels: type: array description: Labels used to select the tasks that the cooldown applies to. items: type: string uniqueItems: true matchType: $ref: '#/components/schemas/RuleFiltersEntityMatchTypes' description: Used to indicate how the id and label filters should be applied. MetricKey: type: string description: >- A public enum that identifies one supported status metric by combining its domain and metric name. enum: - AVAILABILITY.WORKED_MINUTES - AVAILABILITY.ASSIGNMENTS - DEMAND.MISSING_MINUTES_TO_MIN - DEMAND.MISSING_MINUTES_TO_IDEAL - DEMAND.MISSING_SHIFTS_TO_MIN - DEMAND.MISSING_SHIFTS_TO_IDEAL - COOLDOWN.MISSING_DAYS - COOLDOWN.MISSING_MINUTES - COOLDOWN.VIOLATIONS - CONSECUTIVE.MIN_VIOLATIONS - PATTERN.DESIRED_COMPLETE_MATCHES - PATTERN.DESIRED_PARTIAL_MATCHES - PATTERN.DESIRED_INCOMPLETE_PERIODS - PATTERN.UNDESIRED_COMPLETE_PERIODS - UTILIZATION.TOTAL_MINUTES - UTILIZATION.MINUTES_BELOW_MIN - UTILIZATION.MINUTES_BELOW_IDEAL - UTILIZATION.MINUTES_ABOVE_IDEAL - UTILIZATION.ASSIGNMENTS_BELOW_MIN - UTILIZATION.ASSIGNMENTS_BELOW_IDEAL - UTILIZATION.ASSIGNMENTS_ABOVE_IDEAL - PERIOD_DISTRIBUTION.WORKED_PERIODS - PERIOD_DISTRIBUTION.MISSING_WORKED_PERIODS - PERIOD_DISTRIBUTION.EXCESSIVE_WORKED_PERIODS - PERIOD_DISTRIBUTION.MAX_CONSECUTIVE_VIOLATIONS - PERIOD_DISTRIBUTION.MIN_SURROUNDING_VIOLATIONS - PERIODIC_REST.CONTINUOUS_REST_VIOLATIONS RuleFiltersEntityMatchTypes: type: object additionalProperties: false properties: ids: $ref: '#/components/schemas/MatchType' description: >- Used to indicate how to apply the id filters. For example, if set to NONE, entities with the specified ids will be excluded. labels: $ref: '#/components/schemas/MatchType' description: >- 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. Duration: type: object additionalProperties: false description: >- A simple duration of time. E.g. 30 minutes, 2 hours or 2 hours, 30 minutes. Either hours or minutes must be set. They both default to zero, if not specified. Minutes must be a multiple of 5 as this is the smallest time unit used. minProperties: 1 properties: hours: type: integer minimum: 0 default: 0 minutes: type: integer multipleOf: 5 minimum: 0 default: 0 MatchType: type: string enum: - NONE - ANY - ALL default: ANY responses: JobId: description: Response containing the job ID of the initiated roster job. content: application/json: schema: type: object additionalProperties: false required: - jobId properties: jobId: type: string format: uuid BadRequest: description: Request was invalid. content: application/json: schema: $ref: '#/components/schemas/Error' InternalServerError: description: Server failed to process the request. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: vismaConnectBearer: type: http scheme: bearer bearerFormat: JWT description: >- Include the access token in the Authorization header using the Bearer scheme. ````