> ## 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 job > Create and start a new job for the solver. ## OpenAPI ````yaml /v1/api-reference/openapi.no-deprecated.yml post /jobs openapi: 3.1.0 info: title: Automatic Rostering description: API for the automatic creation of rosters. version: json_alpha servers: - url: https://api.optimization-rostering.stag.visma.net description: Stage (dev) environment - url: https://api.optimization-rostering.prod.visma.net description: Production environment security: [] tags: - name: Roster description: Endpoints for starting, stopping, and retrieving scheduling jobs - name: Analyze description: Endpoint for analyzing job requests paths: /jobs: post: tags: - Roster summary: Start job description: Create and start a new job for the solver. parameters: - in: header name: CUSTOMER_ID schema: type: string required: true - in: header name: USER_ID schema: type: string required: true requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/request' responses: '202': description: Job accepted for processing content: application/json: schema: $ref: '#/components/schemas/job' '400': description: Payload defined in request body is not valid content: application/json: schema: $ref: '#/components/schemas/badRequest' '406': description: Defined Accept type is not supported content: text/plain: schema: type: string example: >- Not Acceptable. Supported Accept types are application/xml, application/json '415': description: Defined Content-Type is not supported content: text/plain: schema: type: string example: >- Unsupported content type. Supported Content-Types are application/xml, application/json security: - vismaConnectBearer: [] components: schemas: request: $schema: https://json-schema.org/draft/2020-12/schema title: Roster request type: object description: Payload format representing a rostering job. required: - jobInfo - demands - employees properties: jobInfo: $ref: '#/components/schemas/jobInfo' 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' constraints: $ref: '#/components/schemas/constraints' configuration: $ref: '#/components/schemas/configuration' extensions: description: Extensions that can be helpful in more advanced rostering scenarios. type: object properties: taskGroups: type: array description: List of task groups used in this roster. items: $ref: '#/components/schemas/taskGroup' tasks: type: array description: List of tasks used in this roster. items: $ref: '#/components/schemas/task' job: $schema: https://json-schema.org/draft/2020-12/schema title: Job response body type: object required: - jobId - statusCode - links properties: jobId: type: string description: Unique identifier for the job. example: 78f0aawf13a0436f916cd6gf468afc61 statusCode: type: string enum: - starting - running - stopped - error description: Current status of the job. example: starting link: description: Links to retrieve the request payload. type: object properties: rel: type: string description: The relationship type of the link. example: request href: type: string description: The URL for the linked resource without base. example: /jobs/78f0aawf13a0436f916cd6gf468afc61/request badRequest: $schema: https://json-schema.org/draft/2020-12/schema title: Bad request response type: object required: - errors properties: errors: type: array items: type: object properties: code: type: string enum: - INVALID_PAYLOAD - SHIFT_UTILIZATION_CONSTRAINT - BLOCKED_TIME_CONSTRAINT - MISSING_SHIFT_COMPETENCES - DUPLICATE_ID - MISSING_ID_REFERENCE message: type: string constraintId: type: string employeeId: type: string shift: type: string maxOccurrence: type: integer lockedOccurrence: type: integer required: - code - message example: errors: - code: SHIFT_UTILIZATION_CONSTRAINT message: Employee 1 has exceeded shift limit constraintId: max_shift_limit_1 employeeId: '1' shift: Morning Shift maxOccurrence: 2 lockedOccurrence: 3 - code: SHIFT_UTILIZATION_CONSTRAINT message: Employee 2 has exceeded shift limit constraintId: max_shift_limit_2 employeeId: '2' shift: Evening Shift maxOccurrence: 2 lockedOccurrence: 4 jobInfo: type: object description: Details about the job that the solver will solve. required: - id - organisationId - scheduleType - demandType - planningHorizon properties: id: $ref: '#/components/schemas/rosterId' organisationId: $ref: '#/components/schemas/organisationId' scheduleType: description: Type of schedule that the solver should create. type: string enum: - CALENDAR - RECURRING demandType: $ref: '#/components/schemas/demandType' planningHorizon: $ref: '#/components/schemas/planningHorizon' employee: type: object required: - id properties: id: $ref: '#/components/schemas/employeeId' labels: type: array description: >- List of labels assigned to this employee. Labels can be used in constraints 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 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 the solver will not assign new shifts to this employee. default: false demand: type: object properties: days: description: >- List of days on which this demand exists. Multiple demands can exist on the same day. type: object 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' 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 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 constraints to group shifts. items: type: string uniqueItems: true isReadOnly: type: boolean description: >- If set to true, the shift will not be assigned by the solver. Read only shifts will not be used in new assignments by the solver, 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 the solver, 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' connectedShiftsPreviousDay: $ref: '#/components/schemas/connectedShifts' description: >- List of shifts that are connected to this shift on the previous day. If defined, this shift will always be preceded by one of the connected shifts the previous day. connectedShiftsNextDay: $ref: '#/components/schemas/connectedShifts' description: >- List of shifts that are connected to this shift on the next day. If defined, this shift will always be followed by one of the connected shifts the next day. 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 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' constraints: type: object description: >- Constraints that should be active for this solver run. Used to specify all sorts of preferences, rules and restrictions. properties: employeeAvailabilityConstraints: description: >- Constraints that specify when and for which shifts employees should be considered (un)available. type: array items: $ref: '#/components/schemas/employeeAvailabilityConstraint' employeeUtilizationConstraints: description: >- Constraints that specify targets and limits for how much employees should work (per period). type: array items: $ref: '#/components/schemas/employeeUtilizationConstraint' cooldownConstraints: description: >- Constraints that specify the minimum time between two kinds of work for employees. type: array items: $ref: '#/components/schemas/cooldownConstraint' consecutiveConstraints: description: >- Constraints that limit the number of consecutive entities an employee can work. type: array items: $ref: '#/components/schemas/consecutiveConstraint' patternConstraints: description: >- Constraints that specify patterns of shifts that are (un)desirable for employees to follow. type: array items: $ref: '#/components/schemas/patternConstraint' periodicRestConstraints: description: >- Constraints that specify targets for the amount of (continuous) rest employees get per period. type: array items: $ref: '#/components/schemas/periodicRestConstraint' periodDistributionConstraints: description: >- Constraints that improve the distribution of work during undesired periods over employees. type: array items: $ref: '#/components/schemas/periodDistributionConstraint' layoutConstraints: description: >- Constraints that improve the layout of shifts across the roster for employees. type: array items: $ref: '#/components/schemas/layoutConstraint' rotationConstraints: description: >- Constraints that specify targets for rotating employees through a series of periods. type: array items: $ref: '#/components/schemas/rotationConstraint' fairnessConstraints: description: >- Constraints that improve distribution of (in)conveniences from other constraints over employees. type: array items: $ref: '#/components/schemas/fairnessConstraint' configuration: type: object description: Configurations for this solver run. properties: labels: $ref: '#/components/schemas/labels' fteBelongsToShift: type: boolean default: true description: >- Whether to count FTE hours that fall outside of the FTE period, but are part of a shift that is planned on a day inside the FTE count period. For example, a shift that starts at 23:00 on the last day of the FTE period. bonusTimeRules: $ref: '#/components/schemas/bonusTimeRules' defaultTimeRules: $ref: '#/components/schemas/defaultTimeRules' taskGroup: type: object required: - id - taskIds if: required: - maxMinutes then: required: - cooldownMinutes properties: id: type: string description: Unique identifier. taskIds: type: array description: List of task ids that belong to this task group. items: type: string uniqueItems: true minMinutes: $ref: '#/components/schemas/taskMinMinutes' description: >- Minimum time in minutes an employee needs to work on tasks from this group consecutively. maxMinutes: $ref: '#/components/schemas/taskMaxMinutes' description: >- Maximum time in minutes an employee is allowed to work on tasks from this group consecutively. Afterwards, a cooldown is required. cooldownMinutes: $ref: '#/components/schemas/taskCooldownMinutes' description: >- Time in minutes that has to pass after performing a task from this group, before the employee can perform another task from this group. cooldowns: type: array description: >- Define different cooldowns that become active after working on a task from this group. These can be used to prevent an employee from working on a task or task group for a certain amount of time after working on this task group. Requires either taskId or taskGroupId to be set. items: $ref: '#/components/schemas/cooldown' task: type: object required: - id if: required: - maxMinutes then: required: - cooldownMinutes properties: id: type: string description: Unique identifier. attributeRequirements: description: >- List of requirements on the attributes that an employee needs to be eligible to carry out this Task. If an employee does not meet all of the requirements, the employee can not carry out this Task. type: array items: $ref: '#/components/schemas/attributeRequirement' minMinutes: $ref: '#/components/schemas/taskMinMinutes' description: >- Minimum time in minutes an employee needs to work on this task consecutively. maxMinutes: $ref: '#/components/schemas/taskMaxMinutes' description: >- Maximum time in minutes an employee is allowed to work on this task consecutively. Afterwards, a cooldown is required. cooldownMinutes: $ref: '#/components/schemas/taskCooldownMinutes' description: >- Time in minutes an employee needs to rest before working on this task again. cooldowns: type: array description: >- Define different cooldowns that become active after working on this task. These can be used to prevent an employee from working on a task or task group for a certain amount of time after working on this task. Requires either taskId or taskGroupId to be set. items: $ref: '#/components/schemas/cooldown' rosterId: type: string description: Identifier for this roster. organisationId: type: string description: Identifier for the organisation/user that has requested this roster. demandType: description: Type of demand that will be used in this job. type: string enum: - SHIFT_DEMAND - TIME_DEMAND planningHorizon: type: object description: >- Specifies the planning horizon for which a roster will be created. The required properties depend on the chosen scheduleType. required: - startDate properties: startDate: $ref: '#/components/schemas/date' description: >- Format YYYY-MM-DD. The start date of the planning horizon. The solver will only schedule shifts for days within the planning horizon. If you need to include locked shifts outside the period for which you have demands, the planning horizon should be extended to include these days. For RECURRING jobs, this must be the first Monday of the first week. endDate: $ref: '#/components/schemas/date' description: >- Format YYYY-MM-DD. Only required for CALENDAR jobs. The end date of the planning horizon. The solver will only schedule shifts for days within the planning horizon. If you need to include locked shifts outside the period for which you have demands, the planning horizon should be extended to include these days. nrOfWeeks: minimum: 1 type: integer description: >- Only required for RECURRING jobs. The number of weeks in the planning horizon. fteStartDay: $ref: '#/components/schemas/scheduleDay' description: >- The start day of the period where FTE is counted. Any work planned outside this period will not be counted towards FTE. fteEndDay: $ref: '#/components/schemas/scheduleDay' description: >- The end day of the period where FTE is counted. Any work planned outside this period will not be counted towards FTE. employeeId: type: string description: Unique identifier for this employee. attribute: type: object 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 can have the values "marketing" and "finance" for an attribute with the id "department". periods: $ref: '#/components/schemas/periods' preassignedShift: type: object 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 the solver. 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. date: type: - string - 'null' format: date description: >- Date is specified in ISO8601 format YYYY-MM-DD. Can only be used when schedule type is CALENDAR. dayIndex: type: - integer - 'null' description: >- Day index relative to the first day of the period (starts at 0). Can only be used when schedule type is RECURRING. minimum: 0 dayOfWeek: type: string enum: - MON - TUE - WED - THU - FRI - SAT - SUN shiftDemand: type: object 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. The solver 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. The solver prefers to cover the demand with exactly this number of employees. max: type: integer description: >- Maximum number of employees needed to cover the demand. The solver 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 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. The solver 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. The solver prefers to cover the demand with exactly this number of employees. max: type: integer description: >- Maximum number of employees needed to cover the demand. The solver 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. days: description: >- List of days in the schedule. Days can be defined as an array of dates (in CALENDAR payloads), as an array of day indices (in RECURRING payloads), or as an array of weekdays (allowed in all payloads). type: object 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' shiftInterval: type: object 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 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. The solver does 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. connectedShifts: type: object minProperties: 1 properties: shiftIds: type: array description: List of ids of shifts that are connected to this shift. uniqueItems: true items: $ref: '#/components/schemas/shiftId' shiftTemplateIds: type: array description: List of ids of shift templates that are connected to this shift. uniqueItems: true items: type: string dayOff: type: boolean description: Whether the connected shift can be a day off. default: false attributeRequirement: type: object 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 employeeAvailabilityConstraint: type: object description: >- Used to indicate when employees are strictly or preferably available or unavailable to work. required: - id - importance - isDesired properties: id: $ref: '#/components/schemas/constraintId' labels: $ref: '#/components/schemas/constraintLabels' importance: $ref: '#/components/schemas/importanceWithStrict' isDesired: type: boolean description: >- If set to true, it will be considered preferable for employees to work the shifts that this constraint applies to during the specified periods. If set to false, the solver 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/employeeAvailabilityFilters' periods: $ref: '#/components/schemas/periods' options: $ref: '#/components/schemas/employeeAvailabilityOptions' employeeUtilizationConstraint: description: >- Used to set targets and limits for the amount of hours or shifts worked by employees within given periods. type: object required: - id properties: id: $ref: '#/components/schemas/constraintId' labels: $ref: '#/components/schemas/constraintLabels' importance: $ref: '#/components/schemas/importance' filters: $ref: '#/components/schemas/employeeUtilizationFilters' targets: description: >- Specifies the target utilization for the constraint. Targets can be specified in number of FTE hours, or in number of shifts worked during the period. type: object properties: minHours: type: number description: >- The minimum number of hours that should be worked by employees on shifts that match the constraint 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 constraint 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 constraint 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 constraint 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 constraint 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 constraint 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. bonusTime: description: >- Settings to determine if and how bonus time rules affect the constraint. type: object 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 constraint. 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 overlapRules: $ref: '#/components/schemas/overlapRules' description: >- Specify when a scheduled shift should count towards the targets of this constraint. If both minOverlapHours and minOverlapPercentage are specified, shifts will be counted if they satisfy either requirement. If the overlapRules object is not defined, shifts are counted if they have any overlap with the constraint. periods: $ref: '#/components/schemas/periods' description: >- The periods in which the constraint should be applied. The minHours and maxHours will be applied to each period separately. cooldownConstraint: description: Used to define required or desired rest between working shifts. type: object required: - id - importance - targets properties: id: $ref: '#/components/schemas/constraintId' labels: $ref: '#/components/schemas/constraintLabels' importance: $ref: '#/components/schemas/importanceWithStrict' filters: type: object properties: employees: $ref: '#/components/schemas/constraintFiltersEmployees' work: $ref: '#/components/schemas/constraintFiltersWork' 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. 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 constraint 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. consecutiveConstraint: type: object 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/constraintId' labels: $ref: '#/components/schemas/constraintLabels' importance: $ref: '#/components/schemas/importanceWithStrict' filters: $ref: '#/components/schemas/constraintFilters' targets: $ref: '#/components/schemas/consecutiveTargets' patternConstraint: description: Used to define patterns of shifts that employees should follow or avoid. type: object required: - id - importance - isDesired - patterns properties: id: $ref: '#/components/schemas/constraintId' labels: $ref: '#/components/schemas/constraintLabels' importance: $ref: '#/components/schemas/importanceWithStrict' isDesired: description: >- If set to true, the solver will try to make employees follow the specified patterns. Else, it will try to avoid making employees follow any of the specified patterns. type: boolean filters: type: object description: >- Filters to determine the scope of the constraint. Used to decide which employees the constraint should be applied to. properties: employees: $ref: '#/components/schemas/constraintFiltersEmployees' 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, the solver 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: type: array items: type: object 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 constraints. 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/constraintFiltersRoles' description: >- Used to apply the constraint 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. emptyDayBehaviours: description: >- Describes whether the pattern should skip over days that could be considered irrelevant for the pattern. type: object 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). periodicRestConstraint: description: Used to set targets for continuous rest within specific periods. type: object required: - id properties: id: $ref: '#/components/schemas/constraintId' labels: $ref: '#/components/schemas/constraintLabels' importance: $ref: '#/components/schemas/importanceWithStrict' filters: $ref: '#/components/schemas/constraintFilters' targets: $ref: '#/components/schemas/periodicRestTargets' periods: $ref: '#/components/schemas/periods' description: The periods in which the constraint should be applied. 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 constraint 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' periodDistributionConstraint: description: >- Used to define targets and limits for the distribution of periods (like weekends, holidays, nights). type: object required: - id properties: id: $ref: '#/components/schemas/constraintId' labels: $ref: '#/components/schemas/constraintLabels' importance: $ref: '#/components/schemas/importanceWithStrict' filters: $ref: '#/components/schemas/constraintFilters' 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 overlapRules: $ref: '#/components/schemas/overlapRules' description: Specify when a shift should count as working a period. periods: $ref: '#/components/schemas/periods' layoutConstraint: type: object required: - id - importance - objectives properties: id: $ref: '#/components/schemas/constraintId' labels: $ref: '#/components/schemas/constraintLabels' importance: $ref: '#/components/schemas/importance' filters: $ref: '#/components/schemas/constraintFilters' objectives: $ref: '#/components/schemas/layoutObjectives' description: >- Describes the targets for this constraint. Targets can indicate whether small/large groups are preferred and whether groups should be placed close together or spread out. rotationConstraint: type: object required: - id - importance - targets - periods properties: id: $ref: '#/components/schemas/constraintId' labels: $ref: '#/components/schemas/constraintLabels' importance: $ref: '#/components/schemas/importanceWithStrict' filters: type: object description: >- Filters to determine the scope of the constraint. Used to decide which employees the constraint should be applied to. properties: employees: $ref: '#/components/schemas/constraintFiltersEmployees' targets: $ref: '#/components/schemas/rotationConstraintTargets' periods: $ref: '#/components/schemas/periods' description: The periods in which the constraint should be applied. assignedRotations: type: array description: >- List of employees that have been assigned to specific rotations. The solver will try to ensure that these employees follow the specified rotations as much as possible. items: type: object 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. The solver will try to ensure that these employees work during the specified periods as much as possible. items: type: object 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 fairnessConstraint: type: object required: - id properties: id: $ref: '#/components/schemas/constraintId' importance: $ref: '#/components/schemas/importance' description: The importance of adhering to this fairness constraint. filters: type: object properties: constraints: $ref: '#/components/schemas/constraintFiltersConstraints' description: >- Used to filter which constraints this fairness constraint should be applied to. May only contain constraints of the same type. applyConstraintImportanceScaling: type: boolean description: >- If true, more importance is given to (in)conveniences for constraints 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 constraintFactors: type: array description: >- Technical property. Contact dev team for information on how to use this. items: type: object properties: constraintId: type: string description: >- The id of the constraint for which this factor should be applied. factor: type: number description: >- The factor to apply to the (in)conveniences of the specified constraint when calculating fairness. minimum: 0 maximum: 2 labels: description: >- Define automatic assignment of labels to shifts and periods. These labels can be reused in constraints. type: object 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 constraints. type: array items: $ref: '#/components/schemas/periodLabelRule' bonusTimeRules: description: >- List of rules for assigning bonus minutes to employees based on the times of the shifts they work. type: array items: type: object 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. defaultTimeRules: type: array items: type: object properties: defaultHoursPerDay: type: number employeeIds: type: array items: type: string uniqueItems: true periods: $ref: '#/components/schemas/periods' taskMinMinutes: type: integer default: 0 minimum: 0 maximum: 10080 taskMaxMinutes: type: integer minimum: 5 maximum: 10080 taskCooldownMinutes: type: integer default: 0 minimum: 0 cooldown: type: object required: - minutes properties: minutes: type: integer description: >- The number of minutes that must pass after working on this task or task group before working on the Task or Task group specified in this cooldown. minimum: 0 taskId: type: string description: The id of the task that the cooldown applies to. taskGroupId: type: string description: The id of the task group that the cooldown applies to. scheduleDay: type: object description: >- Defines a day in the planning horizon. If the schedule type is RECURRING, then dayIndex must be specified, and if the schedule type is CALENDAR, then date must be specified. minProperties: 1 maxProperties: 1 properties: dayIndex: $ref: '#/components/schemas/dayIndex' date: $ref: '#/components/schemas/date' periods: type: object 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' labels: type: array uniqueItems: true description: >- Provide labels to re-use periods that were defined in the configuration. items: type: string attributeRequirementGroup: type: object 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 the solver prioritize it compared to demands, but also compared to constraints. dayIndicator: type: integer minimum: -1 maximum: 1 attributeMatchType: type: string enum: - NONE - ANY - ALL default: ALL constraintId: type: string description: Unique identifier for the constraint. constraintLabels: type: array description: >- Labels for the constraint. Labels can be used to group constraints together. For example, if multiple constraints are related to the same shift type, they can all be labeled with the same label. uniqueItems: true items: type: string importanceWithStrict: type: string enum: - NONE - VERY_LOW - LOW - MEDIUM - HIGH - VERY_HIGH - STRICT description: >- The importance of the constraint. The higher the importance, the more the solver will take the constraint into account. Under strict importance, the constraint may never be violated. employeeAvailabilityFilters: type: object description: >- Filters to determine the scope of the constraint. Used to decide which employees and which shifts the constraint 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/constraintFiltersEmployees' shifts: $ref: '#/components/schemas/constraintFiltersShifts' work: $ref: '#/components/schemas/constraintFiltersWork' employeeAvailabilityOptions: type: object 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 constraints. importance: type: string enum: - NONE - VERY_LOW - LOW - MEDIUM - HIGH - VERY_HIGH description: >- The importance of the constraint. The higher the importance, the more the solver will take the constraint into account. employeeUtilizationFilters: type: object description: >- Filters to determine the scope of the constraint. Used to decide which employees and which shifts the constraint 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/constraintFiltersEmployees' shifts: $ref: '#/components/schemas/constraintFiltersShifts' work: $ref: '#/components/schemas/constraintFiltersWork' overlapRules: description: >- Specifies overlap thresholds that a shift must meet with the constraint's periods in order for it to be counted as relevant for the constraint. type: object properties: minOverlapHours: type: integer description: >- The minimum number of hours that a shift must overlap with the constraint in order to be counted as relevant for this constraint. minimum: 1 minOverlapPercentage: type: integer description: >- The minimum percentage of the shift that must overlap with the constraint in order to be counted as relevant for this constraint. minimum: 1 maximum: 100 constraintFiltersEmployees: type: object description: >- Used to filter which employees the constraint should be applied to. If not specified, the constraint applies to all employees. properties: ids: type: array items: type: string description: List of employee ids that the constraint should be applied to. uniqueItems: true labels: type: array description: List of employee labels that the constraint should be applied to. items: type: string uniqueItems: true matchTypes: $ref: '#/components/schemas/constraintFiltersEntityMatchTypes' constraintFiltersWork: type: object description: >- Defines filtering for specific work that the constraint should be applied to. For example, it can be used to apply the constraint only to work carried out in specific roles. properties: roles: $ref: '#/components/schemas/constraintFiltersRoles' workloads: description: >- Used to apply the constraint only to work carried out with specific workload categories. type: object 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 cooldownStartsOrEnds: type: object properties: shifts: type: object properties: ids: type: array items: type: string description: >- List of shift ids that the constraint should be applied to. If not specified, no filtering is applied based on shift ids. uniqueItems: true labels: type: array items: type: string uniqueItems: true matchTypes: $ref: '#/components/schemas/constraintFiltersEntityMatchTypes' filters: description: DEPRECATED. type: array items: $ref: '#/components/schemas/advancedFilter' matchType: $ref: '#/components/schemas/matchType' description: DEPRECATED. cooldownTargets: type: object 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 constraintFilters: type: object description: >- Filters to determine the scope of the constraint. Used to indicate what the constraint should be applied to (which employees, which shifts, etc). Leaving this empty means that the constraint always applies. properties: employees: $ref: '#/components/schemas/constraintFiltersEmployees' shifts: $ref: '#/components/schemas/constraintFiltersShifts' consecutiveTargets: type: object 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 patternDay: type: object minProperties: 1 properties: shifts: $ref: '#/components/schemas/constraintFiltersShifts' keyword: $ref: '#/components/schemas/patternDayKeyword' constraintFiltersRoles: description: Used to apply the constraint only to work carried out in specific roles. type: object properties: ids: type: array items: type: string description: List of relevant role ids. uniqueItems: true emptyDayBehaviour: type: string default: INCLUDE enum: - INCLUDE - EXCLUDE - MATCH periodicRestTargets: type: object properties: continuousRest: type: object properties: minHours: type: number layoutObjectives: type: object 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). rotationConstraintTargets: type: object required: - rotationAmount properties: rotationAmount: type: integer minimum: 0 constraintFiltersConstraints: type: object description: >- Used to filter which other constraints this constraint should be applied to. properties: ids: type: array items: type: string description: >- List of constraint ids that this fairness constraint should be applied to. uniqueItems: true labels: type: array description: >- List of constraint labels that this fairness constraint should be applied to. items: type: string uniqueItems: true shiftLabelRule: type: object 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 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. 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 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 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 description: A recurrent definition to easily create a set of similar periods. example: example_weekly: value: daysPerPeriod: 7 summary: >- The above recurrent definition will create a non-overlapping set of periods that are each 7 days long, spanning the entire roster. example_weekly_sliding: value: daysPerPeriod: 14 daysBetweenStarts: 1 summary: >- The above recurrent definition will create periods that are each two weeks long, with one such period starting on each day of the roster. This could for example be used to indicate that an employee must have 48 hours of rest in any two-week long period (using PeriodicRestConstraint). 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 constraintFiltersShifts: type: object description: >- Used to filter which shifts the constraint should be applied to. If not specified, the constraint applies to all shifts. properties: ids: type: array items: type: string description: List of shift ids that the constraint should be applied to. uniqueItems: true labels: type: array description: List of shift labels that the constraint should be applied to. items: type: string uniqueItems: true matchTypes: $ref: '#/components/schemas/constraintFiltersEntityMatchTypes' constraintFiltersEntityMatchTypes: type: object 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. advancedFilter: type: object required: - field - values properties: field: type: string description: The field to filter on. Can be "id" or "label". values: type: array description: The values to filter on. items: type: string uniqueItems: true matchType: $ref: '#/components/schemas/matchType' description: >- Defines how the values should be matched. For example, if set to ALL, an entity needs to have all of the specified values to match this filter. matchType: type: string enum: - NONE - ANY - ALL default: ANY 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 timeWindow: type: object 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 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 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' day: description: >- Describes one day in the schedule. Can be defined as a date (in CALENDAR payloads) or as a day index (in RECURRING payloads). type: object minProperties: 1 maxProperties: 1 properties: date: $ref: '#/components/schemas/date' dayIndex: $ref: '#/components/schemas/dayIndex' duration: type: object 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 in the solver. minProperties: 1 properties: hours: type: integer default: 0 minimum: 0 minutes: type: integer multipleOf: 5 minimum: 0 default: 0 securitySchemes: vismaConnectBearer: type: http scheme: bearer bearerFormat: JWT description: >- Enter the token with the `Bearer: ` prefix. You can retrieve token from Visma connect. ````