API docs by Redocly

adiutaOpt (v9.4.0)

Download OpenAPI specification:

adiutaByte GmbH: info@adiutabyte.de URL: https://adiutabyte.de

Introduction

Welcome to the adiutaOpt API documentation!

This document specifies all endpoints and schema requirements. If you notice an error, please contact us.

The typical process of an optimization request looks as follows:

  • Obtain authentication tokens
  • Use authentication tokens to post an input data set to the optimization request endpoint. If everything is in order, a key will be returned that has to be stored
    • If the request was rejected, check authentication details and schema. The return code and data will give some hints as to what needs to be fixed.
  • Use the authentication token and the key on the solution endpoint to request the solved data.
    • If the plan is still in calculation, wait until it's done
    • If the calculation has finished, store the solution
  • Check if the calculation could be carried out or if an error was returned (see ErrorPlan as possible return data of the solution endpoint)

The overview site can be found here.

Deployment Status

Deployment status data is available only on PROD/DEV/EXP documentation.

Common Data Types

Types that are reused in different definitions.

Date

string (Date) ^[0-9]{4}-(0?[1-9]|1[0-2])-(0?[1-9]|[1-2][0-9...

A string consisting of three parts following the pattern "YYYY-MM-DD":

  • "YYYY" year AD: 0-9999
  • "MM" month: 1-12
  • "DD" day: 1-31

While the schema does not check for validity, the optimization algorithms do. Including invalid dates (e.g. 2020-02-31) leads to a validation error.

Examples:

  • "2020-04-10"
  • "2051-4-1"
  • "1953-04-10"
"2020-04-10"

Language Type

integer (Language Type) [ 0 .. 1 ]

Values are:

  • 0: German
  • 1: English
1

Time

string (Time) ^[-]?([0-9]{1,9}):([0-5][0-9]|[0-9])$

A string of either format "hh:mm" or "-hh:mm":

  • "hh": hours (24h format),
  • "mm": minutes

Times are always interpreted relative to a date in the same object as the Time field. This allows times to exceed 24h or even become negative, as the value gets "added" to midnight of the date. For example, the following times applied to the respective date (in Date format) are equivalent:

  • "2021-05-21" at "07:25"
  • "2021-05-20" at "31:25"
  • "2021-05-19" at "55:25"
  • "2021-05-22" at "-16:35"
  • "2021-05-23" at "-40:35"
"07:25"

Gender Type

integer (Gender Type) [ 0 .. 3 ]

Values are:

  • 0: not provided
  • 1: male
  • 2: female
  • 3: other
3

Overlap Config Type

integer (Overlap Config Type) [ 0 .. 0 ]

Set preferences regarding overlap

  • 0 - Prefer the time slot being covered by a task
0
0

Weekday

integer (Weekday) [ 0 .. 6 ]

A numerical representation of a weekday. Values are:

  • 0: Sunday
  • 1: Monday
  • 2: Tuesday
  • 3: Wednesday
  • 4: Thursday
  • 5: Friday
  • 6: Saturday
6

FieldPlacerVersion

string (FieldPlacerVersion) ^[0-9]{4}-[0-9]{2}-[0-9]{2}_[0-9]+(p[0-9]+)?$...

A version consisting of the date of release [0-9]{4}-[0-9]{2}-[0-9]{2}_[0-9]+, which can have a patch suffix p[0-9]+.

"1970-01-01_0p0"

SemanticVersion

string (SemanticVersion) ^(v)?(0|([1-9][0-9]{0,4}))(\.(0|([1-9][0-9]{0...

See https://semver.org/ for a full description of semantic versioning. The regex here is a subset of allowed semantic versions.

"v1.2.3"

Authentication

How to authenticate before any request.

AWS Cognito

The authentication is performed via AWS Cognito (Developer-Guide). It is recommended to use one of the SKDs provided by AWS to simplify the authentication process considerably. Examples for SDKs:

Configuration

  • Used protocol: Secure Remote Password Protocol
  • User pool data:
    • UserPoolId/ClientId is available only on PROD/DEV/EXP documentation.
  • Username/Password are provided when signing up for an account. If you don't have an account, please contact us.

Tokens

Authentication provides three tokens: the access-token, the ID-token and the refresh-token. All three are JSON Web Tokens.

  • The access-token is currently not used in the API.
  • The ID-token has to be proposed in every request in the header as follows:

Authorization: 'ID-token'

  • The ID-token contains a timestamp when the token has been authorized (auth_time) and when it will expire (exp). Currently, an ID-token expires after one hour and requests with expired ID-tokens are rejected automatically. You can get a new ID-token by using the refresh-token without having to re-enter your credentials.

Request samples 

const user = "";        // your username
const pw = "";          // your password
const userPoolID = "";  // UserPoolID, see configuration details
const clientID = "";    // ClientId, see configuration details

const AmazonCognitoIdentity = require('amazon-cognito-identity-js');

module.exports.login = () => new Promise((resolve, reject) => {

  const userPool = new AmazonCognitoIdentity.CognitoUserPool({
    UserPoolId: userPoolID,
    ClientId: clientID
  });

  const authenticationDetails = new AmazonCognitoIdentity.AuthenticationDetails({
      Username: user,
      Password: pw,
  });

  const cognitoUser = new AmazonCognitoIdentity.CognitoUser({
      Username: user,
      Pool: userPool
  });

  cognitoUser.authenticateUser(authenticationDetails, {
    onSuccess: function (result) {
        const token = result.getIdToken().getJwtToken();
        resolve(token);
    },
    onFailure: function (err) {
        reject();
    }
  });
})

Optimization Request

Post an optimization request.

Optimization Request

Post a request to be solved.

If a new optimization request was received and was successfully processed, the endpoint will return 201 and the key with which the solution can be retrieved. This does not mean that calculating a solution will succeed, as logic errors, invalid ids and many other checks are performed later - these kinds of issues will result in an ErrorPlan, retrievable from the solution endpoint. Only schema violations are being checked in this request, they will result in the request being rejected with code 422.

Usually, if an optimization request was received but an identical request was already posted before, the endpoint will return 200 and the key with which the solution can be retrieved, which is identical to the key from the earlier request. This is not the case for certain errors which allow a repeat request (marked by the allowRepeat property of an ErrorPlan). Repeats for such requests are allowed after a certain amount of time has passed, trying to post before this cooldown has expired will result in rejection (code 429) where the retry-after header contains the remaining time in seconds until the request will be accepted again. If the repeat request was accepted, the endpoint returns code 201 and a new key to get the solution with.

Request to this endpoint have a content size limit which depends on the used content-type. Requests with content-type: application/json must contain a "plain-text" json payload which must be less than 6Mb in size. For sending larger requests, you must use content-type: application/vnd.adiutabyte.adiutaopt.json+[gzip,deflate,br]. These requests must contain the json data, compressed with gzip, deflate (zlib) or brotli, the payload size limit is 4.5Mb for the compressed data.

Authorizations:
BearerAuth
header Parameters
required
"application/json" (string) or "application/vnd.adiutabyte.adiutaopt.json+gzip" (string) or "application/vnd.adiutabyte.adiutaopt.json+deflate" (string) or "application/vnd.adiutabyte.adiutaopt.json+br" (string)

The content-type of the payload. Invalid values result in status code 415.

adiutaopt-version
string

(optional) A specific version to process the request under. Valid versions can be retrieved with the /packages-list endpoint (Name).

Using a specific version is not recommended for "general" application but for testing, debugging or other developer actions. Versions represent a specific state of the application, they cannot be changed, bug-fixed or extended in any way. For that reason, support for these requests may be limited.

Request Body schema:
object (Client)

Contains information about the client which sends this request.

required
object (ShiftPlannerMeta)

Meta information about what to consider in the optimization.

required
object (ShiftPlannerOptimizationParameters)

Parameters for the optimizer.

required
Array of objects (ShiftPlannerInputTask)

Array of Tasks to be planned by the optimizer.

required
Array of objects (ShiftPlannerInputWorker)

Array of available Workers.

object (ShiftPlannerHistory)

History data the optimizer can learn from to apply to the current request. History analysis is done differently for each of our customers, if you know what issues you want to address/ what results you want to see from such methods, please contact us so we can set up a solution.

recovery
Array of integers (IDReferences) [ items [ 0 .. 2147483647 ] ]
Deprecated

List of ids.

object (DeveloperOptions)

Options for developers. Do not use!

Responses

Request samples

Content type
Example

Basic blueprint for an optimization data set

{
  • "meta": {
    },
  • "parameters": {
    },
  • "tasks": [
    ],
  • "workers": [
    ]
}

Response samples

Content type
application/json
"VGVzdEtleUZvckFQSURvY3VtZW50YXRpb24uYXNk=="

Optimization Request (Preflight)

Responses

Solution

Retrieve the optimization solution for any application

Retrieving Solution

Retrieve the solution from this endpoint with the key you got when posting the request. The solution can either be a solved request or an ErrorPlan.

Responses from this endpoint have a content size limit which depends on the used content-type of the response, which can be specified with the accept header. If the response size would exceed that limit, the endpoint returns code 409 instead. Responses of type application/json can include payloads of up to 6Mb, all other types can return up to 4.5Mb of (compressed) data.

Authorizations:
BearerAuth
path Parameters
planID
required
string

Key returned in the 200/201 response of the POST request

header Parameters
"application/json" (string) or "application/vnd.adiutabyte.adiutaopt.json+gzip" (string) or "application/vnd.adiutabyte.adiutaopt.json+deflate" (string) or "application/vnd.adiutabyte.adiutaopt.json+br" (string)

(optional) The content-type of the response. Defaults to application/json if not set, invalid values result in status code 406.

"identity" (string) or "gzip" (string) or "deflate" (string)

(optional) The content-encode of the response. Only permitted for application/json responses.

Responses

Request samples 

curl \
  --request GET \
  --url '[see url above]/[key obtained from POST request]' \
  --header 'Authorization: Bearer [ID-Token obtained from Authentication (JWT)]'

Response samples

Content type
Example
{
  • "requestID": "string",
  • "client": {
    },
  • "meta": {
    },
  • "parameters": {
    },
  • "tasks": [
    ],
  • "workers": [
    ],
  • "statistics": {
    },
  • "info": {
    },
  • "anomalies": [
    ],
  • "backendVersion": {
    },
  • "recovery": [
    ],
  • "developerOptions": {
    }
}

Get Solution (Preflight)

path Parameters
planID
required
string

Can be anything.

Responses

Get Solution (header-only)

Same behavior as the GET request but returns no content for any of the responses.

path Parameters
planID
required
string

Key returned in the 200/201 response of the POST request

header Parameters
"application/json" (string) or "application/vnd.adiutabyte.adiutaopt.json+gzip" (string) or "application/vnd.adiutabyte.adiutaopt.json+deflate" (string) or "application/vnd.adiutabyte.adiutaopt.json+br" (string)

(optional) The content-type of the response. Defaults to application/json if not set, invalid values result in status code 406.

"identity" (string) or "gzip" (string) or "deflate" (string)

(optional) The content-encode of the response. Only permitted for application/json responses.

Version

Retrieve currently deployed version data

Get Version

Get the currently deployed version.

Responses from this endpoint have a content size limit which depends on the used content-type of the response, which can be specified with the accept header. If the response size would exceed that limit, the endpoint returns code 409 instead. Responses of type application/json can include payloads of up to 6Mb, all other types can return up to 4.5Mb of (compressed) data.

Authorizations:
BearerAuth
header Parameters
adiutaopt-version
string

(optional) A specific version to process the request under. Valid versions can be retrieved with the /packages-list endpoint (Name).

Using a specific version is not recommended for "general" application but for testing, debugging or other developer actions. Versions represent a specific state of the application, they cannot be changed, bug-fixed or extended in any way. For that reason, support for these requests may be limited.

"application/json" (string) or "application/vnd.adiutabyte.adiutaopt.json+gzip" (string) or "application/vnd.adiutabyte.adiutaopt.json+deflate" (string) or "application/vnd.adiutabyte.adiutaopt.json+br" (string)

(optional) The content-type of the response. Defaults to application/json if not set, invalid values result in status code 406.

"identity" (string) or "gzip" (string) or "deflate" (string)

(optional) The content-encode of the response. Only permitted for application/json responses.

Responses

Request samples 

curl \
  --request GET \
  --url '[see url above]' \
  --header 'Authorization: Bearer [ID-Token obtained from Authentication (JWT)]'

Response samples

Content type
{
  • "schema": "v1.7.0",
  • "version": "2024-10-01_0",
  • "meta_data": "v19",
  • "api_scripts": "v1.6.2"
}

Get Version (Preflight)

Responses

Get Version (header-only)

Same behavior as the GET request but returns no content for any of the responses.

header Parameters
adiutaopt-version
string

(optional) A specific version to process the request under. Valid versions can be retrieved with the /packages-list endpoint (Name).

Using a specific version is not recommended for "general" application but for testing, debugging or other developer actions. Versions represent a specific state of the application, they cannot be changed, bug-fixed or extended in any way. For that reason, support for these requests may be limited.

"application/json" (string) or "application/vnd.adiutabyte.adiutaopt.json+gzip" (string) or "application/vnd.adiutabyte.adiutaopt.json+deflate" (string) or "application/vnd.adiutabyte.adiutaopt.json+br" (string)

(optional) The content-type of the response. Defaults to application/json if not set, invalid values result in status code 406.

"identity" (string) or "gzip" (string) or "deflate" (string)

(optional) The content-encode of the response. Only permitted for application/json responses.

Get List of Available Packages

Get a list of all available packages. The Name of each package can be used in a POST request in header adiutaopt-version, the algorithm will then run on the specified version.

Responses from this endpoint have a content size limit which depends on the used content-type of the response, which can be specified with the accept header. If the response size would exceed that limit, the endpoint returns code 409 instead. Responses of type application/json can include payloads of up to 6Mb, all other types can return up to 4.5Mb of (compressed) data.

Authorizations:
BearerAuth
header Parameters
"application/json" (string) or "application/vnd.adiutabyte.adiutaopt.json+gzip" (string) or "application/vnd.adiutabyte.adiutaopt.json+deflate" (string) or "application/vnd.adiutabyte.adiutaopt.json+br" (string)

(optional) The content-type of the response. Defaults to application/json if not set, invalid values result in status code 406.

"identity" (string) or "gzip" (string) or "deflate" (string)

(optional) The content-encode of the response. Only permitted for application/json responses.

Responses

Request samples 

curl \
  --request GET \
  --url '[see url above]' \
  --header 'Authorization: Bearer [ID-Token obtained from Authentication (JWT)]'

Response samples

Content type
[
  • {
    },
  • {
    }
]

Get List of Available Packages (Preflight)

Responses

Get List of Available Packages (header-only)

Same behavior as the GET request but returns no content for any of the responses.

header Parameters
"application/json" (string) or "application/vnd.adiutabyte.adiutaopt.json+gzip" (string) or "application/vnd.adiutabyte.adiutaopt.json+deflate" (string) or "application/vnd.adiutabyte.adiutaopt.json+br" (string)

(optional) The content-type of the response. Defaults to application/json if not set, invalid values result in status code 406.

"identity" (string) or "gzip" (string) or "deflate" (string)

(optional) The content-encode of the response. Only permitted for application/json responses.

Error IDs

Error ID data is available only on PROD/DEV/EXP documentation.

Index

List of all schema definitions

Date

string (Date) ^[0-9]{4}-(0?[1-9]|1[0-2])-(0?[1-9]|[1-2][0-9...

A string consisting of three parts following the pattern "YYYY-MM-DD":

  • "YYYY" year AD: 0-9999
  • "MM" month: 1-12
  • "DD" day: 1-31

While the schema does not check for validity, the optimization algorithms do. Including invalid dates (e.g. 2020-02-31) leads to a validation error.

Examples:

  • "2020-04-10"
  • "2051-4-1"
  • "1953-04-10"
"2020-04-10"

Number_u64

number (Number_u64) [ 0 .. 1.7e+308 ]

Unsigned 64bit number with the upper limit of a signed 64bit number

1.7e+308

Language Type

integer (Language Type) [ 0 .. 1 ]

Values are:

  • 0: German
  • 1: English
1

Integer_u32

integer (Integer_u32) [ 0 .. 2147483647 ]

Unsigned 32 bit integer with the upper limit of a signed 32bit integer

2147483647

IDReferences

Array
integer (Integer_u32) [ 0 .. 2147483647 ]

Unsigned 32 bit integer with the upper limit of a signed 32bit integer

[
  • 2147483647
]

Integer_u32_1

integer (Integer_u32_1) [ 1 .. 2147483647 ]

Unsigned 32 bit integer (not zero) with the upper limit of a signed 32bit integer

1

ShiftPlannerMeta

dateFrom
required
string (Date) ^[0-9]{4}-(0?[1-9]|1[0-2])-(0?[1-9]|[1-2][0-9...

Planning horizon start.

dateTo
required
string (Date) ^[0-9]{4}-(0?[1-9]|1[0-2])-(0?[1-9]|[1-2][0-9...

Planning horizon end.

resCategory
boolean
Default: false

Activate/Deactivate whether category types should be considered in the optimization.

resQualification
boolean
Default: false

Activate/Deactivate whether qualifications should be considered in the optimization.

accuracyMode
number (Number_u64) [ 0 .. 1.7e+308 ]
Default: 1

Manages a solution refinement process. An accuracy > 0.0 can improve the solution significantly but will take longer to calculate, effects increase with higher accuracyMode.

outputLanguage
integer (LanguageType) [ 0 .. 1 ]
Default: 0

Defines which language should be used in the output.

minQualificationOfTaskCoverage
integer (Integer_u32) [ 0 .. 2147483647 ]

At each minute between dateFrom at 00:00 and dateTo at 23:59 there shall be least one worker of this qualification or higher performing a task.

omnipresentCategoriesOfTaskCoverage
Array of integers (IDReferences) [ items [ 0 .. 2147483647 ] ]

For each of these categories, at each minute between dateFrom at 00:00 and dateTo at 23:59 there shall be least one worker with the category performing a task.

enablePlanSplitting
boolean
Deprecated
Default: true
allowUnassignedTasks
boolean
Default: false

If this flag is set to false, all tasks will be assigned by the algorithm (for exceptions regarding unassignable tasks, see removeInvalidTasks). If this flag is set to true, tasks can be left unassigned if the algorithm cannot find a "good fit". The likelihood of this happening can be influenced with the value of assignmentPriority on the InputTask.

removeInvalidTasks
boolean

If this flag is set to false and the input data contains tasks that cannot be assigned to any worker (e.g. no worker has a qualification high enough for the task), an ErrorPlan with a corresponding error is returned. If the flag is set to true, these tasks simply won't get assigned but the optimization will be carried out for all valid tasks.

If this field is not set, it will assume the value of allowUnassignedTasks.

followBiorhythm
boolean
Default: false

Tasks shall be spaced out so that there is at least a 24h time span between the start of consecutive tasks on the same worker.

minConcurrentSolutions
integer (Integer_u32_1) [ 1 .. 2147483647 ]
Default: 1

Number of concurrently calculated solutions. Developer feature, use at your own risk!

minTaskDuration
integer (Integer_u32) [ 0 .. 2147483647 ]
Default: 0

Minimum value for an input task's duration. Task durations with a lower value are being overwritten before the optimization. Profit calculations (e.g. costsPerMinute), coverage, etc use adjusted values.

{
  • "dateFrom": "2020-04-10",
  • "dateTo": "2020-04-10",
  • "resCategory": false,
  • "resQualification": false,
  • "accuracyMode": 1.7e+308,
  • "outputLanguage": 1,
  • "minQualificationOfTaskCoverage": 2147483647,
  • "omnipresentCategoriesOfTaskCoverage": [
    ],
  • "enablePlanSplitting": true,
  • "allowUnassignedTasks": false,
  • "removeInvalidTasks": true,
  • "followBiorhythm": false,
  • "minConcurrentSolutions": 1,
  • "minTaskDuration": 2147483647
}

ShiftPlannerOptimizationParameters

preset
integer [ 0 .. 0 ]

Sets the parameters to a predefined preset. Additionally specified parameters will override the preset parameters.

Preset descriptions:

Preset 0 (Random):

  • The value timeliness is set to a random value 1 to 9.
  • The values workerPrefs, teamPrefs, taskPrefs, workerReduction, genderPref, profitability, worktimePrefs, fairDistribution are set to a random value 0 to 9.

Preset 0 is a dummy preset that must be used for testing only and never in production environments. Due to the random nature of the preset, we are not able to provide full support for any optimization request using this preset.

fairDistribution
integer (Integer_0_9) [ 0 .. 9 ]
Default: 0

Distribute the tasks fairly among the workers. A fair distribution is one where every worker has the same number of tasks assigned.

timeliness
integer (Integer_0_9) [ 0 .. 9 ]
Default: 0

Optimize towards satisfying the time windows.

workerPrefs
integer (Integer_0_9) [ 0 .. 9 ]
Default: 0

Try to satisfy the workers' preferences.

teamPrefs
integer (Integer_0_9) [ 0 .. 9 ]
Default: 0

Try to satisfy preferences between workers.

taskPrefs
integer (Integer_0_9) [ 0 .. 9 ]
Default: 0

Try to satisfy preferences set in tasks.

worktimePrefs
integer (Integer_0_9) [ 0 .. 9 ]
Default: 0

Try to satisfy the working time restrictions specified.

workerReduction
integer (Integer_0_9) [ 0 .. 9 ]
Default: 0

Reduce the number of necessary workers by creating imbalanced schedules where as many workers as possible have as few as possible tasks.

genderPref
integer (Integer_0_9) [ 0 .. 9 ]
Default: 0

Try to satisfy any tasks' gender preferences. Setting this parameter to 9 will force the algorithm to consider prefGender a restriction rather than merely a preference. Requires genders and gender preferences to be set.

profitability
integer (Integer_0_9) [ 0 .. 9 ]
Default: 0

Optimize towards high profitability, requires costs to be set on the worker to have an effect.

{
  • "preset": 0,
  • "fairDistribution": 9,
  • "timeliness": 9,
  • "workerPrefs": 9,
  • "teamPrefs": 9,
  • "taskPrefs": 9,
  • "worktimePrefs": 9,
  • "workerReduction": 9,
  • "genderPref": 9,
  • "profitability": 9
}

Time

string (Time) ^[-]?([0-9]{1,9}):([0-5][0-9]|[0-9])$

A string of either format "hh:mm" or "-hh:mm":

  • "hh": hours (24h format),
  • "mm": minutes

Times are always interpreted relative to a date in the same object as the Time field. This allows times to exceed 24h or even become negative, as the value gets "added" to midnight of the date. For example, the following times applied to the respective date (in Date format) are equivalent:

  • "2021-05-21" at "07:25"
  • "2021-05-20" at "31:25"
  • "2021-05-19" at "55:25"
  • "2021-05-22" at "-16:35"
  • "2021-05-23" at "-40:35"
"07:25"

Integer_s32

integer (Integer_s32) [ -2147483648 .. 2147483647 ]

Signed 32 bit integer

-2147483648

Gender Type

integer (Gender Type) [ 0 .. 3 ]

Values are:

  • 0: not provided
  • 1: male
  • 2: female
  • 3: other
3

ShiftPlannerInputTask

taskID
required
integer (Integer_u32) [ 0 .. 2147483647 ]

The ID of this task. IDs need to be unique among all tasks.

externalID
string

A string to identify the task in the solution. Cannot be used for reference in the input data or the optimizer, it only serves as a helping tool for integrations.

date
required
string (Date) ^[0-9]{4}-(0?[1-9]|1[0-2])-(0?[1-9]|[1-2][0-9...

The date this task should be planned on.

duration
required
integer (Integer_u32) [ 0 .. 2147483647 ]

The time in minutes it takes to complete this task.

timeEarliest
required
string (Time) ^[-]?([0-9]{1,9}):([0-5][0-9]|[0-9])$

The earliest possible starting time of this task.

This is a preference and can be violated for other preferences or restrictions. Its importance depends on the parameter timeliness.

timeLatest
required
string (Time) ^[-]?([0-9]{1,9}):([0-5][0-9]|[0-9])$

The latest time at which this task should be finished.

This is a preference and can be violated for other preferences or restrictions. Its importance depends on the parameter timeliness.

timePriority
integer (Integer_0_5) [ 0 .. 5 ]
Default: 1

The priority of the time window:

  • 0 - irrelevant
  • 1 - not important
  • 2 - more important
  • 3 - important
  • 4 - very important
  • 5 - fixed time

Tasks with high time priority are more likely to get scheduled inside their given time window. Tasks with time priority 0 completely ignore their given time window.

For tasks with a timePriority of 3 or higher, the time window is considered a strict restriction.

prefWorkers
Array of integers (IDReferences) [ items [ 0 .. 2147483647 ] ]

The IDs of preferred workers.

This is a preference and can be violated for other preferences or restrictions. Its importance depends on the parameter taskPrefs.

forbWorkers
Array of integers (IDReferences) [ items [ 0 .. 2147483647 ] ]

The IDs of forbidden workers.

This is a strict restriction and might fail validation if it is impossible to keep.

unpreferredWorkers
Array of integers (IDReferences) [ items [ 0 .. 2147483647 ] ]

The IDs of workers to which an assignment is undesirable but not forbidden.

This is a preference and can be violated for other preferences or restrictions. Its importance depends on the parameter taskPrefs.

antiWorkers
Array of integers (IDReferences) [ items [ 0 .. 2147483647 ] ]
Deprecated

Alias for unpreferredWorkers.

qualification
integer (Integer_u32) [ 0 .. 2147483647 ]

The minimum qualification of the worker required to perform the task (e.g. years of experience). Workers without qualification are not allowed to perform tasks of any qualification.

This is a strict restriction and might fail validation if it is impossible to keep.

maxQualification
integer (Integer_u32) [ 0 .. 2147483647 ]

The maximum qualification of the worker allowed to perform the task. Workers without qualification can carry out any task with qualification (as long as the other restrictions are not violated).

This is a strict restriction and might fail validation if it is impossible to keep.

categories
Array of integers (IDReferences) [ items [ 0 .. 2147483647 ] ]

A suitable worker has to fulfill all of these categories.

This is a strict restriction and might fail validation if it is impossible to keep.

exchangeableCategories
Array of integers (IDReferences) [ items [ 0 .. 2147483647 ] ]

A suitable worker has to fulfill at least one of these categories.

This is a strict restriction and might fail validation if it is impossible to keep.

preassignedWorker
integer (Integer_u32) [ 0 .. 2147483647 ]

The workerID of the only worker that is allowed to carry out the task. This setting overrules any other strict restriction - for example, if the worker does not fulfil the qualification requirement, the task will still get assigned to them. The field can also be used for dontVary assignments. A preassignedWorker does not imply an assignmentPriority - if allowUnassignedTasks is active, the task being unassigned is not a violation of this restriction.

This is a strict restriction and might fail validation if it is impossible to keep.

preassignedOrder
integer (Integer_s32) [ -2147483648 .. 2147483647 ]

Tasks with a value > 0 will be assigned as the first tasks of the preassignedWorker, tasks with a value < 0 as their last. If multiple tasks preassigned to a worker have a preassignedOrder, the tasks will be sorted so that the preassignedOrder is increasing.

This is a strict restriction and might fail validation if it is impossible to keep.

desiredWorker
integer (Integer_u32) [ 0 .. 2147483647 ]

The ID of the worker who is desired (strong preference) to take over this task.

This is a preference and can be violated for other preferences or restrictions.

prefGender
integer (GenderType) [ 0 .. 3 ]

The preferred gender for the assigned worker.

This usually is a preference and can be violated for other preferences or restrictions. Its importance depends on the parameter genderPrefs. If the parameter has the maximum value, it is considered a weak restriction instead and will be considered only if it is possible to keep it. It will not fail the validation if it is impossible to keep it.

precedingTasks
Array of integers (IDReferences) [ items [ 0 .. 2147483647 ] ]

Tasks in this list and this task will be performed by the same worker and all listed tasks will have to be finished before this task starts.

This is a strict restriction and might fail validation if it is impossible to keep.

predecessorTasks
Array of integers (IDReferences) [ items [ 0 .. 2147483647 ] ]

One of these tasks has be carried out right before this task by the same worker. Putting multiple values in the array does not mean they are carried out in that order - if you want to have a predecessor-chain, you need to set the direct predecessor on each task in the chain (see examples). Do not put redundant values in here, as having more than one value in the array has negative impact on performance and solution quality.

This is a strict restriction and might fail validation if it is impossible to keep.

group
integer (Integer_u32) [ 0 .. 2147483647 ]

A group ID. Tasks with the same group get assigned to the same worker.

This is a strict restriction and might fail validation if it is impossible to keep.

groupOrder
integer (Integer_u32) [ 0 .. 2147483647 ]
Deprecated

Unsigned 32 bit integer with the upper limit of a signed 32bit integer

revenue
number (Number_u64) [ 0 .. 1.7e+308 ]
Default: 0

The revenue which will be achieved with this task.

initassignedShift
integer (Integer_u32) [ 0 .. 2147483647 ]
Deprecated

Unsigned 32 bit integer with the upper limit of a signed 32bit integer

assignmentPriority
integer (Integer_0_5) [ 0 .. 5 ]
Default: 1

A priority for assignment (see allowUnassignedTasks):.

  • 0 - no preference regarding unassignment, whether or not the task is assigned does not matter and will depend solely on other factors
  • 1-4 - progressively higher assignment importance
  • 5 - task has to be assigned

If allowUnassignedTasks is set to false, this field has no effect.

For tasks with an assignmentPriority of 5, the task being assigned is considered a strict restriction.

initassignedWorker
integer (Integer_u32) [ 0 .. 2147483647 ]

A hint for large optimization data sets, e.g. solution data from a previous optimization request. The field can also be used for dontVary assignments.

initassignedOrder
integer (Integer_u32) [ 0 .. 2147483647 ]

Requires preassignedWorker or initassignedWorker. The order within the initially assigned worker's tour.

{
  • "taskID": 2147483647,
  • "externalID": "string",
  • "date": "2020-04-10",
  • "duration": 2147483647,
  • "timeEarliest": "07:25",
  • "timeLatest": "07:25",
  • "timePriority": 5,
  • "prefWorkers": [
    ],
  • "forbWorkers": [
    ],
  • "unpreferredWorkers": [
    ],
  • "antiWorkers": [
    ],
  • "qualification": 2147483647,
  • "maxQualification": 2147483647,
  • "categories": [
    ],
  • "exchangeableCategories": [
    ],
  • "preassignedWorker": 2147483647,
  • "preassignedOrder": -2147483648,
  • "desiredWorker": 2147483647,
  • "prefGender": 3,
  • "precedingTasks": [
    ],
  • "predecessorTasks": [
    ],
  • "group": 2147483647,
  • "groupOrder": 2147483647,
  • "revenue": 1.7e+308,
  • "initassignedShift": 2147483647,
  • "assignmentPriority": 5,
  • "initassignedWorker": 2147483647,
  • "initassignedOrder": 2147483647
}

ShiftPlannerShift

shiftID
integer (Integer_u32) [ 0 .. 2147483647 ]
Deprecated

Unsigned 32 bit integer with the upper limit of a signed 32bit integer

shiftDate
required
string (Date) ^[0-9]{4}-(0?[1-9]|1[0-2])-(0?[1-9]|[1-2][0-9...

The date this time slot is available on.

shiftStart
required
string (Time) ^[-]?([0-9]{1,9}):([0-5][0-9]|[0-9])$

The time this time slot starts.

shiftEnd
required
string (Time) ^[-]?([0-9]{1,9}):([0-5][0-9]|[0-9])$

The time this time slot ends.

shiftPriority
integer (Integer_0_3) [ 0 .. 3 ]
Default: 1

The priority to assign tasks within the defined shift start/end times.

  • 0: irrelevant
  • 1: neutral
  • 2: important
  • 3: very important.
{
  • "shiftID": 2147483647,
  • "shiftDate": "2020-04-10",
  • "shiftStart": "07:25",
  • "shiftEnd": "07:25",
  • "shiftPriority": 3
}

Overlap Config Type

integer (Overlap Config Type) [ 0 .. 0 ]

Set preferences regarding overlap

  • 0 - Prefer the time slot being covered by a task
0
0

TimeSlot

date
required
string (Date) ^[0-9]{4}-(0?[1-9]|1[0-2])-(0?[1-9]|[1-2][0-9...

The date this time slot is available on.

start
required
string (Time) ^[-]?([0-9]{1,9}):([0-5][0-9]|[0-9])$

The time this time slot starts.

end
required
string (Time) ^[-]?([0-9]{1,9}):([0-5][0-9]|[0-9])$

The time this time slot ends.

overlapConfig
integer (OverlapConfigType) [ 0 .. 0 ]

Modify preferences regarding this slot being overlapped by a task.

{
  • "date": "2020-04-10",
  • "start": "07:25",
  • "end": "07:25",
  • "overlapConfig": 0
}

ShiftPlannerInputWorker

workerID
required
integer (Integer_u32) [ 0 .. 2147483647 ]

The ID of the worker. Needs to be unique among all workers.

externalID
string

A string to identify the worker in the solution. Cannot be used for reference in the input data or the optimizer, it only serves as a helping tool for integrations.

Array of objects (ShiftPlannerShift)

The time slots during which the worker can carry out tasks.

qualification
integer (Integer_u32) [ 0 .. 2147483647 ]

The qualification of the worker. They are able to take over tasks with the same or lower qualifications.

categories
Array of integers (IDReferences) [ items [ 0 .. 2147483647 ] ]

The worker can only carry out tasks if he has each category the task requires.

desiredCategory
integer (Integer_u32) [ 0 .. 2147483647 ]

The worker has a strong preference towards tasks with this category. The value already counts as a category and does not need to be included in categories.

This is a preference and can be violated for other preferences or restrictions.

prefCategories
Array of integers (IDReferences) [ items [ 0 .. 2147483647 ] ]

The task categories preferred by the worker. Values already count as a categories and do not need to be included in categories.

This is a preference and can be violated for other preferences or restrictions. Its importance depends on the parameter workerPrefs.

prefWeekCategories
Array of integers (IDReferences) [ items [ 0 .. 2147483647 ] ]

The task categories preferred by the worker on any week day (Mon-Fri). Values already count as a categories and do not need to be included in categories.

This is a preference and can be violated for other preferences or restrictions. Its importance depends on the parameter workerPrefs.

prefWeekendCategories
Array of integers (IDReferences) [ items [ 0 .. 2147483647 ] ]

The task categories preferred by the worker on any weekend day (Sat, Sun). Values already count as a categories and do not need to be included in categories.

This is a preference and can be violated for other preferences or restrictions. Its importance depends on the parameter workerPrefs.

prefWorkers
Array of integers (IDReferences) [ items [ 0 .. 2147483647 ] ]

The workers that this worker prefers to have simultaneous shifts with.

This is a preference and can be violated for other preferences or restrictions. Its importance depends on the parameter teamPrefs.

unpreferredWorkers
Array of integers (IDReferences) [ items [ 0 .. 2147483647 ] ]

The workers that this worker prefers to not have simultaneous shifts with.

This is a preference and can be violated for other preferences or restrictions. Its importance depends on the parameter teamPrefs.

antiWorkers
Array of integers (IDReferences) [ items [ 0 .. 2147483647 ] ]
Deprecated

Alias for unpreferredWorkers.

gender
integer (GenderType) [ 0 .. 3 ]

The gender type of the worker.

expectedWorkingMinutes
integer (Integer_u32) [ 0 .. 2147483647 ]

The preferred amount of working time minutes for this worker in the final plan, deviation in both directions will be kept as low as possible.

This is a preference and can be violated for other preferences or restrictions. Its importance depends on the parameter worktimePrefs.

minWorkingMinutes
integer (Integer_u32) [ 0 .. 2147483647 ]
Default: 0

The minimum amount of working time minutes for this worker in the final plan.

This is a preference and can be violated for other preferences or restrictions.

maxWorkingMinutes
integer (Integer_u32) [ 0 .. 2147483647 ]

The maximum amount of working time minutes for this worker in the final plan.

This is a preference and can be violated for other preferences or restrictions.

maxConsecutiveWorkdays
integer (Integer_u32) [ 0 .. 2147483647 ]

Maximum number of consecutive workdays. A day is a workday if any work is performed from 00:00 to 23:59.

This is a preference and can be violated for other preferences or restrictions.

minConsecutiveWorkdays
integer (Integer_u32) [ 0 .. 2147483647 ]
Default: 0

Minimum number of consecutive workdays. A day is a workday if any work is performed from 00:00 to 23:59.

This is a preference and can be violated for other preferences or restrictions.

prefConsecutiveWorkdays
integer (Integer_u32) [ 0 .. 2147483647 ]

The preferred number of working days in a row.

This is a preference and can be violated for other preferences or restrictions. Its importance depends on the parameter workerPrefs.

carryoverConsecutiveWorkdays
integer (Integer_u32) [ 0 .. 2147483647 ]

Can not be used with carryoverConsecutiveOffdays. The current number of consecutive workdays at the start of the plan.

maxConsecutiveOffdays
integer (Integer_u32) [ 0 .. 2147483647 ]

Maximum number of consecutive days off. A day counts as a "day off" if no work is performed from 00:00 to 23:59.

This is a preference and can be violated for other preferences or restrictions.

minConsecutiveOffdays
integer (Integer_u32) [ 0 .. 2147483647 ]
Default: 0

Minimum number of consecutive days off. A day counts as a "day off" if no work is performed from 00:00 to 23:59.

This is a preference and can be violated for other preferences or restrictions.

prefConsecutiveOffdays
integer (Integer_u32) [ 0 .. 2147483647 ]

The preferred number of non-working days in a row.

This is a preference and can be violated for other preferences or restrictions. Its importance depends on the parameter workerPrefs.

carryoverConsecutiveOffdays
integer (Integer_u32) [ 0 .. 2147483647 ]

Can not be used with carryoverConsecutiveWorkdays. The current number of consecutive days off at the start of the plan.

minBreakMinutesBetweenTasks
integer (Integer_u32) [ 0 .. 2147483647 ]
Default: 0

Minimum number of minutes break between two Tasks that start on different days.

This is a strict restriction and might fail validation if it is impossible to keep.

maxDailyWorkingMinutes
integer (Integer_u32) [ 0 .. 2147483647 ]

Maximum number of working minutes per day.

This is a preference and can be violated for other preferences or restrictions.

maxDailyTasks
integer (Integer_u32) [ 0 .. 2147483647 ]

Maximum number of tasks per day. Tasks count towards the day they start in. "Predecessor-Chains" (sets of tasks linked to a "chain" by predecessorTasks) count as one task for this limit.

This is a strict restriction and might fail validation if it is impossible to keep.

minFreeSaturdays
integer (Integer_u32) [ 0 .. 2147483647 ]
Default: 0

Minimum number of work-free Saturdays for this worker.

This is a strict restriction and might fail validation if it is impossible to keep.

minFreeSundays
integer (Integer_u32) [ 0 .. 2147483647 ]
Default: 0

Minimum number of work-free Sundays for this worker.

This is a strict restriction and might fail validation if it is impossible to keep.

maxWeeklyWorkingMinutes
integer (Integer_u32) [ 0 .. 2147483647 ]

Maximum minutes working time for this worker each calendar week (Monday to Sunday). Please note that the week cycle might be independent from the planning horizon, use carryoverWorkingMinutesLastWeek in conflicting cases.

This is a preference and can be violated for other preferences or restrictions.

carryoverWorkingMinutesLastWeek
integer (Integer_u32) [ 0 .. 2147483647 ]

Minutes of worktime already performed by this worker in the week that dateFrom belongs to. The value is factored in by maxWeeklyWorkingMinutes and maxTwoWeekWorkingMinutes but not expectedWorkingMinutes!

maxTwoWeekWorkingMinutes
integer (Integer_u32) [ 0 .. 2147483647 ]

Maximum minutes working time for this worker for every two consecutive calendar weeks (Monday to Sunday). Please note that the week cycle is independent from the planning horizon, use carryoverWorkingMinutesLastWeek and carryoverWorkingMinutesSecondLastWeek in conflicting cases.

This is a preference and can be violated for other preferences or restrictions.

carryoverWorkingMinutesSecondLastWeek
integer (Integer_u32) [ 0 .. 2147483647 ]

Minutes of worktime already performed by this worker in the week prior to the earliest shiftStart (pre v3.8.12)/ dateFrom (v3.8.12) of any Worker in this plan. The value is factored in by maxWeeklyWorkingMinutes and maxTwoWeekWorkingMinutes but not expectedWorkingMinutes!

dontVary
boolean

A worker with dontVary set to true is "fixed" for the optimizer, meaning they get assigned all tasks (and only those tasks) that have this worker set as preassignedWorker or initassignedWorker in the order of initassignedOrder. That also means that initassignedOrder is required for these tasks. All output information still gets calculated on both worker and task, and the worker and its tasks will be considered in statistics and info.

This is a strict restriction and might fail validation if it is impossible to keep.

dontAlter
boolean
Default: false

Workers with dontAlter set to true behave similarly to workers with dontVary. The only difference is that a dontVary-worker cannot get assigned more tasks than specified in the input data, a dontAlter-worker will be assigned all tasks that have this worker as initassignedWorker or preassignedWorker, but can also have other tasks assigned. While the preassigned/initassigned tasks will be in order of initassignedOrder, other tasks can be inserted before, between or after those tasks; if there is no initassignedOrder set, the task will be ignored. Every other behavior and requirement is exactly as in dontVary.

This is a strict restriction and might fail validation if it is impossible to keep.

allowPreassignedTasksOnly
boolean
Default: false

If this flag is true, only tasks preassigned to this worker can be assigned to it. Tasks not preassigned to this worker cannot be assigned to it.

This is a strict restriction and might fail validation if it is impossible to keep.

costsPerMinute
number (Number_u64) [ 0 .. 1.7e+308 ]
Default: 0

The costs per minute working time (carrying out tasks) for this worker (e.g. monthly salary converted to minutes).

costsInitial
number (Number_u64) [ 0 .. 1.7e+308 ]
Default: 0

Costs that occur if there is at least one task assigned to the worker.

precTaskDate
string (Date) ^[0-9]{4}-(0?[1-9]|1[0-2])-(0?[1-9]|[1-2][0-9...

Date of the last task the worker carried out before the start of this plan.

precTaskScheduled
string (Time) ^[-]?([0-9]{1,9}):([0-5][0-9]|[0-9])$

Scheduled time of the last task the worker carried out before the start of this plan.

precTaskDuration
integer (Integer_u32) [ 0 .. 2147483647 ]

Duration of the last task the worker carried out before the start of this plan.

precNightShifts
integer (Integer_u32) [ 0 .. 2147483647 ]

Amount of consecutive "night shifts" the worker carried out directly before the start of this plan. Those are tasks that are scheduled in a way that they overlap with midnight. For more details see below.

maxOrderedGroups
integer (Integer_u32) [ 0 .. 2147483647 ]

The maximum number of task sets with same group and set group order that can be assigned to this worker.

maxDesiredOrderedGroups
integer (Integer_u32) [ 0 .. 2147483647 ]

A preference for the maximum number of task sets with same group and set group order that can be assigned to this worker.

This is a strict restriction and might fail validation if it is impossible to keep.

maxNightShifts
integer (Integer_u32) [ 0 .. 2147483647 ]

The maximum number of "night shifts" this worker can get assigned.

This is a strict restriction and might fail validation if it is impossible to keep.

maxDesiredNightShifts
integer (Integer_u32) [ 0 .. 2147483647 ]

A preference for the maximum number of "night shifts" this worker can get assigned.

This is a preference and can be violated for other preferences or restrictions.

minFreeWeekends
integer (Integer_u32) [ 0 .. 2147483647 ]
Default: 0

The minimum number of completely free weekends with no work on either Saturday or Sunday.

This is a strict restriction and might fail validation if it is impossible to keep.

minDesiredFreeWeekends
integer (Integer_u32) [ 0 .. 2147483647 ]
Default: 0

A preference for the minimum number of completely free weekends with no work on either Saturday or Sunday.

This is a preference and can be violated for other preferences or restrictions.

maxConsecutiveSameTaskStart
integer (Integer_u32) [ 0 .. 2147483647 ]

Can not be used with maxDesiredConsecutiveSameTaskStart. The maximum number of assigned consecutive tasks with a timeScheduled difference of at most 120 min.

This is a strict restriction and might fail validation if it is impossible to keep.

maxDesiredConsecutiveSameTaskStart
integer (Integer_u32) [ 0 .. 2147483647 ]

Can not be used with maxConsecutiveSameTaskStart. A desired maximum number of assigned consecutive tasks with a timeScheduled difference of at most 120 min.

This is a preference and can be violated for other preferences or restrictions.

maxWeeklyWorkingDays
integer (Integer_u32) [ 0 .. 2147483647 ]

The maximum number of tasks in one week. Tasks only count for the week they start in (timeScheduled).

This is a strict restriction and might fail validation if it is impossible to keep.

prefWeeklyWorkingDays
integer (Integer_u32) [ 0 .. 2147483647 ]

The preferred maximum number of tasks in one week. Tasks only count for the week they start in (timeScheduled).

This is a preference and can be violated for other preferences or restrictions.

carryoverWorkingDaysLastWeek
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of already carried-out workdays in the week that dateFrom belongs to.

minConsecutiveFreeWeekends
integer (Integer_u32) [ 0 .. 2147483647 ]
Default: 0

The minimum amount of consecutive weekends without any tasks assigned (task starting on either Saturday or Sunday). This restriction does not apply to the end of the planning horizon, there may be less free weekends than set here right before dateTo.

This is a strict restriction and might fail validation if it is impossible to keep.

minDesiredConsecutiveFreeWeekends
integer (Integer_u32) [ 0 .. 2147483647 ]
Default: 0

The desired minimum amount of consecutive weekends without any tasks assigned (task starting on either Saturday or Sunday). This restriction does not apply to the end of the planning horizon, there may be less free weekends than set here right before dateTo.

This is a preference and can be violated for other preferences or restrictions.

maxConsecutiveFreeWeekends
integer (Integer_u32) [ 0 .. 2147483647 ]

The maximum amount of consecutive weekends without any tasks assigned (task starting on either Saturday or Sunday).

This is a strict restriction and might fail validation if it is impossible to keep.

maxDesiredConsecutiveFreeWeekends
integer (Integer_u32) [ 0 .. 2147483647 ]

The desired maximum amount of consecutive weekends without any tasks assigned (task starting on either Saturday or Sunday).

This is a preference and can be violated for other preferences or restrictions.

minConsecutiveWorkingWeekends
integer (Integer_u32) [ 0 .. 2147483647 ]
Default: 0

The minimum amount of consecutive weekends with at least one task assigned (task starting on either Saturday or Sunday).

This is a strict restriction and might fail validation if it is impossible to keep.

minDesiredConsecutiveWorkingWeekends
integer (Integer_u32) [ 0 .. 2147483647 ]
Default: 0

The desired minimum amount of consecutive weekends with at least one task assigned (task starting on either Saturday or Sunday).

This is a preference and can be violated for other preferences or restrictions.

maxConsecutiveWorkingWeekends
integer (Integer_u32) [ 0 .. 2147483647 ]

The maximum amount of consecutive weekends with at least one task assigned (task starting on either Saturday or Sunday).

This is a strict restriction and might fail validation if it is impossible to keep.

maxDesiredConsecutiveWorkingWeekends
integer (Integer_u32) [ 0 .. 2147483647 ]

The desired maximum amount of consecutive weekends with at least one task assigned (task starting on either Saturday or Sunday).

This is a preference and can be violated for other preferences or restrictions.

precWeekendWorkingDay
string (Date) ^[0-9]{4}-(0?[1-9]|1[0-2])-(0?[1-9]|[1-2][0-9...

The latest working day on a weekend before dateFrom.

carryoverConsecutiveWorkingWeekends
integer (Integer_u32) [ 0 .. 2147483647 ]

The amount of consecutive weekends with at least one task performed on either Saturday or Sunday on and before the first complete weekend before dateFrom. See below for explanations.

consecutiveNightShiftsForOffdays
integer (Integer_u32) [ 0 .. 2147483647 ]

After a night shift streak consisting of this or more night shifts, there have to be a number of days off (number of days is defined in minOffdaysAfterConsecutiveNightShifts). This also means that it is disallowed to have a non-night-shift directly after a night shift.

minOffdaysAfterConsecutiveNightShifts
integer (Integer_u32) [ 0 .. 2147483647 ]
Default: 0

The number of days off after a corresponding trigger.

This is a strict restriction and might fail validation if it is impossible to keep.

workdayPattern
Array of integers (Integer_u32_1) >= 2 items [ items [ 1 .. 2147483647 ] ]

This field can be used to define irregular workday patterns. There must be an even number of entries, where each even numbered entry (starting at zero) is the number of workdays and each odd numbered entry the number of days off.

Example: The array [1, 2, 4, 1] means the worker shall work (exactly) one day, then have two days off, then work four days, then have one day off. Then start over at the beginning.

If no history data is provided, the rhythm will start on dateFrom. If there is history data, the algorithm finds a day the previous iteration most likely ended and starts the rhythm from there.

This is a preference and can be violated for other preferences or restrictions.

object

Define workday restrictions for a smaller periods of time (e.g. 7 days, 14 days) than the whole plan. Those cycles loop until dateTo.

If no history data is provided, the first cycle will start on dateFrom. If there is history data, the algorithm finds a day the previous iteration most likely ended and starts the first cycle from there.

Array of objects (TimeSlot)

The worker will definitely work during the time slots specified here. Tasks can overlap the time slots, in which case they get "merged" onto the overlapping task. If the time slot does not get overlapped, it counts as a regular task. Time slots may not overlap each other.

preventSplitWeekends
boolean
Default: false

If true, the algorithm will avoid scheduling tasks on only one day of the weekend - this worker should be working either on both days or none. This is a preference and can be violated for other preferences or restrictions.

{
  • "workerID": 2147483647,
  • "externalID": "string",
  • "shifts": [
    ],
  • "qualification": 2147483647,
  • "categories": [
    ],
  • "desiredCategory": 2147483647,
  • "prefCategories": [
    ],
  • "prefWeekCategories": [
    ],
  • "prefWeekendCategories": [
    ],
  • "prefWorkers": [
    ],
  • "unpreferredWorkers": [
    ],
  • "antiWorkers": [
    ],
  • "gender": 3,
  • "expectedWorkingMinutes": 2147483647,
  • "minWorkingMinutes": 2147483647,
  • "maxWorkingMinutes": 2147483647,
  • "maxConsecutiveWorkdays": 2147483647,
  • "minConsecutiveWorkdays": 2147483647,
  • "prefConsecutiveWorkdays": 2147483647,
  • "carryoverConsecutiveWorkdays": 2147483647,
  • "maxConsecutiveOffdays": 2147483647,
  • "minConsecutiveOffdays": 2147483647,
  • "prefConsecutiveOffdays": 2147483647,
  • "carryoverConsecutiveOffdays": 2147483647,
  • "minBreakMinutesBetweenTasks": 2147483647,
  • "maxDailyWorkingMinutes": 2147483647,
  • "maxDailyTasks": 2147483647,
  • "minFreeSaturdays": 2147483647,
  • "minFreeSundays": 2147483647,
  • "maxWeeklyWorkingMinutes": 2147483647,
  • "carryoverWorkingMinutesLastWeek": 2147483647,
  • "maxTwoWeekWorkingMinutes": 2147483647,
  • "carryoverWorkingMinutesSecondLastWeek": 2147483647,
  • "dontVary": true,
  • "dontAlter": false,
  • "allowPreassignedTasksOnly": false,
  • "costsPerMinute": 1.7e+308,
  • "costsInitial": 1.7e+308,
  • "precTaskDate": "2020-04-10",
  • "precTaskScheduled": "07:25",
  • "precTaskDuration": 2147483647,
  • "precNightShifts": 2147483647,
  • "maxOrderedGroups": 2147483647,
  • "maxDesiredOrderedGroups": 2147483647,
  • "maxNightShifts": 2147483647,
  • "maxDesiredNightShifts": 2147483647,
  • "minFreeWeekends": 2147483647,
  • "minDesiredFreeWeekends": 2147483647,
  • "maxConsecutiveSameTaskStart": 2147483647,
  • "maxDesiredConsecutiveSameTaskStart": 2147483647,
  • "maxWeeklyWorkingDays": 2147483647,
  • "prefWeeklyWorkingDays": 2147483647,
  • "carryoverWorkingDaysLastWeek": 2147483647,
  • "minConsecutiveFreeWeekends": 2147483647,
  • "minDesiredConsecutiveFreeWeekends": 2147483647,
  • "maxConsecutiveFreeWeekends": 2147483647,
  • "maxDesiredConsecutiveFreeWeekends": 2147483647,
  • "minConsecutiveWorkingWeekends": 2147483647,
  • "minDesiredConsecutiveWorkingWeekends": 2147483647,
  • "maxConsecutiveWorkingWeekends": 2147483647,
  • "maxDesiredConsecutiveWorkingWeekends": 2147483647,
  • "precWeekendWorkingDay": "2020-04-10",
  • "carryoverConsecutiveWorkingWeekends": 2147483647,
  • "consecutiveNightShiftsForOffdays": 2147483647,
  • "minOffdaysAfterConsecutiveNightShifts": 2147483647,
  • "workdayPattern": [
    ],
  • "workdayCycle": {
    },
  • "fixedPresences": [
    ],
  • "preventSplitWeekends": false
}

ShiftPlannerHistoryAssignment

date
required
string (Date) ^[0-9]{4}-(0?[1-9]|1[0-2])-(0?[1-9]|[1-2][0-9...

The date of the assignment.

assignedWorker
integer (Integer_u32) [ 0 .. 2147483647 ]

The worker (workerID) the corresponding task was assigned to in the final planned version.

assignedWorkerAutomatically
integer (Integer_u32) [ 0 .. 2147483647 ]

The worker the corresponding task was assigned to by the optimizer at the time.

actualWorker
integer (Integer_u32) [ 0 .. 2147483647 ]

The worker the task was actually carried out by, for instance as determined by mobile tracking.

actualStartTime
string (Time) ^[-]?([0-9]{1,9}):([0-5][0-9]|[0-9])$

The time the task was actually started, for instance as determined by mobile tracking.

{
  • "date": "2020-04-10",
  • "assignedWorker": 2147483647,
  • "assignedWorkerAutomatically": 2147483647,
  • "actualWorker": 2147483647,
  • "actualStartTime": "07:25"
}

ShiftPlannerHistoryTask

taskID
required
integer (Integer_u32) [ 0 .. 2147483647 ]

The ID of this task, unique among all history tasks. Has to correspond to a taskID of an input task in either the request or additionalTasks.

required
Array of objects (ShiftPlannerHistoryAssignment)

All historical assignments of this task.

{
  • "taskID": 2147483647,
  • "scheduling": [
    ]
}

ShiftPlannerHistoryWorker

workerID
required
integer (Integer_u32) [ 0 .. 2147483647 ]

The ID of this worker, unique among all history workers. Has to correspond to a workerID of an input worker in the request.

excludedDays
Array of strings (Date) [ items^[0-9]{4}-(0?[1-9]|1[0-2])-(0?[1-9]|[1-2][0-9... ]

Dates that should be disregarded for historical analysis (e.g. sick days, schooling, ...).

preferenceFulfilledOn
Array of strings (Date) [ items^[0-9]{4}-(0?[1-9]|1[0-2])-(0?[1-9]|[1-2][0-9... ]

Days on which a preference was fulfilled.

preferenceNotFulfilledOn
Array of strings (Date) [ items^[0-9]{4}-(0?[1-9]|1[0-2])-(0?[1-9]|[1-2][0-9... ]

Days on which a preference was not fulfilled.

{
  • "workerID": 2147483647,
  • "excludedDays": [
    ],
  • "preferenceFulfilledOn": [
    ],
  • "preferenceNotFulfilledOn": [
    ]
}

ShiftPlannerHistory

required
Array of objects (ShiftPlannerHistoryTask)

All historical task data.

required
Array of objects (ShiftPlannerHistoryWorker)

Historical worker data.

Array of objects (ShiftPlannerInputTask)

All tasks that are relevant for the analysis but are not part of the optimization.

{
  • "tasks": [
    ],
  • "workers": [
    ],
  • "additionalTasks": [
    ]
}

DeveloperOptions

recovery
Array of integers (IDReferences) [ items [ 0 .. 2147483647 ] ]

[developer feature] Contains recovery data that can be used to reproduce timeout behaviour.

debugSolution
string

[developer feature] Contains data for (re-)producing specific solutions.

{
  • "recovery": [
    ],
  • "debugSolution": "string"
}

ShiftPlannerInputPlan

object (Client)

Contains information about the client which sends this request.

required
object (ShiftPlannerMeta)

Meta information about what to consider in the optimization.

required
object (ShiftPlannerOptimizationParameters)

Parameters for the optimizer.

required
Array of objects (ShiftPlannerInputTask)

Array of Tasks to be planned by the optimizer.

required
Array of objects (ShiftPlannerInputWorker)

Array of available Workers.

object (ShiftPlannerHistory)

History data the optimizer can learn from to apply to the current request. History analysis is done differently for each of our customers, if you know what issues you want to address/ what results you want to see from such methods, please contact us so we can set up a solution.

recovery
Array of integers (IDReferences) [ items [ 0 .. 2147483647 ] ]
Deprecated

List of ids.

object (DeveloperOptions)

Options for developers. Do not use!

{
  • "client": {
    },
  • "meta": {
    },
  • "parameters": {
    },
  • "tasks": [
    ],
  • "workers": [
    ],
  • "history": {
    },
  • "recovery": [
    ],
  • "developerOptions": {
    }
}

AjvError

keyword
required
string

Validation keyword.

instancePath
required
string

JSON Pointer to the location in the data instance (e.g., "/prop/1/subProp").

schemaPath
required
string

JSON Pointer to the location of the failing keyword in the schema

params
required
object

Params property is the object with the additional information about error. It can be used to generate error messages (e.g., using ajv-i18n package).

propertyName
string

Set for errors in propertyNames keyword schema. instancePath still points to the object in this case.

message
string

The error message.

schema
any

The value of the failing keyword in the schema.

parentSchema
object

The schema containing the keyword.

data
any

The data validated by the keyword.

{
  • "keyword": "string",
  • "instancePath": "string",
  • "schemaPath": "string",
  • "params": { },
  • "propertyName": "string",
  • "message": "string",
  • "schema": null,
  • "parentSchema": { },
  • "data": null
}

Number_s64

number (Number_s64) [ -1.7e+308 .. 1.7e+308 ]

Signed 64bit number

-1.7e+308

ShiftPlannerOutputTaskAssigned

taskID
required
integer (Integer_u32) [ 0 .. 2147483647 ]

The ID of this task. IDs need to be unique among all tasks.

externalID
string

A string to identify the task in the solution. Cannot be used for reference in the input data or the optimizer, it only serves as a helping tool for integrations.

date
required
string (Date) ^[0-9]{4}-(0?[1-9]|1[0-2])-(0?[1-9]|[1-2][0-9...

The date this task should be planned on.

duration
required
integer (Integer_u32) [ 0 .. 2147483647 ]

The time in minutes it takes to complete this task.

timeEarliest
required
string (Time) ^[-]?([0-9]{1,9}):([0-5][0-9]|[0-9])$

The earliest possible starting time of this task.

This is a preference and can be violated for other preferences or restrictions. Its importance depends on the parameter timeliness.

timeLatest
required
string (Time) ^[-]?([0-9]{1,9}):([0-5][0-9]|[0-9])$

The latest time at which this task should be finished.

This is a preference and can be violated for other preferences or restrictions. Its importance depends on the parameter timeliness.

timePriority
integer (Integer_0_5) [ 0 .. 5 ]
Default: 1

The priority of the time window:

  • 0 - irrelevant
  • 1 - not important
  • 2 - more important
  • 3 - important
  • 4 - very important
  • 5 - fixed time

Tasks with high time priority are more likely to get scheduled inside their given time window. Tasks with time priority 0 completely ignore their given time window.

For tasks with a timePriority of 3 or higher, the time window is considered a strict restriction.

prefWorkers
Array of integers (IDReferences) [ items [ 0 .. 2147483647 ] ]

The IDs of preferred workers.

This is a preference and can be violated for other preferences or restrictions. Its importance depends on the parameter taskPrefs.

forbWorkers
Array of integers (IDReferences) [ items [ 0 .. 2147483647 ] ]

The IDs of forbidden workers.

This is a strict restriction and might fail validation if it is impossible to keep.

unpreferredWorkers
Array of integers (IDReferences) [ items [ 0 .. 2147483647 ] ]

The IDs of workers to which an assignment is undesirable but not forbidden.

This is a preference and can be violated for other preferences or restrictions. Its importance depends on the parameter taskPrefs.

antiWorkers
Array of integers (IDReferences) [ items [ 0 .. 2147483647 ] ]
Deprecated

Alias for unpreferredWorkers.

qualification
integer (Integer_u32) [ 0 .. 2147483647 ]

The minimum qualification of the worker required to perform the task (e.g. years of experience). Workers without qualification are not allowed to perform tasks of any qualification.

This is a strict restriction and might fail validation if it is impossible to keep.

maxQualification
integer (Integer_u32) [ 0 .. 2147483647 ]

The maximum qualification of the worker allowed to perform the task. Workers without qualification can carry out any task with qualification (as long as the other restrictions are not violated).

This is a strict restriction and might fail validation if it is impossible to keep.

categories
Array of integers (IDReferences) [ items [ 0 .. 2147483647 ] ]

A suitable worker has to fulfill all of these categories.

This is a strict restriction and might fail validation if it is impossible to keep.

exchangeableCategories
Array of integers (IDReferences) [ items [ 0 .. 2147483647 ] ]

A suitable worker has to fulfill at least one of these categories.

This is a strict restriction and might fail validation if it is impossible to keep.

preassignedWorker
integer (Integer_u32) [ 0 .. 2147483647 ]

The workerID of the only worker that is allowed to carry out the task. This setting overrules any other strict restriction - for example, if the worker does not fulfil the qualification requirement, the task will still get assigned to them. The field can also be used for dontVary assignments. A preassignedWorker does not imply an assignmentPriority - if allowUnassignedTasks is active, the task being unassigned is not a violation of this restriction.

This is a strict restriction and might fail validation if it is impossible to keep.

preassignedOrder
integer (Integer_s32) [ -2147483648 .. 2147483647 ]

Tasks with a value > 0 will be assigned as the first tasks of the preassignedWorker, tasks with a value < 0 as their last. If multiple tasks preassigned to a worker have a preassignedOrder, the tasks will be sorted so that the preassignedOrder is increasing.

This is a strict restriction and might fail validation if it is impossible to keep.

desiredWorker
integer (Integer_u32) [ 0 .. 2147483647 ]

The ID of the worker who is desired (strong preference) to take over this task.

This is a preference and can be violated for other preferences or restrictions.

prefGender
integer (GenderType) [ 0 .. 3 ]

The preferred gender for the assigned worker.

This usually is a preference and can be violated for other preferences or restrictions. Its importance depends on the parameter genderPrefs. If the parameter has the maximum value, it is considered a weak restriction instead and will be considered only if it is possible to keep it. It will not fail the validation if it is impossible to keep it.

precedingTasks
Array of integers (IDReferences) [ items [ 0 .. 2147483647 ] ]

Tasks in this list and this task will be performed by the same worker and all listed tasks will have to be finished before this task starts.

This is a strict restriction and might fail validation if it is impossible to keep.

predecessorTasks
Array of integers (IDReferences) [ items [ 0 .. 2147483647 ] ]

One of these tasks has be carried out right before this task by the same worker. Putting multiple values in the array does not mean they are carried out in that order - if you want to have a predecessor-chain, you need to set the direct predecessor on each task in the chain (see examples). Do not put redundant values in here, as having more than one value in the array has negative impact on performance and solution quality.

This is a strict restriction and might fail validation if it is impossible to keep.

group
integer (Integer_u32) [ 0 .. 2147483647 ]

A group ID. Tasks with the same group get assigned to the same worker.

This is a strict restriction and might fail validation if it is impossible to keep.

groupOrder
integer (Integer_u32) [ 0 .. 2147483647 ]
Deprecated

Unsigned 32 bit integer with the upper limit of a signed 32bit integer

revenue
number (Number_u64) [ 0 .. 1.7e+308 ]
Default: 0

The revenue which will be achieved with this task.

initassignedShift
integer (Integer_u32) [ 0 .. 2147483647 ]
Deprecated

Unsigned 32 bit integer with the upper limit of a signed 32bit integer

assignmentPriority
integer (Integer_0_5) [ 0 .. 5 ]
Default: 1

A priority for assignment (see allowUnassignedTasks):.

  • 0 - no preference regarding unassignment, whether or not the task is assigned does not matter and will depend solely on other factors
  • 1-4 - progressively higher assignment importance
  • 5 - task has to be assigned

If allowUnassignedTasks is set to false, this field has no effect.

For tasks with an assignmentPriority of 5, the task being assigned is considered a strict restriction.

initassignedWorker
integer (Integer_u32) [ 0 .. 2147483647 ]

A hint for large optimization data sets, e.g. solution data from a previous optimization request. The field can also be used for dontVary assignments.

initassignedOrder
integer (Integer_u32) [ 0 .. 2147483647 ]

Requires preassignedWorker or initassignedWorker. The order within the initially assigned worker's tour.

timeScheduled
required
string (Time) ^[-]?([0-9]{1,9}):([0-5][0-9]|[0-9])$

The planned time to start this task by the assigned worker.

timeWindowViolation
integer (Integer_s32) [ -2147483648 .. 2147483647 ]

If the task is scheduled outside its time window, this value displays the discrepancy in minutes - the value is < 0 if the task was scheduled earlier than its time window and > 0 otherwise. If the task is scheduled within its time window, the field does not get added.

Examples:

  • A task of 30 minutes with timeLatest: 12:00 scheduled at 11:45 will have timeWindowViolation: 15.
  • A task with timeEarliest: 10:00 scheduled at 09:30 will have timeWindowViolation: -30.
assignedWorker
required
integer (Integer_u32) [ 0 .. 2147483647 ]

The ID of the assigned worker who will carry out this task.

assignedShift
integer (Integer_u32) [ 0 .. 2147483647 ]
Deprecated

The ID of the assigned shift on the assigned worker.

info
required
string

May contain some information about the worker.

allowedWorkers
Array of integers (IDReferences) [ items [ 0 .. 2147483647 ] ]

A list of all workers (workerID) this task can be assigned to.

finalassignedOrder
required
integer (Integer_u32_1) [ 1 .. 2147483647 ]

The order number on the assigned worker.

profit
required
number (Number_s64) [ -1.7e+308 .. 1.7e+308 ]

The profit the task creates (revenue - costs).

{
  • "taskID": 2147483647,
  • "externalID": "string",
  • "date": "2020-04-10",
  • "duration": 2147483647,
  • "timeEarliest": "07:25",
  • "timeLatest": "07:25",
  • "timePriority": 5,
  • "prefWorkers": [
    ],
  • "forbWorkers": [
    ],
  • "unpreferredWorkers": [
    ],
  • "antiWorkers": [
    ],
  • "qualification": 2147483647,
  • "maxQualification": 2147483647,
  • "categories": [
    ],
  • "exchangeableCategories": [
    ],
  • "preassignedWorker": 2147483647,
  • "preassignedOrder": -2147483648,
  • "desiredWorker": 2147483647,
  • "prefGender": 3,
  • "precedingTasks": [
    ],
  • "predecessorTasks": [
    ],
  • "group": 2147483647,
  • "groupOrder": 2147483647,
  • "revenue": 1.7e+308,
  • "initassignedShift": 2147483647,
  • "assignmentPriority": 5,
  • "initassignedWorker": 2147483647,
  • "initassignedOrder": 2147483647,
  • "timeScheduled": "07:25",
  • "timeWindowViolation": -2147483648,
  • "assignedWorker": 2147483647,
  • "assignedShift": 2147483647,
  • "info": "string",
  • "allowedWorkers": [
    ],
  • "finalassignedOrder": 1,
  • "profit": -1.7e+308
}

ShiftPlannerOutputTaskUnassigned

taskID
required
integer (Integer_u32) [ 0 .. 2147483647 ]

The ID of this task. IDs need to be unique among all tasks.

externalID
string

A string to identify the task in the solution. Cannot be used for reference in the input data or the optimizer, it only serves as a helping tool for integrations.

date
required
string (Date) ^[0-9]{4}-(0?[1-9]|1[0-2])-(0?[1-9]|[1-2][0-9...

The date this task should be planned on.

duration
required
integer (Integer_u32) [ 0 .. 2147483647 ]

The time in minutes it takes to complete this task.

timeEarliest
required
string (Time) ^[-]?([0-9]{1,9}):([0-5][0-9]|[0-9])$

The earliest possible starting time of this task.

This is a preference and can be violated for other preferences or restrictions. Its importance depends on the parameter timeliness.

timeLatest
required
string (Time) ^[-]?([0-9]{1,9}):([0-5][0-9]|[0-9])$

The latest time at which this task should be finished.

This is a preference and can be violated for other preferences or restrictions. Its importance depends on the parameter timeliness.

timePriority
integer (Integer_0_5) [ 0 .. 5 ]
Default: 1

The priority of the time window:

  • 0 - irrelevant
  • 1 - not important
  • 2 - more important
  • 3 - important
  • 4 - very important
  • 5 - fixed time

Tasks with high time priority are more likely to get scheduled inside their given time window. Tasks with time priority 0 completely ignore their given time window.

For tasks with a timePriority of 3 or higher, the time window is considered a strict restriction.

prefWorkers
Array of integers (IDReferences) [ items [ 0 .. 2147483647 ] ]

The IDs of preferred workers.

This is a preference and can be violated for other preferences or restrictions. Its importance depends on the parameter taskPrefs.

forbWorkers
Array of integers (IDReferences) [ items [ 0 .. 2147483647 ] ]

The IDs of forbidden workers.

This is a strict restriction and might fail validation if it is impossible to keep.

unpreferredWorkers
Array of integers (IDReferences) [ items [ 0 .. 2147483647 ] ]

The IDs of workers to which an assignment is undesirable but not forbidden.

This is a preference and can be violated for other preferences or restrictions. Its importance depends on the parameter taskPrefs.

antiWorkers
Array of integers (IDReferences) [ items [ 0 .. 2147483647 ] ]
Deprecated

Alias for unpreferredWorkers.

qualification
integer (Integer_u32) [ 0 .. 2147483647 ]

The minimum qualification of the worker required to perform the task (e.g. years of experience). Workers without qualification are not allowed to perform tasks of any qualification.

This is a strict restriction and might fail validation if it is impossible to keep.

maxQualification
integer (Integer_u32) [ 0 .. 2147483647 ]

The maximum qualification of the worker allowed to perform the task. Workers without qualification can carry out any task with qualification (as long as the other restrictions are not violated).

This is a strict restriction and might fail validation if it is impossible to keep.

categories
Array of integers (IDReferences) [ items [ 0 .. 2147483647 ] ]

A suitable worker has to fulfill all of these categories.

This is a strict restriction and might fail validation if it is impossible to keep.

exchangeableCategories
Array of integers (IDReferences) [ items [ 0 .. 2147483647 ] ]

A suitable worker has to fulfill at least one of these categories.

This is a strict restriction and might fail validation if it is impossible to keep.

preassignedWorker
integer (Integer_u32) [ 0 .. 2147483647 ]

The workerID of the only worker that is allowed to carry out the task. This setting overrules any other strict restriction - for example, if the worker does not fulfil the qualification requirement, the task will still get assigned to them. The field can also be used for dontVary assignments. A preassignedWorker does not imply an assignmentPriority - if allowUnassignedTasks is active, the task being unassigned is not a violation of this restriction.

This is a strict restriction and might fail validation if it is impossible to keep.

preassignedOrder
integer (Integer_s32) [ -2147483648 .. 2147483647 ]

Tasks with a value > 0 will be assigned as the first tasks of the preassignedWorker, tasks with a value < 0 as their last. If multiple tasks preassigned to a worker have a preassignedOrder, the tasks will be sorted so that the preassignedOrder is increasing.

This is a strict restriction and might fail validation if it is impossible to keep.

desiredWorker
integer (Integer_u32) [ 0 .. 2147483647 ]

The ID of the worker who is desired (strong preference) to take over this task.

This is a preference and can be violated for other preferences or restrictions.

prefGender
integer (GenderType) [ 0 .. 3 ]

The preferred gender for the assigned worker.

This usually is a preference and can be violated for other preferences or restrictions. Its importance depends on the parameter genderPrefs. If the parameter has the maximum value, it is considered a weak restriction instead and will be considered only if it is possible to keep it. It will not fail the validation if it is impossible to keep it.

precedingTasks
Array of integers (IDReferences) [ items [ 0 .. 2147483647 ] ]

Tasks in this list and this task will be performed by the same worker and all listed tasks will have to be finished before this task starts.

This is a strict restriction and might fail validation if it is impossible to keep.

predecessorTasks
Array of integers (IDReferences) [ items [ 0 .. 2147483647 ] ]

One of these tasks has be carried out right before this task by the same worker. Putting multiple values in the array does not mean they are carried out in that order - if you want to have a predecessor-chain, you need to set the direct predecessor on each task in the chain (see examples). Do not put redundant values in here, as having more than one value in the array has negative impact on performance and solution quality.

This is a strict restriction and might fail validation if it is impossible to keep.

group
integer (Integer_u32) [ 0 .. 2147483647 ]

A group ID. Tasks with the same group get assigned to the same worker.

This is a strict restriction and might fail validation if it is impossible to keep.

groupOrder
integer (Integer_u32) [ 0 .. 2147483647 ]
Deprecated

Unsigned 32 bit integer with the upper limit of a signed 32bit integer

revenue
number (Number_u64) [ 0 .. 1.7e+308 ]
Default: 0

The revenue which will be achieved with this task.

initassignedShift
integer (Integer_u32) [ 0 .. 2147483647 ]
Deprecated

Unsigned 32 bit integer with the upper limit of a signed 32bit integer

assignmentPriority
integer (Integer_0_5) [ 0 .. 5 ]
Default: 1

A priority for assignment (see allowUnassignedTasks):.

  • 0 - no preference regarding unassignment, whether or not the task is assigned does not matter and will depend solely on other factors
  • 1-4 - progressively higher assignment importance
  • 5 - task has to be assigned

If allowUnassignedTasks is set to false, this field has no effect.

For tasks with an assignmentPriority of 5, the task being assigned is considered a strict restriction.

initassignedWorker
integer (Integer_u32) [ 0 .. 2147483647 ]

A hint for large optimization data sets, e.g. solution data from a previous optimization request. The field can also be used for dontVary assignments.

initassignedOrder
integer (Integer_u32) [ 0 .. 2147483647 ]

Requires preassignedWorker or initassignedWorker. The order within the initially assigned worker's tour.

info
required
string

May contain some information about the task, will give a reason as to why this task is unassigned.

allowedWorkers
Array of integers (IDReferences) [ items [ 0 .. 2147483647 ] ]

A list of all workers (workerID) this task can be assigned to.

{
  • "taskID": 2147483647,
  • "externalID": "string",
  • "date": "2020-04-10",
  • "duration": 2147483647,
  • "timeEarliest": "07:25",
  • "timeLatest": "07:25",
  • "timePriority": 5,
  • "prefWorkers": [
    ],
  • "forbWorkers": [
    ],
  • "unpreferredWorkers": [
    ],
  • "antiWorkers": [
    ],
  • "qualification": 2147483647,
  • "maxQualification": 2147483647,
  • "categories": [
    ],
  • "exchangeableCategories": [
    ],
  • "preassignedWorker": 2147483647,
  • "preassignedOrder": -2147483648,
  • "desiredWorker": 2147483647,
  • "prefGender": 3,
  • "precedingTasks": [
    ],
  • "predecessorTasks": [
    ],
  • "group": 2147483647,
  • "groupOrder": 2147483647,
  • "revenue": 1.7e+308,
  • "initassignedShift": 2147483647,
  • "assignmentPriority": 5,
  • "initassignedWorker": 2147483647,
  • "initassignedOrder": 2147483647,
  • "info": "string",
  • "allowedWorkers": [
    ]
}

ShiftPlannerOutputWorker

workerID
required
integer (Integer_u32) [ 0 .. 2147483647 ]

The ID of the worker. Needs to be unique among all workers.

externalID
string

A string to identify the worker in the solution. Cannot be used for reference in the input data or the optimizer, it only serves as a helping tool for integrations.

Array of objects (ShiftPlannerShift)

The time slots during which the worker can carry out tasks.

qualification
integer (Integer_u32) [ 0 .. 2147483647 ]

The qualification of the worker. They are able to take over tasks with the same or lower qualifications.

categories
Array of integers (IDReferences) [ items [ 0 .. 2147483647 ] ]

The worker can only carry out tasks if he has each category the task requires.

desiredCategory
integer (Integer_u32) [ 0 .. 2147483647 ]

The worker has a strong preference towards tasks with this category. The value already counts as a category and does not need to be included in categories.

This is a preference and can be violated for other preferences or restrictions.

prefCategories
Array of integers (IDReferences) [ items [ 0 .. 2147483647 ] ]

The task categories preferred by the worker. Values already count as a categories and do not need to be included in categories.

This is a preference and can be violated for other preferences or restrictions. Its importance depends on the parameter workerPrefs.

prefWeekCategories
Array of integers (IDReferences) [ items [ 0 .. 2147483647 ] ]

The task categories preferred by the worker on any week day (Mon-Fri). Values already count as a categories and do not need to be included in categories.

This is a preference and can be violated for other preferences or restrictions. Its importance depends on the parameter workerPrefs.

prefWeekendCategories
Array of integers (IDReferences) [ items [ 0 .. 2147483647 ] ]

The task categories preferred by the worker on any weekend day (Sat, Sun). Values already count as a categories and do not need to be included in categories.

This is a preference and can be violated for other preferences or restrictions. Its importance depends on the parameter workerPrefs.

prefWorkers
Array of integers (IDReferences) [ items [ 0 .. 2147483647 ] ]

The workers that this worker prefers to have simultaneous shifts with.

This is a preference and can be violated for other preferences or restrictions. Its importance depends on the parameter teamPrefs.

unpreferredWorkers
Array of integers (IDReferences) [ items [ 0 .. 2147483647 ] ]

The workers that this worker prefers to not have simultaneous shifts with.

This is a preference and can be violated for other preferences or restrictions. Its importance depends on the parameter teamPrefs.

antiWorkers
Array of integers (IDReferences) [ items [ 0 .. 2147483647 ] ]
Deprecated

Alias for unpreferredWorkers.

gender
integer (GenderType) [ 0 .. 3 ]

The gender type of the worker.

expectedWorkingMinutes
integer (Integer_u32) [ 0 .. 2147483647 ]

The preferred amount of working time minutes for this worker in the final plan, deviation in both directions will be kept as low as possible.

This is a preference and can be violated for other preferences or restrictions. Its importance depends on the parameter worktimePrefs.

minWorkingMinutes
integer (Integer_u32) [ 0 .. 2147483647 ]
Default: 0

The minimum amount of working time minutes for this worker in the final plan.

This is a preference and can be violated for other preferences or restrictions.

maxWorkingMinutes
integer (Integer_u32) [ 0 .. 2147483647 ]

The maximum amount of working time minutes for this worker in the final plan.

This is a preference and can be violated for other preferences or restrictions.

maxConsecutiveWorkdays
integer (Integer_u32) [ 0 .. 2147483647 ]

Maximum number of consecutive workdays. A day is a workday if any work is performed from 00:00 to 23:59.

This is a preference and can be violated for other preferences or restrictions.

minConsecutiveWorkdays
integer (Integer_u32) [ 0 .. 2147483647 ]
Default: 0

Minimum number of consecutive workdays. A day is a workday if any work is performed from 00:00 to 23:59.

This is a preference and can be violated for other preferences or restrictions.

prefConsecutiveWorkdays
integer (Integer_u32) [ 0 .. 2147483647 ]

The preferred number of working days in a row.

This is a preference and can be violated for other preferences or restrictions. Its importance depends on the parameter workerPrefs.

carryoverConsecutiveWorkdays
integer (Integer_u32) [ 0 .. 2147483647 ]

Can not be used with carryoverConsecutiveOffdays. The current number of consecutive workdays at the start of the plan.

maxConsecutiveOffdays
integer (Integer_u32) [ 0 .. 2147483647 ]

Maximum number of consecutive days off. A day counts as a "day off" if no work is performed from 00:00 to 23:59.

This is a preference and can be violated for other preferences or restrictions.

minConsecutiveOffdays
integer (Integer_u32) [ 0 .. 2147483647 ]
Default: 0

Minimum number of consecutive days off. A day counts as a "day off" if no work is performed from 00:00 to 23:59.

This is a preference and can be violated for other preferences or restrictions.

prefConsecutiveOffdays
integer (Integer_u32) [ 0 .. 2147483647 ]

The preferred number of non-working days in a row.

This is a preference and can be violated for other preferences or restrictions. Its importance depends on the parameter workerPrefs.

carryoverConsecutiveOffdays
integer (Integer_u32) [ 0 .. 2147483647 ]

Can not be used with carryoverConsecutiveWorkdays. The current number of consecutive days off at the start of the plan.

minBreakMinutesBetweenTasks
integer (Integer_u32) [ 0 .. 2147483647 ]
Default: 0

Minimum number of minutes break between two Tasks that start on different days.

This is a strict restriction and might fail validation if it is impossible to keep.

maxDailyWorkingMinutes
integer (Integer_u32) [ 0 .. 2147483647 ]

Maximum number of working minutes per day.

This is a preference and can be violated for other preferences or restrictions.

maxDailyTasks
integer (Integer_u32) [ 0 .. 2147483647 ]

Maximum number of tasks per day. Tasks count towards the day they start in. "Predecessor-Chains" (sets of tasks linked to a "chain" by predecessorTasks) count as one task for this limit.

This is a strict restriction and might fail validation if it is impossible to keep.

minFreeSaturdays
integer (Integer_u32) [ 0 .. 2147483647 ]
Default: 0

Minimum number of work-free Saturdays for this worker.

This is a strict restriction and might fail validation if it is impossible to keep.

minFreeSundays
integer (Integer_u32) [ 0 .. 2147483647 ]
Default: 0

Minimum number of work-free Sundays for this worker.

This is a strict restriction and might fail validation if it is impossible to keep.

maxWeeklyWorkingMinutes
integer (Integer_u32) [ 0 .. 2147483647 ]

Maximum minutes working time for this worker each calendar week (Monday to Sunday). Please note that the week cycle might be independent from the planning horizon, use carryoverWorkingMinutesLastWeek in conflicting cases.

This is a preference and can be violated for other preferences or restrictions.

carryoverWorkingMinutesLastWeek
integer (Integer_u32) [ 0 .. 2147483647 ]

Minutes of worktime already performed by this worker in the week that dateFrom belongs to. The value is factored in by maxWeeklyWorkingMinutes and maxTwoWeekWorkingMinutes but not expectedWorkingMinutes!

maxTwoWeekWorkingMinutes
integer (Integer_u32) [ 0 .. 2147483647 ]

Maximum minutes working time for this worker for every two consecutive calendar weeks (Monday to Sunday). Please note that the week cycle is independent from the planning horizon, use carryoverWorkingMinutesLastWeek and carryoverWorkingMinutesSecondLastWeek in conflicting cases.

This is a preference and can be violated for other preferences or restrictions.

carryoverWorkingMinutesSecondLastWeek
integer (Integer_u32) [ 0 .. 2147483647 ]

Minutes of worktime already performed by this worker in the week prior to the earliest shiftStart (pre v3.8.12)/ dateFrom (v3.8.12) of any Worker in this plan. The value is factored in by maxWeeklyWorkingMinutes and maxTwoWeekWorkingMinutes but not expectedWorkingMinutes!

dontVary
boolean

A worker with dontVary set to true is "fixed" for the optimizer, meaning they get assigned all tasks (and only those tasks) that have this worker set as preassignedWorker or initassignedWorker in the order of initassignedOrder. That also means that initassignedOrder is required for these tasks. All output information still gets calculated on both worker and task, and the worker and its tasks will be considered in statistics and info.

This is a strict restriction and might fail validation if it is impossible to keep.

dontAlter
boolean
Default: false

Workers with dontAlter set to true behave similarly to workers with dontVary. The only difference is that a dontVary-worker cannot get assigned more tasks than specified in the input data, a dontAlter-worker will be assigned all tasks that have this worker as initassignedWorker or preassignedWorker, but can also have other tasks assigned. While the preassigned/initassigned tasks will be in order of initassignedOrder, other tasks can be inserted before, between or after those tasks; if there is no initassignedOrder set, the task will be ignored. Every other behavior and requirement is exactly as in dontVary.

This is a strict restriction and might fail validation if it is impossible to keep.

allowPreassignedTasksOnly
boolean
Default: false

If this flag is true, only tasks preassigned to this worker can be assigned to it. Tasks not preassigned to this worker cannot be assigned to it.

This is a strict restriction and might fail validation if it is impossible to keep.

costsPerMinute
number (Number_u64) [ 0 .. 1.7e+308 ]
Default: 0

The costs per minute working time (carrying out tasks) for this worker (e.g. monthly salary converted to minutes).

costsInitial
number (Number_u64) [ 0 .. 1.7e+308 ]
Default: 0

Costs that occur if there is at least one task assigned to the worker.

precTaskDate
string (Date) ^[0-9]{4}-(0?[1-9]|1[0-2])-(0?[1-9]|[1-2][0-9...

Date of the last task the worker carried out before the start of this plan.

precTaskScheduled
string (Time) ^[-]?([0-9]{1,9}):([0-5][0-9]|[0-9])$

Scheduled time of the last task the worker carried out before the start of this plan.

precTaskDuration
integer (Integer_u32) [ 0 .. 2147483647 ]

Duration of the last task the worker carried out before the start of this plan.

precNightShifts
integer (Integer_u32) [ 0 .. 2147483647 ]

Amount of consecutive "night shifts" the worker carried out directly before the start of this plan. Those are tasks that are scheduled in a way that they overlap with midnight. For more details see below.

maxOrderedGroups
integer (Integer_u32) [ 0 .. 2147483647 ]

The maximum number of task sets with same group and set group order that can be assigned to this worker.

maxDesiredOrderedGroups
integer (Integer_u32) [ 0 .. 2147483647 ]

A preference for the maximum number of task sets with same group and set group order that can be assigned to this worker.

This is a strict restriction and might fail validation if it is impossible to keep.

maxNightShifts
integer (Integer_u32) [ 0 .. 2147483647 ]

The maximum number of "night shifts" this worker can get assigned.

This is a strict restriction and might fail validation if it is impossible to keep.

maxDesiredNightShifts
integer (Integer_u32) [ 0 .. 2147483647 ]

A preference for the maximum number of "night shifts" this worker can get assigned.

This is a preference and can be violated for other preferences or restrictions.

minFreeWeekends
integer (Integer_u32) [ 0 .. 2147483647 ]
Default: 0

The minimum number of completely free weekends with no work on either Saturday or Sunday.

This is a strict restriction and might fail validation if it is impossible to keep.

minDesiredFreeWeekends
integer (Integer_u32) [ 0 .. 2147483647 ]
Default: 0

A preference for the minimum number of completely free weekends with no work on either Saturday or Sunday.

This is a preference and can be violated for other preferences or restrictions.

maxConsecutiveSameTaskStart
integer (Integer_u32) [ 0 .. 2147483647 ]

Can not be used with maxDesiredConsecutiveSameTaskStart. The maximum number of assigned consecutive tasks with a timeScheduled difference of at most 120 min.

This is a strict restriction and might fail validation if it is impossible to keep.

maxDesiredConsecutiveSameTaskStart
integer (Integer_u32) [ 0 .. 2147483647 ]

Can not be used with maxConsecutiveSameTaskStart. A desired maximum number of assigned consecutive tasks with a timeScheduled difference of at most 120 min.

This is a preference and can be violated for other preferences or restrictions.

maxWeeklyWorkingDays
integer (Integer_u32) [ 0 .. 2147483647 ]

The maximum number of tasks in one week. Tasks only count for the week they start in (timeScheduled).

This is a strict restriction and might fail validation if it is impossible to keep.

prefWeeklyWorkingDays
integer (Integer_u32) [ 0 .. 2147483647 ]

The preferred maximum number of tasks in one week. Tasks only count for the week they start in (timeScheduled).

This is a preference and can be violated for other preferences or restrictions.

carryoverWorkingDaysLastWeek
integer (Integer_u32) [ 0 .. 2147483647 ]

Number of already carried-out workdays in the week that dateFrom belongs to.

minConsecutiveFreeWeekends
integer (Integer_u32) [ 0 .. 2147483647 ]
Default: 0

The minimum amount of consecutive weekends without any tasks assigned (task starting on either Saturday or Sunday). This restriction does not apply to the end of the planning horizon, there may be less free weekends than set here right before dateTo.

This is a strict restriction and might fail validation if it is impossible to keep.

minDesiredConsecutiveFreeWeekends
integer (Integer_u32) [ 0 .. 2147483647 ]
Default: 0

The desired minimum amount of consecutive weekends without any tasks assigned (task starting on either Saturday or Sunday). This restriction does not apply to the end of the planning horizon, there may be less free weekends than set here right before dateTo.

This is a preference and can be violated for other preferences or restrictions.

maxConsecutiveFreeWeekends
integer (Integer_u32) [ 0 .. 2147483647 ]

The maximum amount of consecutive weekends without any tasks assigned (task starting on either Saturday or Sunday).

This is a strict restriction and might fail validation if it is impossible to keep.

maxDesiredConsecutiveFreeWeekends
integer (Integer_u32) [ 0 .. 2147483647 ]

The desired maximum amount of consecutive weekends without any tasks assigned (task starting on either Saturday or Sunday).

This is a preference and can be violated for other preferences or restrictions.

minConsecutiveWorkingWeekends
integer (Integer_u32) [ 0 .. 2147483647 ]
Default: 0

The minimum amount of consecutive weekends with at least one task assigned (task starting on either Saturday or Sunday).

This is a strict restriction and might fail validation if it is impossible to keep.

minDesiredConsecutiveWorkingWeekends
integer (Integer_u32) [ 0 .. 2147483647 ]
Default: 0

The desired minimum amount of consecutive weekends with at least one task assigned (task starting on either Saturday or Sunday).

This is a preference and can be violated for other preferences or restrictions.

maxConsecutiveWorkingWeekends
integer (Integer_u32) [ 0 .. 2147483647 ]

The maximum amount of consecutive weekends with at least one task assigned (task starting on either Saturday or Sunday).

This is a strict restriction and might fail validation if it is impossible to keep.

maxDesiredConsecutiveWorkingWeekends
integer (Integer_u32) [ 0 .. 2147483647 ]

The desired maximum amount of consecutive weekends with at least one task assigned (task starting on either Saturday or Sunday).

This is a preference and can be violated for other preferences or restrictions.

precWeekendWorkingDay
string (Date) ^[0-9]{4}-(0?[1-9]|1[0-2])-(0?[1-9]|[1-2][0-9...

The latest working day on a weekend before dateFrom.

carryoverConsecutiveWorkingWeekends
integer (Integer_u32) [ 0 .. 2147483647 ]

The amount of consecutive weekends with at least one task performed on either Saturday or Sunday on and before the first complete weekend before dateFrom. See below for explanations.

consecutiveNightShiftsForOffdays
integer (Integer_u32) [ 0 .. 2147483647 ]

After a night shift streak consisting of this or more night shifts, there have to be a number of days off (number of days is defined in minOffdaysAfterConsecutiveNightShifts). This also means that it is disallowed to have a non-night-shift directly after a night shift.

minOffdaysAfterConsecutiveNightShifts
integer (Integer_u32) [ 0 .. 2147483647 ]
Default: 0

The number of days off after a corresponding trigger.

This is a strict restriction and might fail validation if it is impossible to keep.

workdayPattern
Array of integers (Integer_u32_1) >= 2 items [ items [ 1 .. 2147483647 ] ]

This field can be used to define irregular workday patterns. There must be an even number of entries, where each even numbered entry (starting at zero) is the number of workdays and each odd numbered entry the number of days off.

Example: The array [1, 2, 4, 1] means the worker shall work (exactly) one day, then have two days off, then work four days, then have one day off. Then start over at the beginning.

If no history data is provided, the rhythm will start on dateFrom. If there is history data, the algorithm finds a day the previous iteration most likely ended and starts the rhythm from there.

This is a preference and can be violated for other preferences or restrictions.

object

Define workday restrictions for a smaller periods of time (e.g. 7 days, 14 days) than the whole plan. Those cycles loop until dateTo.

If no history data is provided, the first cycle will start on dateFrom. If there is history data, the algorithm finds a day the previous iteration most likely ended and starts the first cycle from there.

Array of objects (TimeSlot)

The worker will definitely work during the time slots specified here. Tasks can overlap the time slots, in which case they get "merged" onto the overlapping task. If the time slot does not get overlapped, it counts as a regular task. Time slots may not overlap each other.

preventSplitWeekends
boolean
Default: false

If true, the algorithm will avoid scheduling tasks on only one day of the weekend - this worker should be working either on both days or none. This is a preference and can be violated for other preferences or restrictions.

info
string

Some textual information about the worker.

totalTaskTime
required
integer (Integer_u32) [ 0 .. 2147483647 ]

Sum of the duration of all tasks assigned to this worker.

{
  • "workerID": 2147483647,
  • "externalID": "string",
  • "shifts": [
    ],
  • "qualification": 2147483647,
  • "categories": [
    ],
  • "desiredCategory": 2147483647,
  • "prefCategories": [
    ],
  • "prefWeekCategories": [
    ],
  • "prefWeekendCategories": [
    ],
  • "prefWorkers": [
    ],
  • "unpreferredWorkers": [
    ],
  • "antiWorkers": [
    ],
  • "gender": 3,
  • "expectedWorkingMinutes": 2147483647,
  • "minWorkingMinutes": 2147483647,
  • "maxWorkingMinutes": 2147483647,
  • "maxConsecutiveWorkdays": 2147483647,
  • "minConsecutiveWorkdays": 2147483647,
  • "prefConsecutiveWorkdays": 2147483647,
  • "carryoverConsecutiveWorkdays": 2147483647,
  • "maxConsecutiveOffdays": 2147483647,
  • "minConsecutiveOffdays": 2147483647,
  • "prefConsecutiveOffdays": 2147483647,
  • "carryoverConsecutiveOffdays": 2147483647,
  • "minBreakMinutesBetweenTasks": 2147483647,
  • "maxDailyWorkingMinutes": 2147483647,
  • "maxDailyTasks": 2147483647,
  • "minFreeSaturdays": 2147483647,
  • "minFreeSundays": 2147483647,
  • "maxWeeklyWorkingMinutes": 2147483647,
  • "carryoverWorkingMinutesLastWeek": 2147483647,
  • "maxTwoWeekWorkingMinutes": 2147483647,
  • "carryoverWorkingMinutesSecondLastWeek": 2147483647,
  • "dontVary": true,
  • "dontAlter": false,
  • "allowPreassignedTasksOnly": false,
  • "costsPerMinute": 1.7e+308,
  • "costsInitial": 1.7e+308,
  • "precTaskDate": "2020-04-10",
  • "precTaskScheduled": "07:25",
  • "precTaskDuration": 2147483647,
  • "precNightShifts": 2147483647,
  • "maxOrderedGroups": 2147483647,
  • "maxDesiredOrderedGroups": 2147483647,
  • "maxNightShifts": 2147483647,
  • "maxDesiredNightShifts": 2147483647,
  • "minFreeWeekends": 2147483647,
  • "minDesiredFreeWeekends": 2147483647,
  • "maxConsecutiveSameTaskStart": 2147483647,
  • "maxDesiredConsecutiveSameTaskStart": 2147483647,
  • "maxWeeklyWorkingDays": 2147483647,
  • "prefWeeklyWorkingDays": 2147483647,
  • "carryoverWorkingDaysLastWeek": 2147483647,
  • "minConsecutiveFreeWeekends": 2147483647,
  • "minDesiredConsecutiveFreeWeekends": 2147483647,
  • "maxConsecutiveFreeWeekends": 2147483647,
  • "maxDesiredConsecutiveFreeWeekends": 2147483647,
  • "minConsecutiveWorkingWeekends": 2147483647,
  • "minDesiredConsecutiveWorkingWeekends": 2147483647,
  • "maxConsecutiveWorkingWeekends": 2147483647,
  • "maxDesiredConsecutiveWorkingWeekends": 2147483647,
  • "precWeekendWorkingDay": "2020-04-10",
  • "carryoverConsecutiveWorkingWeekends": 2147483647,
  • "consecutiveNightShiftsForOffdays": 2147483647,
  • "minOffdaysAfterConsecutiveNightShifts": 2147483647,
  • "workdayPattern": [
    ],
  • "workdayCycle": {
    },
  • "fixedPresences": [
    ],
  • "preventSplitWeekends": false,
  • "info": "string",
  • "totalTaskTime": 2147483647
}

Fraction

number (Fraction) [ 0 .. 1 ]
1

Weekday

integer (Weekday) [ 0 .. 6 ]

A numerical representation of a weekday. Values are:

  • 0: Sunday
  • 1: Monday
  • 2: Tuesday
  • 3: Wednesday
  • 4: Thursday
  • 5: Friday
  • 6: Saturday
6

ShiftPlannerStatistics

required
Array of objects

Contains all restriction types and gives the absolute value as well as a percentage (0.0-1.0) evaluation of each restriction's final influence on the algorithmic optimization and plan result.

timeWindowViolationTaskIDs
Array of integers (Integer_u32) [ items [ 0 .. 2147483647 ] ]

taskIDs of all tasks not assigned within their given time window.

unassignedTaskIDs
Array of integers (Integer_u32) [ items [ 0 .. 2147483647 ] ]

taskIDs of all tasks that were not assigned during optimization.

unassignableTaskIDs
Array of integers (Integer_u32) [ items [ 0 .. 2147483647 ] ]

taskIDs of all tasks that were not assigned during optimization because there is no assignment possible (meaning they would fail input validation if unassigned tasks were not allowed).

object

All data determined from the history.

object (ShiftPlannerStatisticsPreferencesMatches)

Preference statistics for prefWorkers on tasks.

object (ShiftPlannerStatisticsPreferencesMatches)

Preference statistics for antiWorkers on tasks.

{
  • "impact": [
    ],
  • "timeWindowViolationTaskIDs": [
    ],
  • "unassignedTaskIDs": [
    ],
  • "unassignableTaskIDs": [
    ],
  • "history": {
    },
  • "preferredWorkers": {
    },
  • "unpreferredWorkers": {
    }
}

ShiftPlannerInfo

text
required
string

Some general information about the plan.

feasible
required
boolean

Set to false if any restrictions are violated in the solution.

{
  • "text": "string",
  • "feasible": true
}

FieldPlacerVersion

string (FieldPlacerVersion) ^[0-9]{4}-[0-9]{2}-[0-9]{2}_[0-9]+(p[0-9]+)?$...

A version consisting of the date of release [0-9]{4}-[0-9]{2}-[0-9]{2}_[0-9]+, which can have a patch suffix p[0-9]+.

"1970-01-01_0p0"

SemanticVersion

string (SemanticVersion) ^(v)?(0|([1-9][0-9]{0,4}))(\.(0|([1-9][0-9]{0...

See https://semver.org/ for a full description of semantic versioning. The regex here is a subset of allowed semantic versions.

"v1.2.3"

BackendVersion

version
any
Deprecated
Value: "v1.0.0"
optVersion
string (FieldPlacerVersion) ^[0-9]{4}-[0-9]{2}-[0-9]{2}_[0-9]+(p[0-9]+)?$...

The version of the algorithm used for calculating the result.

rev
string >= 7 characters

An internal identifier for the algorithm version.

schema
required
string (SemanticVersion) ^(v)?(0|([1-9][0-9]{0,4}))(\.(0|([1-9][0-9]{0...

The version of the schema used for validating both request data sent via the PUT request as well as response data gotten from the GET request.

{
  • "version": "v1.0.0",
  • "optVersion": "1970-01-01_0p0",
  • "rev": "strings",
  • "schema": "v1.2.3"
}

ShiftPlannerOutputPlan

requestID
string

The identifier that allows finding input/output data, logs and more. This ID will be asked for in most non-trivial support cases so it should be stored when receiving the data.

object (Client)

Contains information about the client which sends this request.

required
object (ShiftPlannerMeta)

Meta information about what to consider in the optimization.

required
object (ShiftPlannerOptimizationParameters)

Parameters for the optimizer.

required
Array of ShiftPlannerOutputTaskAssigned (object) or ShiftPlannerOutputTaskUnassigned (object) (ShiftPlannerOutputTask)

Array of assigned and unassigned tasks.

required
Array of objects (ShiftPlannerOutputWorker)

Array of available Workers.

required
object (ShiftPlannerStatistics)

Some statistics about the plan.

required
object (ShiftPlannerInfo)

Some textual information about the plan.

Array of objects (Anomalies) non-empty

List of all anomalies found in solution.

required
object (BackendVersion)

Used validation/ calculation version.

recovery
Array of integers (IDReferences) [ items [ 0 .. 2147483647 ] ]
Deprecated

List of ids.

object (DeveloperOptions)

Additional debug information for developers.

{
  • "requestID": "string",
  • "client": {
    },
  • "meta": {
    },
  • "parameters": {
    },
  • "tasks": [
    ],
  • "workers": [
    ],
  • "statistics": {
    },
  • "info": {
    },
  • "anomalies": [
    ],
  • "backendVersion": {
    },
  • "recovery": [
    ],
  • "developerOptions": {
    }
}

VersionInfo

schema
string

Schema version against which input and output data are validated

version
string

Version of the application that calculates solutions

meta_data
string

Meta data version

api_scripts
string

Version of the scripts handling requests

{
  • "schema": "v1.7.0",
  • "version": "2024-10-01_0",
  • "meta_data": "v19",
  • "api_scripts": "v1.6.2"
}

PackagesList

Array
Name
required
string

Package name to use in the adiutaopt-version header

LastModified
string

Modification timestamp of the package, usually of the time it was uploaded at

object (VersionInfo)
[
  • {
    },
  • {
    }
]

Changelog

v9.3.3

  • In Client: Updated description for clientID.

v9.3.2

  • In Client: Updated description for clientID.

v9.3.1

  • In ShiftPlannerOptimizationParameters: Updated descriptions for parameter entries.

v9.2.0

  • In ShiftPlannerInputWorker: Added dontAlter.
  • In ShiftPlannerInputTask:
    • Removed "deprecated" flag from precedingTasks.
    • Added preassignedOrder.

v9.1.1

  • Marked inactive errors in error id overview

v9.1.0

  • In ShiftPlannerStatistics: Added property absolute to impact

v9.0.0

  • Added definition DeveloperOptions
  • In ErrorPlan: Added developerOptions, deprecated recovery
  • In ShiftPlannerInputPlan, ShiftPlannerOutputPlan: Added developerOptions, deprecated recovery

v8.4.0

  • In ShiftPlannerInputWorker: Added allowPreassignedTasksOnly

v8.3.0

  • In ShiftPlannerOutputTaskAssigned: Added timeWindowViolation

v7.18.2

  • In ShiftPlannerInputPlan: Updated description for history.
  • In ShiftPlannerInputTask: Updated description for preassignedWorker, initassignedWorker, predecessorTasks.
  • In ShiftPlannerOptimizationParameters: Updated description for preset.
  • Added example PredecessorChain for POST /shift-description endpoint

v7.17.0

  • Added accept and accept-encoding headers to GET /version, GET /packages-list endpoints, added 406 response code
  • Added 409 response code to all GET endpoints

v7.15.1

  • In Client: Updated description for clientID, added examples

v7.15.0

  • In ShiftPlannerInputWorker: Added preventSplitWeekends.

v7.14.1

  • Updated descriptions to include whether a field is a restriction or a preference and optionally, if the latter, what parameter influences it.

v7.14.0

  • Added definition TimeSlot, OverlapConfigType
  • In InputWorker: Added fixedPresences

v7.12.0

  • In OutputTaskAssigned, OutputTaskUnassigned: Added allowedWorkers

v7.11.0

  • In AnomalyEntry:
    • Added severity
    • Changed text to required

v7.10.0

  • In OutputPlan: Added anomalies

v7.8.0

  • Added section Index which contains all major schema defintions

v7.7.0

  • Updated 4xx and 5xx http responses with content documentation
  • Added description for PackagesList and VersionInfo component

v7.6.0

  • Added missing HEAD request documentation to GET endpoints

v7.5.0

  • Added response code 405 to all endpoints

v7.4.1

  • Updated changelog to only include changes related to the corresponding site.

v7.3.0

  • Added definition ShiftPlannerOutput:
    • Combines ShiftPlannerOutputPlan and ErrorPlan into one definition to use as schema in /plan GET response

v7.1.0

  • Added response code 429 to all POST requests
  • In ErrorPlan: Added allowRepeat

v5.2.0

  • In ShiftPlannerInputWorker:
    • Added workdayPattern.
    • Added workdayCycle.
  • In ShiftPlannerStatisticsHistoryWorkerEntry:
    • Added cycleStart

v5.1.0

  • Added new content-type options in POST requests:
    • application/vnd.adiutabyte.adiutaopt.json+gzip
    • application/vnd.adiutabyte.adiutaopt.json+deflate
    • application/vnd.adiutabyte.adiutaopt.json+br
  • Updated description for POST request, added explanations to response codes, compression and returned key
  • Added header accept-encoding in GET requests with allowed values:
    • identity
    • deflate
    • gzip
  • Added header accept in GET requests with allowed values:
    • application/json
    • application/vnd.adiutabyte.adiutaopt.json+gzip
    • application/vnd.adiutabyte.adiutaopt.json+deflate
    • application/vnd.adiutabyte.adiutaopt.json+br
  • Renamed header version to adiutaopt-version

v5.0.0

  • Restored compatibility to v3 schemata
  • In BackendVersion:
    • Changed version to be constant "v1.0.0", marked as deprecated
    • Added optVersion, has the same properties as version did in v4

v4.0.1

  • Added response codes to OPTIONS requests
  • Removed incorrect authentication details from OPTIONS requests

v4.0.0

  • Changed FieldPlacerVersion pattern to ^d{4}-d{2}-d{2}_d+(pd+)?$.

v2.9.0

  • Added header parameter Version to paths /shift-description and /shift-version
    • Updated curl/nodejs code examples to include one with the new header
  • Added path /shift-packages-list

v2.8.2

  • Fixed incorrect description in ShiftPlannerWorker: shifts

v2.8.1

  • Fixed response content type for status 200, 201 for endpoint /shift-description

v2.8.0

  • In ShiftPlannerInputWorker:
    • Added consecutiveNightShiftsForOffdays
    • Added minOffdaysAfterConsecutiveNightShifts

v2.0.0

  • Removed definition Number_u32, replaced all occurrences with Number_u64. Those are:
    • ShiftPlannerInputWorker, ShiftPlannerOutputWorker:
      • costsPerMinute
      • costsInitial
  • Added Number_s64
  • Removed definition Number_s32, replaced all occurrences with Number_s64. Those are:
    • ShiftPlannerOutputTaskAssigned:
      • profit
  • Fixed incorrect type of ShiftPlannerInputTask/ShiftPlannerOutputTask: revenue, changed it from Number_s32 to Number_u64

v1.14.0

  • In ErrorPlan
    • Added recovery

v1.13.0

  • In ShiftPlannerInputPlan, ShiftPlannerOutputPlan:
    • Added recovery

v1.12.0

  • In ShiftPlannerInputWorker:
    • Added maxDailyTasks

v1.11.0

  • In ShiftPlannerMeta:
    • Added new field removeInvalidTasks

v1.10.0

  • Added definition ShiftPlannerStatisticsPreferencesMatches
  • In ShiftPlannerStatistics:
    • Added preferredWorkers
    • Added unpreferredWorkers
  • In ShiftPlannerOutputWorker:
    • Added totalTaskTime

v1.9.0

  • In ShiftPlannerInputTask, ShiftPlannerInputWorker:
    • Added unpreferredWorkers
    • Marked antiWorkers as deprecated
  • Added some missing default values

v1.8.1

  • Added missing return codes 400, 413 to endpoints for posting new optimization requests

v1.7.3

  • Added missing return code 401 to all endpoints

v1.7.1

  • Minor (non-functional) rework of ErrorEntry
  • Minor (non-functional) rework of ShiftPlannerInputTask, ShiftPlannerInputWorker
  • Fixed unevaluated properties being allowed in:
    • ErrorPlan
  • Fixed unevaluated properties being allowed in:
    • ShiftPlannerOutputTaskAssigned
    • ShiftPlannerOutputTaskUnassigned
    • ShiftPlannerOutputWorker