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

MixedPlannerVehicleType

integer (MixedPlannerVehicleType) [ 0 .. 4 ]

An integer representing the vehicle type:

  • 0: Car
  • 1: Bicycle
  • 2: Pedestrian
  • 3: Truck
  • 4: Public Transport Approximation
4

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 (MixedPlannerMeta)

Meta information about what to consider in the optimization.

required
object (MixedPlannerOptimizationParameters)

Parameters for the optimizer.

required
Array of objects (MixedPlannerInputTask)

Array of tasks to be planned by the optimizer.

required
Array of objects (MixedPlannerInputWorker)

Array of available workers.

Array of objects (MixedPlannerLocationSite)

Array of available location sites.

object (MixedPlannerHistory)

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.

object (MixedPlannerTravelOverride)

Manual distance matrix data

Array of objects or objects (MixedPlannerObstacle)
Deprecated

Obstacles for the travel calculation.

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

A basic TSP

{
  • "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": [
    ],
  • "locationSites": [
    ],
  • "obstacles": [
    ],
  • "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

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

MixedPlannerMeta

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

Planning horizon start, usually the earliest date on any of the tasks.

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

Planning horizon end, usually the latest date on any of the tasks.

resCapacity
boolean
Default: false

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

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.

postProcessing
boolean
Default: false

Enables dynamic traffic for calculating travel times (e.g. rush hour). Recommended for use cases where such dynamic travel times actually make a difference, otherwise leave it at false or carefully evaluate outcomes.

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.

tightSchedule
boolean
Default: false

If set to true, any buffer between tasks (time spent neither working, driving, nor on break) is avoided if possible. Tasks with a timePriority less than 3 can be moved to earlier than their time window if necessary.

tourStartsOnShiftStart
boolean
Default: false

Per default, the worker tour starts not at their shiftStart but the first task carried out by the worker. If the use case demands that a worker start at their given shiftStart, this flag can be set to true.

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

A global lower limit to travel time, travel times below this will be raised.

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

Alias for minTravelTime, does the same thing

integrateDurationExtensions
boolean
Deprecated
integrateGermanBreakRegulations
boolean
Default: false

Adds mandatory breaks to workers according to the German Working Time Act if set. Using manual breaks is recommended whenever possible.

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.

useInitialClustering
boolean
Default: false

Use only clustering as a first optimization step instead of the default algorithms. Developer feature, use at your own risk!

dontOptimizeResets
boolean
Default: false

Per default, travel from and to capacity reset locations is part of the optimization. This option prevents considering these travels in the optimization.

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.

useDensityClustering
boolean
Default: false

Uses a location-based density-clustering to restrict the possible solution space, potentially saving runtime and improving solution quality under certain conditions.

disableTaskTimeWindowRelaxation
boolean
Default: false

Per default, time windows of tasks are slightly relaxed before optimization depending on their timePriority. This usually creates better results as it is common that customer declared time windows are tighter than what they would actually accept as a good scheduling. However, if the time windows are indeed reliable and can be used without modification, the relaxation is no longer necessary or beneficial and can be turned off with this flag.

{
  • "dateFrom": "2020-04-10",
  • "dateTo": "2020-04-10",
  • "resCapacity": false,
  • "resCategory": false,
  • "resQualification": false,
  • "postProcessing": false,
  • "accuracyMode": 1.7e+308,
  • "outputLanguage": 1,
  • "tightSchedule": false,
  • "tourStartsOnShiftStart": false,
  • "minTravelTime": 2147483647,
  • "travelTimeMin": 2147483647,
  • "integrateDurationExtensions": true,
  • "integrateGermanBreakRegulations": false,
  • "enablePlanSplitting": true,
  • "allowUnassignedTasks": false,
  • "removeInvalidTasks": true,
  • "useInitialClustering": false,
  • "dontOptimizeResets": false,
  • "minConcurrentSolutions": 1,
  • "minTaskDuration": 2147483647,
  • "useDensityClustering": false,
  • "disableTaskTimeWindowRelaxation": false
}

MixedPlannerOptimizationParameters

preset
integer [ 0 .. 4 ]

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

Preset descriptions:

Preset 0 (Eco Oriented):

  • shortPaths: 9
  • timeliness: 5
  • profitability: 9

Preset 1 (Worker Oriented):

  • fairDistribution: 9
  • shortPaths: 5
  • timeliness: 4
  • workerPref: 4
  • profitability: 4

Preset 2 (Customer Oriented):

  • shortPaths: 2
  • timeliness: 9
  • workerPref: 7
  • profitability: 2

Preset 3 (Fleet Oriented):

  • shortPaths: 5
  • timeliness: 2
  • workerReduction: 9
  • profitability: 2

Preset 4 (Random):

  • The values shortPaths, timeliness are set to a random value 1 to 9.
  • The values fairDistribution, workerPrefs, workerReduction, profitability are set to a random value 0 to 9.

Preset 4 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 ratio of total task duration to shift length. Consequently, only tasks with non-zero durations affect the fair distribution.

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

Build local clusters for the workers to work within if possible.

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

Calculate a solution with low total travel time.

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

Optimize towards fulfilling time windows.

travelTimeRelax
integer (Integer_0_9) [ 0 .. 9 ]
Deprecated

An integer 0-9

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

Try to satisfy any tasks' worker preferences.

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

Reduce the number of necessary workers by creating imbalanced schedules with respect to task duration. This requires the tasks to have durations greater than zero.

workTimeRelax
integer (Integer_0_9) [ 0 .. 9 ]
Deprecated

An integer 0-9

genderPref
integer (Integer_0_9) [ 0 .. 9 ]
Deprecated

An integer 0-9

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

Optimize towards high profitability. This requires workers to have costs or, if allowUnassignedTasks: true, tasks to have revenue to have an effect.

{
  • "preset": 4,
  • "fairDistribution": 9,
  • "localityClustering": 9,
  • "shortPaths": 9,
  • "timeliness": 9,
  • "travelTimeRelax": 9,
  • "workerPrefs": 9,
  • "workerReduction": 9,
  • "workTimeRelax": 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"

GeoCoord

lat
required
number [ -90 .. 90 ]

latitude

lng
required
number [ -180 .. 180 ]

longitude

{
  • "lat": -90,
  • "lng": -180
}

IDReferences

Array
integer (Integer_u32) [ 0 .. 2147483647 ]

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

[
  • 2147483647
]

Number_s64

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

Signed 64bit number

-1.7e+308

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

MixedPlannerInputTask

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

The ID of this task. Task IDs need to be unique for all tasks in the input data

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.

clientID
integer (Integer_u32) [ 0 .. 2147483647 ]

A unique id to identify a client to whom different tasks can be attributed. Only use when instructed to do so.

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

A time for identifying history assignments. Only use when instructed to do so.

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

The date for the day to be planned.

duration
integer (Integer_u32) [ 0 .. 2147483647 ]

The time in minutes it takes to complete this task. Exactly one of duration and durationInSeconds must be set, it can be set to zero though.

durationInSeconds
integer (Integer_u32) [ 0 .. 2147483647 ]

The time in seconds it takes to complete this task. Exactly one of duration and durationInSeconds must be set, it can be set to zero though.

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.

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

The start of the forbidden time window. Tasks will not be carried out in the forbidden time window and will be scheduled either completely before or after integrations.

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

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

The end of the forbidden time window. Tasks will not be carried out in the forbidden time window and will be scheduled either completely before or after it.

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

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

The priority of the time window:

  • 0 - irrelevant
  • 1 - not important (automatically extended by 30 minutes)
  • 2 - more important (automatically extended by 15 minutes)
  • 3 - important (no extension)
  • 4 - very important (no extension)
  • 5 - fixed time (no extension)

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 5, the time window is considered a strict restriction.

object (GeoCoord)

The coordinates where the task has to be performed. Not defining a location will allow the task to be performed anywhere.

locationSiteID
integer (Integer_u32) [ 0 .. 2147483647 ]

The ID of the location site that will be used as location

object (GeoCoord)

The coordinates where the task will end. Moving between location and finishLocation occurs during the duration and does not count as travel.

finishLocationSiteID
integer (Integer_u32) [ 0 .. 2147483647 ]

The ID of the location site that will be used as finishLocation.

rotatable
boolean
Default: false

If set to true, the algorithm can swap location and finishLocation (or corresponding locationSiteID) depending on what creates a better solution, similar to "rotating" the task in place.

description
string
Deprecated
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 workerPrefs.

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 workerPrefs.

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

Alias for unpreferredWorkers.

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.

capacity
number (Number_s64) [ -1.7e+308 .. 1.7e+308 ]
Default: 0

The capacity requirement of this task, which the assigned worker will need to provide.

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

weight
number (Number_s64) [ -1.7e+308 .. 1.7e+308 ]
Default: 0

The weight requirement of this task, which the assigned worker will need to provide.

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

volume
number (Number_s64) [ -1.7e+308 .. 1.7e+308 ]
Default: 0

The volume requirement of this task, which the assigned worker will need to provide.

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

qualification
integer (Integer_u32) [ 0 .. 2147483647 ]

The minimum qualification of the employee required to perform the task (e.g. years of experience). The algorithm tries to avoid high discrepancies between worker and task qualification. The importance of avoiding overqualification depends on the parameter profitability.

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.

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

Categories of other tasks which exclude joint performance with this task.

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.

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

The assigned worker will need to perform at least two tasks with each 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 dontAlter and dontVary assignments as well as preassignedOrder. A preassignedWorker does not imply an assignmentPriority - if allowUnassignedTasks is active, the task being unassigned is not a violation of this restriction.

When there are multiple workers with the same workerID:

  • if the task only has preassignedWorker set, the task can be assigned to any of the workers with that workerID, regardless of what their shiftIDs are (or if they have one)
  • if the task has an initassignedShift set as well as preassignedWorker, the task can only be assigned to the worker that matches the workerID to preassignedWorker and the shiftID to initassignedShift

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 to the start of the tour of the preassignedWorker, tasks with a value < 0 to the end. If multiple tasks preassigned to a worker have a preassignedOrder, the tasks will be sorted so that the preassignedOrder is increasing (tasks at the front of the tour and tasks at the end of the tour separately).

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.

initassignedOrder
integer (Integer_u32) [ 0 .. 2147483647 ]

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

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 dontAlter and dontVary assignments.

initassignedShiftID
integer (Integer_u32) [ 0 .. 2147483647 ]

A shiftID to compliment either initassignedWorker or preassignedWorker in case the workerID is not unique.

prefGender
integer (GenderType) [ 0 .. 3 ]

The assigned worker needs to have this gender.

This is a weak restriction 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.

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

The revenue which will be achieved with this task.

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

Fixed amount of time added to this task's travel time.

group
integer (Integer_u32) [ 0 .. 2147483647 ]

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

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

predecessorGroup
integer (Integer_u32) [ 0 .. 2147483647 ]

Tasks with the same 'predecessorGroup' ID will be scheduled as a single batch of tasks without any tasks with different or no predecessorGroupIDs scheduled between them. The order of tasks within a batch can vary.

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

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 must 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.

ignoreHistory
boolean
Default: false

If true, this tasks get ignored in all history analysis

{
  • "taskID": 2147483647,
  • "externalID": "string",
  • "clientID": 2147483647,
  • "baseScheduleTime": "07:25",
  • "date": "2020-04-10",
  • "duration": 2147483647,
  • "durationInSeconds": 2147483647,
  • "timeEarliest": "07:25",
  • "timeLatest": "07:25",
  • "forbTimeEarliest": "07:25",
  • "forbTimeLatest": "07:25",
  • "timePriority": 5,
  • "location": {
    },
  • "locationSiteID": 2147483647,
  • "finishLocation": {
    },
  • "finishLocationSiteID": 2147483647,
  • "rotatable": false,
  • "description": "string",
  • "prefWorkers": [
    ],
  • "unpreferredWorkers": [
    ],
  • "antiWorkers": [
    ],
  • "forbWorkers": [
    ],
  • "capacity": -1.7e+308,
  • "weight": -1.7e+308,
  • "volume": -1.7e+308,
  • "qualification": 2147483647,
  • "categories": [
    ],
  • "antiCategories": [
    ],
  • "exchangeableCategories": [
    ],
  • "twinCategories": [
    ],
  • "preassignedWorker": 2147483647,
  • "preassignedOrder": -2147483648,
  • "desiredWorker": 2147483647,
  • "initassignedOrder": 2147483647,
  • "initassignedWorker": 2147483647,
  • "initassignedShiftID": 2147483647,
  • "prefGender": 3,
  • "precedingTasks": [
    ],
  • "predecessorTasks": [
    ],
  • "revenue": 1.7e+308,
  • "travelTimeExtra": 2147483647,
  • "group": 2147483647,
  • "predecessorGroup": 2147483647,
  • "assignmentPriority": 5,
  • "ignoreHistory": false
}

MixedPlannerVehicleType

integer (MixedPlannerVehicleType) [ 0 .. 4 ]

An integer representing the vehicle type:

  • 0: Car
  • 1: Bicycle
  • 2: Pedestrian
  • 3: Truck
  • 4: Public Transport Approximation
4

MixedPlannerInputWorker

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

The ID of the worker. Multiple workers with identical ID are allowed, those represent multiple "shifts" of the same person.

shiftID
integer (Integer_u32) [ 0 .. 2147483647 ]

A second ID in case there are multiple workers with the same workerID. This one needs to be unique among all workers with the same workerID. It can be referenced whenever a unique reference to this worker object is required.

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.

object (GeoCoord)

The location where the worker begins their working day. Leaving it empty means the worker starts on the location of their first task, this can be used in situations where workers start their day at home and any travel time to their first client does not count as working time.

startLocationSiteID
integer (Integer_u32) [ 0 .. 2147483647 ]

The ID of the location site that will be used as startLocation.

object (GeoCoord)

The location where the worker finishes their working day. Leaving it empty means the worker will end their tour at their last task, this can be used in situations where travel time home does not count as working time.

endLocationSiteID
integer (Integer_u32) [ 0 .. 2147483647 ]

The ID of the location site that will be used as endLocation.

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

The date of this shift.

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

The time this shift starts.

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

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

The time this shift ends.

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

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

The priority to keep the defined shift start and end times:

  • 0 - irrelevant
  • 1 - neutral
  • 2 - important
  • 3 - very important.
hoursPerWeek
integer [ 1 .. 90 ]
Deprecated
capacity
number (Number_u64) [ 0 .. 1.7e+308 ]
Default: 0

The available capacity of the worker or their vehicle.

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

The initially occupied capacity on shift start of this worker or their vehicle.

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

If during the tour the worker capacity gets filled up and this field is set, the worker will travel to the best available location sites in the given list and unload all their stored capacity, weight, and volume before traveling to the next task.

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

The time in minutes needed for a capacity reset.

maxResets
integer (Integer_u32) [ 0 .. 2147483647 ]

The maximum number of allowed capacity resets on this worker.

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

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

The available volume of the worker or their vehicle.

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

The initially loaded volume on shift start of this worker or their vehicle.

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

The weight the worker or their vehicle is able to handle.

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

The initially loaded weight on shift start of this worker or their vehicle.

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

If at the end of the worker's tour the current capacity exceeds this threshold, a final reset is automatically added.

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

If at the end of the worker's tour the current weight exceeds this threshold, a final reset is automatically added.

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

If at the end of the worker's tour the current volume exceeds this threshold, a final reset is automatically added.

qualification
integer (Integer_u32) [ 0 .. 2147483647 ]

The qualification of the worker. Workers can perform any task with equal or lower qualification requirement, the optimizer tried to not "overqualify" workers for tasks by keeping worker and task qualification close.

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 categories listed here is automatically considered valid as if they're listed in categories.

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

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

Tasks with any of these categories will be preferred by this worker. Categories listed here are automatically considered valid as if they're listed in categories.

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

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

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

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

The earliest start of the break a worker has to do.

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

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

The latest end of the break a worker has to do.

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

breakDuration
integer (Integer_u32) [ 0 .. 2147483647 ]

The duration in minutes of the break.

noAutomaticBreak
boolean
Default: false

If integrateGermanBreakDurations is set to true, this can flag can be used to exempt the worker from being assigned an automatic break. By setting the value to true, no automatic break is added. If either a manual break is specified or integrateGermanBreakDurations is false, this flag has no effect and should not be used.

vehicleType
integer (MixedPlannerVehicleType) [ 0 .. 4 ]
Default: 0

The vehicle type used by this worker.

gender
integer (GenderType) [ 0 .. 3 ]

The gender type of the worker.

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

The costs per km for this worker (e.g. fuel costs).

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.

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

The maximum total travel distance per shift that a worker wants to perform.

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

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

The maximum travel distance for each individual travel that a worker wants to perform.

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

dontVary
boolean
Default: false

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, as well as shiftID on the worker and initassignedShiftID on the task if the workerID is not unique. Travel times, resets, etc still get 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.

expectedWorkingMinutes
integer (Integer_u32) [ 0 .. 2147483647 ]

The target value for working time (tourStart until tourEnd) for this worker.

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

maxAssignableTasks
integer (Integer_u32) [ 0 .. 2147483647 ]

The maximum number of tasks that can be assigned to this worker.

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

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

The minimum number of tasks that must be assigned to this worker.

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

{
  • "workerID": 2147483647,
  • "shiftID": 2147483647,
  • "externalID": "string",
  • "startLocation": {
    },
  • "startLocationSiteID": 2147483647,
  • "endLocation": {
    },
  • "endLocationSiteID": 2147483647,
  • "shiftDate": "2020-04-10",
  • "shiftStart": "07:25",
  • "shiftEnd": "07:25",
  • "shiftPriority": 3,
  • "hoursPerWeek": 1,
  • "capacity": 1.7e+308,
  • "capacityInitial": 1.7e+308,
  • "capacityResetLocationSiteIDs": [
    ],
  • "capacityResetDuration": 2147483647,
  • "maxResets": 2147483647,
  • "volume": 1.7e+308,
  • "volumeInitial": 1.7e+308,
  • "weight": 1.7e+308,
  • "weightInitial": 1.7e+308,
  • "finalCapacityResetThreshold": 1.7e+308,
  • "finalVolumeResetThreshold": 1.7e+308,
  • "finalWeightResetThreshold": 1.7e+308,
  • "qualification": 2147483647,
  • "categories": [
    ],
  • "desiredCategory": 2147483647,
  • "prefCategories": [
    ],
  • "breakLocationSiteID": 2147483647,
  • "breakStartEarliest": "07:25",
  • "breakEndLatest": "07:25",
  • "breakDuration": 2147483647,
  • "noAutomaticBreak": false,
  • "vehicleType": 4,
  • "gender": 3,
  • "costsPerKM": 1.7e+308,
  • "costsPerMinute": 1.7e+308,
  • "costsInitial": 1.7e+308,
  • "maxDesiredTotalDistance": 1.7e+308,
  • "maxDesiredSingleDistance": 1.7e+308,
  • "dontVary": false,
  • "dontAlter": false,
  • "allowPreassignedTasksOnly": false,
  • "expectedWorkingMinutes": 2147483647,
  • "maxAssignableTasks": 2147483647,
  • "minAssignableTasks": 2147483647
}

MixedPlannerLocationSite

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

The ID of the location site. IDs need to be unique among all locationSite entries.

required
object (GeoCoord)

Coordinates of the location site.

externalID
string

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

{
  • "locationSiteID": 2147483647,
  • "location": {
    },
  • "externalID": "string"
}

MixedPlannerHistoryAssignment

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

Date this assignment was on.

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

A baseline orientation when the corresponding task was supposed to be scheduled.

baseWorker
integer (Integer_u32) [ 0 .. 2147483647 ]

A baseline orientation for the worker to be assigned.

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

The time the corresponding task was scheduled (meaning the time the final plan had this task scheduled on, not to be confused with actualStartTime).

assignedWorker
integer (Integer_u32) [ 0 .. 2147483647 ]

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

assignedShiftID
integer (Integer_u32) [ 0 .. 2147483647 ]

The ID of the assigned shift of the assigned worker.

timeVariance
integer (Integer_u32) [ 0 .. 2147483647 ]

The time variance the corresponding task was scheduled with at the time.

timePriority
integer (Integer_0_5) [ 0 .. 5 ]

The timePriority the corresponding task was scheduled with at the time.

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

The time the corresponding task was scheduled on by the optimizer at the time.

assignedWorkerAutomatically
integer (Integer_u32) [ 0 .. 2147483647 ]

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

assignedShiftIDAutomatically
integer (Integer_u32) [ 0 .. 2147483647 ]

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

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.

actualWorker
integer (Integer_u32) [ 0 .. 2147483647 ]

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

actualShiftID
integer (Integer_u32) [ 0 .. 2147483647 ]

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

prevTask
integer (Integer_u32) [ 0 .. 2147483647 ]

The task that was assigned directly before this task at the time. (If that task is present in either history or planning tasks).

prevTaskAutomatically
integer (Integer_u32) [ 0 .. 2147483647 ]

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

prevActualTask
integer (Integer_u32) [ 0 .. 2147483647 ]

The task that was carried out directly before this task at the time. (If that task is present in either history or planning tasks)

{
  • "date": "2020-04-10",
  • "baseScheduleTime": "07:25",
  • "baseWorker": 2147483647,
  • "timeScheduled": "07:25",
  • "assignedWorker": 2147483647,
  • "assignedShiftID": 2147483647,
  • "timeVariance": 2147483647,
  • "timePriority": 5,
  • "timeScheduledAutomatically": "07:25",
  • "assignedWorkerAutomatically": 2147483647,
  • "assignedShiftIDAutomatically": 2147483647,
  • "actualStartTime": "07:25",
  • "actualWorker": 2147483647,
  • "actualShiftID": 2147483647,
  • "prevTask": 2147483647,
  • "prevTaskAutomatically": 2147483647,
  • "prevActualTask": 2147483647
}

MixedPlannerHistoryTask

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

Task ID for referencing task in planning tasks.

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

Client ID for referencing tasks in planning tasks.

required
Array of objects (MixedPlannerHistoryAssignment)

All considered historical assignments of this task.

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

MixedPlannerHistoryWorker

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

ID of a worker that is not present in the input data. Has to be unique among all history workers.

gender
integer (GenderType) [ 0 .. 3 ]

Same as in input worker.

qualification
integer (Integer_u32) [ 0 .. 2147483647 ]

Same as in input worker.

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

Same as in input worker.

{
  • "workerID": 2147483647,
  • "gender": 3,
  • "qualification": 2147483647,
  • "categories": [
    ]
}

MixedPlannerHistory

required
Array of objects (MixedPlannerHistoryTask)

All tasks that are connected to tasks in the optimization either by taskID or clientID.

required
Array of objects (MixedPlannerHistoryWorker)

Workers that are not included in the optimization but are referenced in history-tasks, e.g. as assignedWorker

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

MixedPlannerTravelOverride

Array of objects (MixedPlannerTravelOverrideDense)

Dense travel override to set distance matrix for the entire data set.

Array of objects (MixedPlannerTravelOverrideSparse)

Sparse travel override to set individual distance matrix override for a few travels.

{
  • "dense": [
    ],
  • "sparse": [
    ]
}

Fraction

number (Fraction) [ 0 .. 1 ]
1

MixedPlannerObstacle

One of
type
required
string
Enum: "polygon" "polyline"

Obstacle type, can be either a 1D-polyline or a 2D-polygon.

Value: "polyline"
required
Array of objects >= 2 items

Coordinates of the polygon/polyline.

description
string

Textual information to this obstacle.

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

Travel through this obstacle creates travel time increase by this factor.

restriction
number (Fraction) [ 0 .. 1 ]

Travel through this obstacle is forbidden, regardless of which value is set. Should be used with 1.0.

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

Flat travel time increase in minutes when traveling through obstacle.

{
  • "type": "polygon",
  • "points": [
    ],
  • "description": "string",
  • "factor": 1.7e+308,
  • "restriction": 1,
  • "travelTimeIncrease": 1.7e+308
}

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"
}

MixedPlannerInputPlan

object (Client)

Contains information about the client which sends this request.

required
object (MixedPlannerMeta)

Meta information about what to consider in the optimization.

required
object (MixedPlannerOptimizationParameters)

Parameters for the optimizer.

required
Array of objects (MixedPlannerInputTask)

Array of tasks to be planned by the optimizer.

required
Array of objects (MixedPlannerInputWorker)

Array of available workers.

Array of objects (MixedPlannerLocationSite)

Array of available location sites.

object (MixedPlannerHistory)

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.

object (MixedPlannerTravelOverride)

Manual distance matrix data

Array of objects or objects (MixedPlannerObstacle)
Deprecated

Obstacles for the travel calculation.

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": [
    ],
  • "locationSites": [
    ],
  • "history": {
    },
  • "travelOverride": {
    },
  • "obstacles": [
    ],
  • "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
}

MixedPlannerOutputTaskAssigned

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

The ID of this task. Task IDs need to be unique for all tasks in the input data

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.

clientID
integer (Integer_u32) [ 0 .. 2147483647 ]

A unique id to identify a client to whom different tasks can be attributed. Only use when instructed to do so.

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

A time for identifying history assignments. Only use when instructed to do so.

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

The date for the day to be planned.

duration
integer (Integer_u32) [ 0 .. 2147483647 ]

The time in minutes it takes to complete this task. Exactly one of duration and durationInSeconds must be set, it can be set to zero though.

durationInSeconds
integer (Integer_u32) [ 0 .. 2147483647 ]

The time in seconds it takes to complete this task. Exactly one of duration and durationInSeconds must be set, it can be set to zero though.

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.

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

The start of the forbidden time window. Tasks will not be carried out in the forbidden time window and will be scheduled either completely before or after integrations.

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

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

The end of the forbidden time window. Tasks will not be carried out in the forbidden time window and will be scheduled either completely before or after it.

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

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

The priority of the time window:

  • 0 - irrelevant
  • 1 - not important (automatically extended by 30 minutes)
  • 2 - more important (automatically extended by 15 minutes)
  • 3 - important (no extension)
  • 4 - very important (no extension)
  • 5 - fixed time (no extension)

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 5, the time window is considered a strict restriction.

object (GeoCoord)

The coordinates where the task has to be performed. Not defining a location will allow the task to be performed anywhere.

locationSiteID
integer (Integer_u32) [ 0 .. 2147483647 ]

The ID of the location site that will be used as location

object (GeoCoord)

The coordinates where the task will end. Moving between location and finishLocation occurs during the duration and does not count as travel.

finishLocationSiteID
integer (Integer_u32) [ 0 .. 2147483647 ]

The ID of the location site that will be used as finishLocation.

rotatable
boolean
Default: false

If set to true, the algorithm can swap location and finishLocation (or corresponding locationSiteID) depending on what creates a better solution, similar to "rotating" the task in place.

description
string
Deprecated
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 workerPrefs.

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 workerPrefs.

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

Alias for unpreferredWorkers.

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.

capacity
number (Number_s64) [ -1.7e+308 .. 1.7e+308 ]
Default: 0

The capacity requirement of this task, which the assigned worker will need to provide.

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

weight
number (Number_s64) [ -1.7e+308 .. 1.7e+308 ]
Default: 0

The weight requirement of this task, which the assigned worker will need to provide.

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

volume
number (Number_s64) [ -1.7e+308 .. 1.7e+308 ]
Default: 0

The volume requirement of this task, which the assigned worker will need to provide.

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

qualification
integer (Integer_u32) [ 0 .. 2147483647 ]

The minimum qualification of the employee required to perform the task (e.g. years of experience). The algorithm tries to avoid high discrepancies between worker and task qualification. The importance of avoiding overqualification depends on the parameter profitability.

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.

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

Categories of other tasks which exclude joint performance with this task.

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.

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

The assigned worker will need to perform at least two tasks with each 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 dontAlter and dontVary assignments as well as preassignedOrder. A preassignedWorker does not imply an assignmentPriority - if allowUnassignedTasks is active, the task being unassigned is not a violation of this restriction.

When there are multiple workers with the same workerID:

  • if the task only has preassignedWorker set, the task can be assigned to any of the workers with that workerID, regardless of what their shiftIDs are (or if they have one)
  • if the task has an initassignedShift set as well as preassignedWorker, the task can only be assigned to the worker that matches the workerID to preassignedWorker and the shiftID to initassignedShift

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 to the start of the tour of the preassignedWorker, tasks with a value < 0 to the end. If multiple tasks preassigned to a worker have a preassignedOrder, the tasks will be sorted so that the preassignedOrder is increasing (tasks at the front of the tour and tasks at the end of the tour separately).

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.

initassignedOrder
integer (Integer_u32) [ 0 .. 2147483647 ]

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

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 dontAlter and dontVary assignments.

initassignedShiftID
integer (Integer_u32) [ 0 .. 2147483647 ]

A shiftID to compliment either initassignedWorker or preassignedWorker in case the workerID is not unique.

prefGender
integer (GenderType) [ 0 .. 3 ]

The assigned worker needs to have this gender.

This is a weak restriction 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.

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

The revenue which will be achieved with this task.

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

Fixed amount of time added to this task's travel time.

group
integer (Integer_u32) [ 0 .. 2147483647 ]

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

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

predecessorGroup
integer (Integer_u32) [ 0 .. 2147483647 ]

Tasks with the same 'predecessorGroup' ID will be scheduled as a single batch of tasks without any tasks with different or no predecessorGroupIDs scheduled between them. The order of tasks within a batch can vary.

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

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 must 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.

ignoreHistory
boolean
Default: false

If true, this tasks get ignored in all history analysis

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.
travelTime
required
integer (Integer_u32) [ 0 .. 2147483647 ]

The time in minutes needed to travel from the previous task to this task. If a reset is performed (performResetBeforeAtID is set), this includes the travel to a capacity reset location as well as the reset duration (capacityResetDuration). Travel modifiers like minTravelTime and travelTimeExtra are also considered.

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

The distance in km needed to travel from the previous task to this task. The same rules as travelTime apply.

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

The ID (workerID) of the assigned worker who will perform this task.

assignedShiftID
integer (Integer_u32) [ 0 .. 2147483647 ]

The shiftID to which the task is assigned to.

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

The order number within the assigned tour..

info
required
string

Additional information about the task.

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

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

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

The profit the task creates (revenue - costs).

performResetBeforeAtID
integer (Integer_u32) [ 0 .. 2147483647 ]

The id of the location site which will be visited to reset capacity/weight/volume before this task starts.

travelTimeToReset
integer (Integer_u32) [ 0 .. 2147483647 ]

If a capacity reset is performed right before this task (performResetBeforeAtID is set), this value contains the travel time to the reset location. Subtracting this value and capacityResetDuration from travelTime nets the travel time from the reset location to this task.

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

If a capacity reset is performed right before this task (performResetBeforeAtID is set), this value contains the travel distance to the reset location. Subtracting this value from travelDistance nets the travel distance from the reset location to this task.

rotated
boolean

If true, the rotation described in rotatable has occurred, meaning the task starts at its finishLocation and ends at its location. The field is only included if rotatable is set to true.

gapBeforeTask
integer (Integer_u32) [ 0 .. 2147483647 ]

The "empty" time between this task and the one before it (time not covered by the task, travel, capacity reset or break). If this task is the first on the assigned worker and tourStartsWithShiftStart is false, the field does not get printed. If this task is the first on the assigned worker and tourStartsWithShiftStart is true, it contains the gap minutes to the worker's shiftStart.

{
  • "taskID": 2147483647,
  • "externalID": "string",
  • "clientID": 2147483647,
  • "baseScheduleTime": "07:25",
  • "date": "2020-04-10",
  • "duration": 2147483647,
  • "durationInSeconds": 2147483647,
  • "timeEarliest": "07:25",
  • "timeLatest": "07:25",
  • "forbTimeEarliest": "07:25",
  • "forbTimeLatest": "07:25",
  • "timePriority": 5,
  • "location": {
    },
  • "locationSiteID": 2147483647,
  • "finishLocation": {
    },
  • "finishLocationSiteID": 2147483647,
  • "rotatable": false,
  • "description": "string",
  • "prefWorkers": [
    ],
  • "unpreferredWorkers": [
    ],
  • "antiWorkers": [
    ],
  • "forbWorkers": [
    ],
  • "capacity": -1.7e+308,
  • "weight": -1.7e+308,
  • "volume": -1.7e+308,
  • "qualification": 2147483647,
  • "categories": [
    ],
  • "antiCategories": [
    ],
  • "exchangeableCategories": [
    ],
  • "twinCategories": [
    ],
  • "preassignedWorker": 2147483647,
  • "preassignedOrder": -2147483648,
  • "desiredWorker": 2147483647,
  • "initassignedOrder": 2147483647,
  • "initassignedWorker": 2147483647,
  • "initassignedShiftID": 2147483647,
  • "prefGender": 3,
  • "precedingTasks": [
    ],
  • "predecessorTasks": [
    ],
  • "revenue": 1.7e+308,
  • "travelTimeExtra": 2147483647,
  • "group": 2147483647,
  • "predecessorGroup": 2147483647,
  • "assignmentPriority": 5,
  • "ignoreHistory": false,
  • "timeScheduled": "07:25",
  • "timeWindowViolation": -2147483648,
  • "travelTime": 2147483647,
  • "travelDistance": 1.7e+308,
  • "assignedWorker": 2147483647,
  • "assignedShiftID": 2147483647,
  • "finalassignedOrder": 1,
  • "info": "string",
  • "allowedWorkers": [
    ],
  • "profit": -1.7e+308,
  • "performResetBeforeAtID": 2147483647,
  • "travelTimeToReset": 2147483647,
  • "travelDistanceToReset": 1.7e+308,
  • "rotated": true,
  • "gapBeforeTask": 2147483647
}

MixedPlannerOutputTaskUnassigned

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

The ID of this task. Task IDs need to be unique for all tasks in the input data

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.

clientID
integer (Integer_u32) [ 0 .. 2147483647 ]

A unique id to identify a client to whom different tasks can be attributed. Only use when instructed to do so.

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

A time for identifying history assignments. Only use when instructed to do so.

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

The date for the day to be planned.

duration
integer (Integer_u32) [ 0 .. 2147483647 ]

The time in minutes it takes to complete this task. Exactly one of duration and durationInSeconds must be set, it can be set to zero though.

durationInSeconds
integer (Integer_u32) [ 0 .. 2147483647 ]

The time in seconds it takes to complete this task. Exactly one of duration and durationInSeconds must be set, it can be set to zero though.

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.

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

The start of the forbidden time window. Tasks will not be carried out in the forbidden time window and will be scheduled either completely before or after integrations.

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

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

The end of the forbidden time window. Tasks will not be carried out in the forbidden time window and will be scheduled either completely before or after it.

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

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

The priority of the time window:

  • 0 - irrelevant
  • 1 - not important (automatically extended by 30 minutes)
  • 2 - more important (automatically extended by 15 minutes)
  • 3 - important (no extension)
  • 4 - very important (no extension)
  • 5 - fixed time (no extension)

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 5, the time window is considered a strict restriction.

object (GeoCoord)

The coordinates where the task has to be performed. Not defining a location will allow the task to be performed anywhere.

locationSiteID
integer (Integer_u32) [ 0 .. 2147483647 ]

The ID of the location site that will be used as location

object (GeoCoord)

The coordinates where the task will end. Moving between location and finishLocation occurs during the duration and does not count as travel.

finishLocationSiteID
integer (Integer_u32) [ 0 .. 2147483647 ]

The ID of the location site that will be used as finishLocation.

rotatable
boolean
Default: false

If set to true, the algorithm can swap location and finishLocation (or corresponding locationSiteID) depending on what creates a better solution, similar to "rotating" the task in place.

description
string
Deprecated
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 workerPrefs.

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 workerPrefs.

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

Alias for unpreferredWorkers.

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.

capacity
number (Number_s64) [ -1.7e+308 .. 1.7e+308 ]
Default: 0

The capacity requirement of this task, which the assigned worker will need to provide.

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

weight
number (Number_s64) [ -1.7e+308 .. 1.7e+308 ]
Default: 0

The weight requirement of this task, which the assigned worker will need to provide.

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

volume
number (Number_s64) [ -1.7e+308 .. 1.7e+308 ]
Default: 0

The volume requirement of this task, which the assigned worker will need to provide.

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

qualification
integer (Integer_u32) [ 0 .. 2147483647 ]

The minimum qualification of the employee required to perform the task (e.g. years of experience). The algorithm tries to avoid high discrepancies between worker and task qualification. The importance of avoiding overqualification depends on the parameter profitability.

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.

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

Categories of other tasks which exclude joint performance with this task.

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.

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

The assigned worker will need to perform at least two tasks with each 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 dontAlter and dontVary assignments as well as preassignedOrder. A preassignedWorker does not imply an assignmentPriority - if allowUnassignedTasks is active, the task being unassigned is not a violation of this restriction.

When there are multiple workers with the same workerID:

  • if the task only has preassignedWorker set, the task can be assigned to any of the workers with that workerID, regardless of what their shiftIDs are (or if they have one)
  • if the task has an initassignedShift set as well as preassignedWorker, the task can only be assigned to the worker that matches the workerID to preassignedWorker and the shiftID to initassignedShift

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 to the start of the tour of the preassignedWorker, tasks with a value < 0 to the end. If multiple tasks preassigned to a worker have a preassignedOrder, the tasks will be sorted so that the preassignedOrder is increasing (tasks at the front of the tour and tasks at the end of the tour separately).

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.

initassignedOrder
integer (Integer_u32) [ 0 .. 2147483647 ]

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

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 dontAlter and dontVary assignments.

initassignedShiftID
integer (Integer_u32) [ 0 .. 2147483647 ]

A shiftID to compliment either initassignedWorker or preassignedWorker in case the workerID is not unique.

prefGender
integer (GenderType) [ 0 .. 3 ]

The assigned worker needs to have this gender.

This is a weak restriction 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.

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

The revenue which will be achieved with this task.

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

Fixed amount of time added to this task's travel time.

group
integer (Integer_u32) [ 0 .. 2147483647 ]

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

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

predecessorGroup
integer (Integer_u32) [ 0 .. 2147483647 ]

Tasks with the same 'predecessorGroup' ID will be scheduled as a single batch of tasks without any tasks with different or no predecessorGroupIDs scheduled between them. The order of tasks within a batch can vary.

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

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 must 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.

ignoreHistory
boolean
Default: false

If true, this tasks get ignored in all history analysis

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",
  • "clientID": 2147483647,
  • "baseScheduleTime": "07:25",
  • "date": "2020-04-10",
  • "duration": 2147483647,
  • "durationInSeconds": 2147483647,
  • "timeEarliest": "07:25",
  • "timeLatest": "07:25",
  • "forbTimeEarliest": "07:25",
  • "forbTimeLatest": "07:25",
  • "timePriority": 5,
  • "location": {
    },
  • "locationSiteID": 2147483647,
  • "finishLocation": {
    },
  • "finishLocationSiteID": 2147483647,
  • "rotatable": false,
  • "description": "string",
  • "prefWorkers": [
    ],
  • "unpreferredWorkers": [
    ],
  • "antiWorkers": [
    ],
  • "forbWorkers": [
    ],
  • "capacity": -1.7e+308,
  • "weight": -1.7e+308,
  • "volume": -1.7e+308,
  • "qualification": 2147483647,
  • "categories": [
    ],
  • "antiCategories": [
    ],
  • "exchangeableCategories": [
    ],
  • "twinCategories": [
    ],
  • "preassignedWorker": 2147483647,
  • "preassignedOrder": -2147483648,
  • "desiredWorker": 2147483647,
  • "initassignedOrder": 2147483647,
  • "initassignedWorker": 2147483647,
  • "initassignedShiftID": 2147483647,
  • "prefGender": 3,
  • "precedingTasks": [
    ],
  • "predecessorTasks": [
    ],
  • "revenue": 1.7e+308,
  • "travelTimeExtra": 2147483647,
  • "group": 2147483647,
  • "predecessorGroup": 2147483647,
  • "assignmentPriority": 5,
  • "ignoreHistory": false,
  • "info": "string",
  • "allowedWorkers": [
    ]
}

MixedPlannerOutputWorker

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

The ID of the worker. Multiple workers with identical ID are allowed, those represent multiple "shifts" of the same person.

shiftID
integer (Integer_u32) [ 0 .. 2147483647 ]

A second ID in case there are multiple workers with the same workerID. This one needs to be unique among all workers with the same workerID. It can be referenced whenever a unique reference to this worker object is required.

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.

object (GeoCoord)

The location where the worker begins their working day. Leaving it empty means the worker starts on the location of their first task, this can be used in situations where workers start their day at home and any travel time to their first client does not count as working time.

startLocationSiteID
integer (Integer_u32) [ 0 .. 2147483647 ]

The ID of the location site that will be used as startLocation.

object (GeoCoord)

The location where the worker finishes their working day. Leaving it empty means the worker will end their tour at their last task, this can be used in situations where travel time home does not count as working time.

endLocationSiteID
integer (Integer_u32) [ 0 .. 2147483647 ]

The ID of the location site that will be used as endLocation.

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

The date of this shift.

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

The time this shift starts.

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

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

The time this shift ends.

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

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

The priority to keep the defined shift start and end times:

  • 0 - irrelevant
  • 1 - neutral
  • 2 - important
  • 3 - very important.
hoursPerWeek
integer [ 1 .. 90 ]
Deprecated
capacity
number (Number_u64) [ 0 .. 1.7e+308 ]
Default: 0

The available capacity of the worker or their vehicle.

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

The initially occupied capacity on shift start of this worker or their vehicle.

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

If during the tour the worker capacity gets filled up and this field is set, the worker will travel to the best available location sites in the given list and unload all their stored capacity, weight, and volume before traveling to the next task.

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

The time in minutes needed for a capacity reset.

maxResets
integer (Integer_u32) [ 0 .. 2147483647 ]

The maximum number of allowed capacity resets on this worker.

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

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

The available volume of the worker or their vehicle.

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

The initially loaded volume on shift start of this worker or their vehicle.

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

The weight the worker or their vehicle is able to handle.

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

The initially loaded weight on shift start of this worker or their vehicle.

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

If at the end of the worker's tour the current capacity exceeds this threshold, a final reset is automatically added.

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

If at the end of the worker's tour the current weight exceeds this threshold, a final reset is automatically added.

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

If at the end of the worker's tour the current volume exceeds this threshold, a final reset is automatically added.

qualification
integer (Integer_u32) [ 0 .. 2147483647 ]

The qualification of the worker. Workers can perform any task with equal or lower qualification requirement, the optimizer tried to not "overqualify" workers for tasks by keeping worker and task qualification close.

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 categories listed here is automatically considered valid as if they're listed in categories.

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

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

Tasks with any of these categories will be preferred by this worker. Categories listed here are automatically considered valid as if they're listed in categories.

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

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

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

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

The earliest start of the break a worker has to do.

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

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

The latest end of the break a worker has to do.

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

breakDuration
integer (Integer_u32) [ 0 .. 2147483647 ]

The duration in minutes of the break.

noAutomaticBreak
boolean
Default: false

If integrateGermanBreakDurations is set to true, this can flag can be used to exempt the worker from being assigned an automatic break. By setting the value to true, no automatic break is added. If either a manual break is specified or integrateGermanBreakDurations is false, this flag has no effect and should not be used.

vehicleType
integer (MixedPlannerVehicleType) [ 0 .. 4 ]
Default: 0

The vehicle type used by this worker.

gender
integer (GenderType) [ 0 .. 3 ]

The gender type of the worker.

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

The costs per km for this worker (e.g. fuel costs).

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.

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

The maximum total travel distance per shift that a worker wants to perform.

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

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

The maximum travel distance for each individual travel that a worker wants to perform.

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

dontVary
boolean
Default: false

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, as well as shiftID on the worker and initassignedShiftID on the task if the workerID is not unique. Travel times, resets, etc still get 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.

expectedWorkingMinutes
integer (Integer_u32) [ 0 .. 2147483647 ]

The target value for working time (tourStart until tourEnd) for this worker.

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

maxAssignableTasks
integer (Integer_u32) [ 0 .. 2147483647 ]

The maximum number of tasks that can be assigned to this worker.

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

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

The minimum number of tasks that must be assigned to this worker.

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

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

The time a break was scheduled on this worker.

info
string

Some textual information about the worker, e.g., for delays.

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

Time in minutes needed to get to the end location from the last task. The same rules as for the output-task's travelTime apply.

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

Distance in km between the last task and the end location. The same rules as for the output-task's travelDistance apply.

performFinalResetAtID
integer (Integer_u32) [ 0 .. 2147483647 ]

The id of the location site at which a capacity reset was performed after the last task and before returning to a depot.

travelTimeToFinalReset
integer (Integer_u32) [ 0 .. 2147483647 ]

If the worker performs a reset right before the end of their tour (performFinalResetAtID is set), this value contains the travel time to the reset location. Subtracting this value and capacityResetDuration from travelHomeTime nets the travel time from the reset location to the endLocation.

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

If the worker performs a reset right before the end of their tour (performFinalResetAtID is set), this value contains the travel distance to the reset location. Subtracting this value from travelHomeDistance nets the travel distance from the reset location to the endLocation.

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

The actual time this worker starts their tour. The value is set only if the worker has a task assigned. If the worker has a task assigned and tourStartsOnShiftStart is set to true, it will always be equal to shiftStart.

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

The actual time this worker ends their tour, including travel to its endLocation and any capacity resets.

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

The sum of all travel times of this worker. Does not include reset durations, neither from reset between tasks nor the final reset, but travel to and from reset locations is included.

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

The sum of all travel distances of this worker.

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

The sum of all task durations on this worker. Does not include breaks or capacity reset duration.

{
  • "workerID": 2147483647,
  • "shiftID": 2147483647,
  • "externalID": "string",
  • "startLocation": {
    },
  • "startLocationSiteID": 2147483647,
  • "endLocation": {
    },
  • "endLocationSiteID": 2147483647,
  • "shiftDate": "2020-04-10",
  • "shiftStart": "07:25",
  • "shiftEnd": "07:25",
  • "shiftPriority": 3,
  • "hoursPerWeek": 1,
  • "capacity": 1.7e+308,
  • "capacityInitial": 1.7e+308,
  • "capacityResetLocationSiteIDs": [
    ],
  • "capacityResetDuration": 2147483647,
  • "maxResets": 2147483647,
  • "volume": 1.7e+308,
  • "volumeInitial": 1.7e+308,
  • "weight": 1.7e+308,
  • "weightInitial": 1.7e+308,
  • "finalCapacityResetThreshold": 1.7e+308,
  • "finalVolumeResetThreshold": 1.7e+308,
  • "finalWeightResetThreshold": 1.7e+308,
  • "qualification": 2147483647,
  • "categories": [
    ],
  • "desiredCategory": 2147483647,
  • "prefCategories": [
    ],
  • "breakLocationSiteID": 2147483647,
  • "breakStartEarliest": "07:25",
  • "breakEndLatest": "07:25",
  • "breakDuration": 2147483647,
  • "noAutomaticBreak": false,
  • "vehicleType": 4,
  • "gender": 3,
  • "costsPerKM": 1.7e+308,
  • "costsPerMinute": 1.7e+308,
  • "costsInitial": 1.7e+308,
  • "maxDesiredTotalDistance": 1.7e+308,
  • "maxDesiredSingleDistance": 1.7e+308,
  • "dontVary": false,
  • "dontAlter": false,
  • "allowPreassignedTasksOnly": false,
  • "expectedWorkingMinutes": 2147483647,
  • "maxAssignableTasks": 2147483647,
  • "minAssignableTasks": 2147483647,
  • "breakScheduled": "07:25",
  • "info": "string",
  • "travelHomeTime": 2147483647,
  • "travelHomeDistance": 1.7e+308,
  • "performFinalResetAtID": 2147483647,
  • "travelTimeToFinalReset": 2147483647,
  • "travelDistanceToFinalReset": 1.7e+308,
  • "tourStart": "07:25",
  • "tourEnd": "07:25",
  • "totalTravelTime": 2147483647,
  • "totalTravelDistance": 1.7e+308,
  • "totalTaskTime": 2147483647
}

MixedPlannerStatistics

required
Array of objects

The applied optimizer configuration as fractions.

required
Array of objects

The workload per worker for each hour of the day as fractions. The first value is fraction of working time between 00:00 - 01:00 (1.0: worked 60 minutes, 0.0: worked 0 minutes), the second value is the working time between 01:00 - 02:00, etc.

required
Array of objects

The total time in minutes each worker spends traveling. Capacity reset durations (but not the drive to and from a reset location) are excluded.

required
Array of objects

The distance in km each worker drives for this plan.

required
Array of objects

The time in minutes each worker spends on working on tasks (sum of durations).

required
Array of objects

Proportion of working time to shift time.

required
Array of objects

Proportion of travel time to shift time. Capacity reset durations (but not the drive to and from a reset location) are excluded.

required
Array of objects

The time in minutes spent on different actions summed up. Capacity resets are counted towards travel time.

required
Array of objects

Sum of fulfilled (type matched) as well as unfulfilled (type unmatched) worker preferences.

required
Array of objects

Sum of fulfilled (type 'matched') as well as unfulfilled (type 'unmatched') gender preferences.

required
Array of objects

Sum of tasks assigned to desired workers (type 'matched') and sum of tasks assigned to another worker (type 'unmatched').

Array of objects

A number-based summary of total distance for each MixedPlannerVehicleType.

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.

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.

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

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

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

The driven distance in km summed up over all workers.

onTime
required
integer (Integer_0_100) [ 0 .. 100 ]

Percentage for tasks scheduled perfectly inside the desired time windows (0 to 100).

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

The profitability this plan archives based on worker costs and task revenues.

object

Data analyzed from history.

{
  • "configuration": [
    ],
  • "workload": [
    ],
  • "travelTimes": [
    ],
  • "travelDistances": [
    ],
  • "taskTimes": [
    ],
  • "taskBusyness": [
    ],
  • "travelBusyness": [
    ],
  • "workTimeDistribution": [
    ],
  • "preferredWorkers": [
    ],
  • "preferredGender": [
    ],
  • "desiredWorkers": [
    ],
  • "vehicleTypeDistances": [
    ],
  • "impact": [
    ],
  • "unassignedTaskIDs": [
    ],
  • "unassignableTaskIDs": [
    ],
  • "timeWindowViolationTaskIDs": [
    ],
  • "routeLength": 1.7e+308,
  • "onTime": 100,
  • "planProfitability": -1.7e+308,
  • "history": {
    }
}

MixedPlannerInfo

text
required
string

Some general information about the plan. Contains warnings for some strict restrictions.

balance
required
string

Statistics about the workload of the workers and the distribution of tasks among them.

dist
required
string

Distance in km driven by the workers.

pref
required
string

Information about preferred workers matches.

relax
required
string

Information about delayed tasks grouped by delay amount 5-30 minutes, 30+ minutes and information about exceeded worker shifts.

time
required
string

Total and average travel time.

feasible
required
boolean

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

constructionSites
any
Deprecated
{
  • "text": "string",
  • "balance": "string",
  • "dist": "string",
  • "pref": "string",
  • "relax": "string",
  • "time": "string",
  • "feasible": true,
  • "constructionSites": null
}

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"
}

MixedPlannerOutputPlan

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 sent this request.

required
object (MixedPlannerMeta)

Meta-information about what to consider in the optimization.

required
object (MixedPlannerOptimizationParameters)

Parameters for the optimization.

required
Array of MixedPlannerOutputTaskAssigned (object) or MixedPlannerOutputTaskUnassigned (object) (MixedPlannerOutputTask)

Array of assigned and unassigned tasks.

required
Array of objects (MixedPlannerOutputWorker)

Array of available workers.

Array of objects (MixedPlannerLocationSite)

Array of available location sites.

Array of objects or objects (MixedPlannerObstacle)
Deprecated
required
object (MixedPlannerStatistics)

Some statistics about the plan.

required
object (MixedPlannerInfo)

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": [
    ],
  • "locationSites": [
    ],
  • "obstacles": [
    ],
  • "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 MixedPlannerOptimizationParameters: Updated descriptions for parameter entries.

v9.1.1

  • Marked inactive errors in error id overview

v9.1.0

  • In MixedPlannerStatistics: Added property absolute to impact

v9.0.0

  • Added definition DeveloperOptions
  • In ErrorPlan: Added developerOptions, deprecated recovery
  • In MixedPlannerInputPlan, MixedPlannerOutputPlan: Added developerOptions, deprecated recovery

v8.5.0

  • in MixedPlannerHistoryAssignment: Added assignedShiftID
  • in MixedPlannerHistoryAssignment: Added assignedShiftIDAutomatically
  • in MixedPlannerHistoryAssignment: Added actualShiftID

v8.4.0

  • In MixedPlannerInputWorker: Added allowPreassignedTasksOnly
  • In MixedPlannerInputTask: Updated description of preassignedWorker to better explain behaviour when there are multiple worker with the same workerID

v8.3.0

  • In MixedPlannerOutputTaskAssigned: Added timeWindowViolation

v8.2.0

  • In MixedPlannerOutputTaskAssigned: Added gapBeforeTask

v8.0.0

  • In MixedPlannerOptimizationParameters: Deprecated field genderPref
  • In MixedPlannerStatisticsHistoryTask: Deprecated field genderWeights

v7.18.2

  • In MixedPlannerInputPlan: Updated description for history.
  • In MixedPlannerInputTask: Updated description for preassignedWorker, initassignedWorker, predecessorTasks.
  • In MixedPlannerOptimizationParameters: Updated description for preset.
  • Added example PredecessorChain for POST /description endpoint

v7.18.1

  • In MixedPlannerInputTask: Changed description of qualification to represent new dependency on parameter profitability

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.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.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 MixedPlannerOutput:
    • Combines MixedPlannerOutputPlan and ErrorPlan into one definition to use as schema in /plan GET response

v7.2.0

  • Added response code 409 to POST-requests

v7.1.0

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

v7.0.0

  • Removed MixedPlannerConstructionSite
  • Changed MixedPlannerInfo:constructionSites to deprecated.

v6.1.0

  • In MixedPlannerStatisticsHistoryTask: Added timeEarliestLimit, timeLatestLimit

v6.0.0

  • In MixedPlannerMeta, ShiftPlannerMeta, FloorPlannerMeta:
    • Deprecated enablePlanSplitting

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+)?$.

v3.1.0

  • In MixedPlannerInputTask: Added predecessorGroup.

v3.0.0

  • In MixedPlannerTravelOverride: Removed field internal.

v2.9.0

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

v2.8.1

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

v2.7.0

  • In MixedPlannerInputWorker: Added minAssignableTasks.

v2.6.0

  • In MixedPlannerLocationSite: Added externalID.

v2.5.0

  • In MixedPlannerInputWorker: Added noAutomaticBreak.

v2.4.0

  • In MixedPlannerInputWorker: Added expectedWorkingMinutes.

v2.3.0

  • In MixedPlannerInputWorker: Added maxAssignableTasks.

v2.2.0

  • In MixedPlannerMeta:
    • Added disableTaskTimeWindowRelaxation

v2.1.0

  • In MixedPlannerStatisticsHistoryWorker:
    • Added hasNoHistory

v2.0.0

  • Removed definition Number_u32, replaced all occurrences with Number_u64. Those are:
    • MixedPlannerInputTask, MixedPlannerOutputTask:
      • revenue
    • MixedPlannerInputWorker, MixedPlannerOutputWorker:
      • capacity
      • capacityInitial
      • volume
      • volumeInitial
      • weight
      • weightInitial
      • finalCapacityResetThreshold
      • finalVolumeResetThreshold
      • finalWeightResetThreshold
      • costsPerKM
      • costsPerMinute
      • costsInitial
  • Added Number_s64
  • Removed definition Number_s32, replaced all occurrences with Number_s64. Those are:
    • MixedPlannerInputTask, MixedPlannerOutputTask:
      • capacity
      • weight
      • volume
    • MixedPlannerOutputTaskAssigned:
      • profit
    • MixedPlannerStatistics:
      • planProfitability

v1.14.0

  • In ErrorPlan
    • Added recovery

v1.13.0

  • In MixedPlannerInputPlan, MixedPlannerOutputPlan:
    • Added recovery

v1.11.0

  • In MixedPlannerMeta:
    • Added new field removeInvalidTasks

v1.9.0

  • In MixedPlannerInputTask:
    • 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 MixedPlannerInputTask, MixedPlannerInputWorker
  • Fixed unevaluated properties being allowed in:
    • ErrorPlan
  • Fixed unevaluated properties being allowed in:
    • MixedPlannerConstructionSite
    • MixedPlannerHistoryAssignment
    • MixedPlannerHistoryTask
    • MixedPlannerHistoryWorker
    • MixedPlannerLocationSite
    • MixedPlannerOutputPlan
    • MixedPlannerStatisticsHistoryTask
    • MixedPlannerStatisticsHistoryWorker
    • MixedPlannerTravelOverrideDense
    • MixedPlannerOutputTaskAssigned
    • MixedPlannerOutputTaskUnassigned
    • MixedPlannerOutputWorker

v1.7.0

  • In MixedPlannerInputTask:
    • Added property durationInSeconds
    • Removed duration from required properties
  • In MixedPlannerStatisticsHistoryTask:
    • Added property group