Introduction

Welcome to the adiutaByte API. The goal of the API is to provide an interface for generating plans for various fleet optimization problems. This API description is intended to help setting up your own code to access the adiutaByte API. Currently there are two API endpoints implemented. The first one is for submitting a problem description, for which an optimized plan is then calculated. The second endpoint is for retrieving this finalized plan.

The API uses token-based authentication to protect these endpoints; users are generated on demand. Feel free to contact us for such a personalized access.

The furthest right column of this page will provide examples to data structures, requests or responses. Additionally there will be a few code snippets for some languages. With the tabs in the upper right corner you can switch the example's programming language.

Currently the API solely supports JSON formatted data. For the JSON structures there is a schema that is used to validate the data. Non-valid requests are immediately rejected with an error message. The structure and meaning of the JSON data used is shown in the first part of the following description. In each section a downloadable corresponding JSON schema in the latest version is linked.

For the different requests you need to insert some entries in the header:

• Authorization (your ID-token, see Authentication)
• Accepts ("application/json")
• Content-Type ("application/json")

Currently we distinguish between users whose limits for how many tasks can be planned within a month are managed by us, and accounts which are used for clients, to which a special management account exists to register new clients. For such an account the limits are set per client. The account for submitting plans and the account for management use the same e-mail-address but need to identify against different cognitio pools. The configuration for the different account types can be found in Authentication. To identify the different clients you need to relay the client-ID to the backend in every request.

Tags

• Features that are planned and not yet implemented are marked with TBA (Example: timeEarliest ^TBA). These are in a conceptual phase and might still get changed or deleted.
• Some features might not yet work, depending on what application version the plan is being calculated on. Features that are not yet live for all requests are marked with the version they are first introduced on (Example: timeEarliest ^v1.0.0). To determine the used version, check the field info->text in the response or contact us. ^{pre v2.26.0: This only works for MixedPlanner-Requests}

Restrictions

Certain values on input objects can restrict the general set of available solutions. These include time windows on tasks, workers or shifts, preferences of all kinds, categories, qualifications and many more. Due to the nature of optimization, not all of them can be kept nor is that even intended, as violating a constraint can often lead to vast improvements regarding another metric. Nevertheless there are some constraints the algorithm will keep at all costs, as they are deemed too important to be disregarded.

To differentiate the types of constraints, there will be an occasional Depends on column added to the parameter listing. It can contain a number of different text markers:

• "strict": A constraint that the algorithm either literally cannot violate or can do so but only in a worst-case scenario, for instance to keep another strict constraint. (Example: Qualifications)
• An optimization parameter: The constraint depends on the optimization parameter setting. The higher the setting value, the more likely it is for the restriction to be kept. However, unless noted otherwise, it cannot reach the importance level of a strict constraint. (Example: preferredWorkers)
• Nothing: The parameter either is not a constraint or its importance cannot be influenced via input data settings. (Example: gender or desiredWorker)

Contact us

If you notice issues or error with the documentation, if you have questions regarding the API or its documentation or if you're having another related issue, please contact us.

Definition of common types

Integers/Numbers

{
  "integer_u32": 12,
  "integer_s32": -12,
  "number_u32" : 7.184535,
  "number_s32" : -7.184535,
  "number_u64" : 7.184535,
  "number_s64" : -7.184535
}

JSON-Schema

The following ranges get used for values of type integer/ number:

Please refer to the respective linked json schema to determine which type of integer/number gets used.

GeoCoord

{
  "lat": 50.780241,
  "lng": 7.184535
}

JSON-Schema

Date

Examples for valid date strings are :

"2018-01-10"
"2019-12-03"
"2020-05-23"

JSON-Schema

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

• "YYYY": year AD, $ 2010 \leq x \leq 2099 $
• "MM": month, $ 1 \leq x \leq 12 $
• "DD": day, $ 1 \leq x \leq 31 $

Time

Examples for valid time strings are :

"06:59"
"15:59"
"1230:33"
"-39:12"
"03:01"

JSON-Schema

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

• "hh": hours, $ 0 \leq x \leq 9999 $
• "mm": minutes, $ 0 \leq x \leq 59 $ with exactly 2 digits

All times are interpreted in 24-hour notation and relative to midnight ("00:00") of a certain defined date. Those dates are:

• shiftDate for any Time values in Shift
• date for any Time values in Unassigned MixedPlanner-Task and Assigned MixedPlanner-Task
• shiftDate for any Time values in Unassigned MixedPlanner-Worker and Assigned MixedPlanner-Worker
• date for any Time values in Unassigned ShiftPlanner-Task and Assigned ShiftPlanner-Task.

This means that 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"

Input data containing only identical dates and no time of format "-hh:mm" will not result in output data containing times of format "-hh:mm".

VehicleType

An integer in the range $0 \leq x \leq 4$.

JSON-Schema

GenderType

JSON-Schema

An integer in the range $0 \leq x \leq 3$.

LanguageType

An integer in the range $0 \leq x \leq 1$.

Parameter Preset

An integer in the range $0 \leq x \leq 4$. Depending on the type of plan (MixedPlanner/ ShiftPlanner) not all presets are valid for use. For more information please refer to the respective preset specification.

Location Site

{
  "locationSiteID": 200,
  "location": {
    "lat": 50.878847,
    "lng": 6.964728400000013
  }
}

JSON-Schema

A location site is a GeoCoord which can be referenced by an id in various places:

• startLocationSiteID
• endLocationSiteID
• capacityResetLocationSiteIDs
• locationSiteID

Shift

The minimum required shift JSON-body looks like this:

{
  "shiftID": 1,
  "shiftDate": "2019-12-03",
  "shiftStart": "05:00",
  "shiftEnd": "12:00"
}

The full shift JSON-body looks like this:

{
  "shiftID": 1,
  "shiftDate": "2019-12-03",
  "shiftStart": "05:00",
  "shiftEnd": "12:00",
  "shiftPriority": 2
}

JSON-Schema (TODO)

A shift represents a worker's timeslot in which exactly one ShiftPlanner-Task can be carried out. For exceptions see the groupOrder parameter in ShiftPlanner-Tasks.

Construction Site

{
  "constructionSiteID": 666,
  "startDate": "2020-07-23",
  "endDate": "2020-07-25",
  "startPoint": {
    "lat": 48.17083,
    "lng": 11.3292
  },
  "endPoint": {
    "lat": 48.16774,
    "lng": 11.33253
  },
  "info": "Waldstraße gesperrt 2020"
}

JSON-Schema

A construction site gets represented by a straight line between its startPoint and endPoint. These can be identical for small scale obstructions.

Clientinformation

{
  "clientID": "{1234-5678-9123}"
}

Obstacle

The minimum required obstacle can look like these:

{
  "type": "polyline",
  "factor": 2.5,
  "points": [
    {
      "lat": 51.46149994737996,
      "lng": 7.850463381293338
    },
    {
      "lat": 51.66914967977792,
      "lng": 9.753747625087499
    },
    ...
  ]
},
{
  "type": "polygon",
  "restriction": 0.5,
  "points": [
    {
      "lat": 51.46149994737996,
      "lng": 7.850463381293338
    },
    {
      "lat": 51.66914967977792,
      "lng": 9.753747625087499
    },
    ...
  ]
},
{
  "type": "polygon",
  "travelTimeIncrease": 2.5,
  "points": [
    ...
  ]
}

A full obstacle can look like this:

{
  "type": "polyline",
  "factor": 2.5,
  "restriction": 0.5,
  "travelTimeIncrease": 2.5,
  "description": "This is a line",
  "points": [
    {
      "lat": 51.46149994737996,
      "lng": 7.850463381293338
    },
    {
      "lat": 51.66914967977792,
      "lng": 9.753747625087499
    },
    ...
  ]
}

Further examples for obstacles

{
  "type": "polygon",
  "factor": 2.5,
  "description": "This is a square obstacle",
  "points": [
    {
      "lat": 0.0,
      "lng": 0.0
    },
    {
      "lat": 1.0,
      "lng": 0.0
    },
    {
      "lat": 1.0,
      "lng": 1.0
    },
    {
      "lat": 0.0,
      "lng": 1.0
    }
  ]
},
{
  "type": "polyline",
  "restriction": 0.5,
  "description": "This is a W",
  "points": [
    {
      "lat": 0.0,
      "lng": 1.0
    },
    {
      "lat": 0.5,
      "lng": 0.0
    },
    {
      "lat": 1.0,
      "lng": 0.5
    },
    {
      "lat": 1.5,
      "lng": 0.0
    },
    {
      "lat": 2.0,
      "lng": 1.0
    }
  ]
}

JSON-Schema

An obstacle represents a permanent traffic hindrance that increases travel times.

Based on obstacle type, the shape of the obstacle is defined as follows:

• polygon: The points define the corner points of the obstacle, in order of their listing in the array. Each consecutive pair of GeoCoords defines a side of the polygon, so does the pair consisting of the first and last GeoCoord in the array.
• polyline: The points define the obstacle by connecting each consecutive pair of GeoCoords with a straight line.

At least one offactor, restriction or travelTimeIncrease needs to be set.

Backend Version

Introduced in: v2.35.0

The minimum required Backend Version JSON-body looks like this:

{
  "schema": "v0.0.0"
}

The full Backend Version JSON-body looks like this:

{
  "schema": "v0.0.0",
  "version": "v0.0.0",
  "rev": "abde12"
}

JSON-Schema

Definition of MixedPlanner-Types

Mixedplanner-Metainformation

The minimum required Meta-Information looks like this:

{
  "dateFrom": "2019-12-03",
  "dateTo": "2019-12-03",
  "resCapacity": false,
  "resCategory": false,
  "resQualification": false,
  "postProcessing": false
}

A full Meta-Information object can look like this:

{
  "dateFrom": "2019-12-03",
  "dateTo": "2019-12-03",
  "resCapacity": false,
  "resCategory": false,
  "resQualification": false,
  "postProcessing": false,
  "accuracyMode": 1.0,
  "outputLanguage": 1,
  "tightSchedule": false,
  "travelTimeMin": 5,
  "integrateDurationExtensions": true,
  "integrateGermanBreakRegulations": true,
  "enablePlanSplitting": true
}

JSON-Schema

The options res* describe which fields from the dataset should be taken into account. More precisely those are:

• resCapacity:
  • capacity (Task)
  • volume (Task)
  • weight (Task)
  • capacity (Worker)
  • capacityInitial
  • capacityResetDuration
  • capacityResetLocationSiteIDs
  • finalCapacityResetThreshold
  • volume (Worker)
  • volumeInitial
  • finalVolumeResetThreshold
  • weight (Worker)
  • weightInitial
  • finalWeightResetThreshold
• resCategories:
  • categories (Task)
  • antiCategories
  • exchangeableCategories
  • twinCategories
  • categories (Worker)
  • prefCategories
  • desiredCategory
• resQualification:
  • qualification (Task)
  • qualification (Worker)

The setting integrateDurationExtensions is an output-only setting, meaning both internal calculations and algorithm result are unaffected. Any values besides the ones listed below are unchanged:

• duration: The task duration gets multiplied by the workTimeMultiplicator determined by workTimeRelax.
• travelTime: A detailed explanation to the modification can be found in the respective section.

Using the integrateDurationExtensions setting might provide some better readable data: Since internal calculations always apply the modifiers to durations and travel times, the internal values when calculating a plan are greater or equal to the ones that get output when not using integrateDurationExtensions. As a result, the output plan will feature gaps in time where for instance travel happens internally but would already be concluded if you used the output values. The integrateDurationExtensions setting outputs the internally used values to avoid this effect. However, the downside is inflated travel and work times in the output, since all buffers are now included in their respective work or travel time.

Using the option enablePlanSplitting can be benefitial if your input data contains clearly separateable sets of data, meaning you can create sets of workers and tasks, which can never be assigned to or carry out a task/worker from a different set than its own. In this case the option allows the algorithm to simplify the problem by solving each set separately. Additionally, any automatic input data modifications will be applied separately as well, meaning they'll be more focussed towards the respective set and can work more accurately.

However, due to the nature of the algorithm, this can lead to a timeout without having obtained a solution to the plan, and an error solution will be returned (Code 103). The likelihood of this happening increases with input data size.

Using the option allowUnassignedTasks enables an unassignment behaviour in the algorithm, meaning it will, if deemed necessary, refuse to assign subsets of tasks to any worker. Examples are scenarios where the only qualified workers are overloaded or there is no workers that can even carry out a task. In the output data this can be recognized by the task missing its assignment data, such as timeScheduled or travelTime. The differences to an assigned task are noted in the description for the Assigned MixedPlanner-Task. Additionally, the info section will notify of unassignment and, if possible, the reason for it.

Per default, travel from and to capacity reset locations is part of the optimization, after a reset the worker will often continue their tour closer to the reset location. Other tours might lead to or from reset locations to minimize travel from the task before reset to the reset location and vice versa from the reset location to the next task. While this behaviour is no doubt beneficial for reducing travel time/ distance, it can lead to unwanted results in use cases where a high amount of clustering is intended, since from a pure time/distance approach, it makes little sense to have a worker return to their cluster after a reset. For these cases, the option dontOptimizeResets can be set to true so that travel to and from reset locations does not get considered in the optimization anymore. Of course, the travel will still get factored into scheduled times etc, but the algorithm will no longer consider these travels as part of the optimization.

Mixedplanner-Optimization-Parameters

The minimum optimization parameters JSON-body is an empty body. The full body looks like this:

{
  "preset": 1,
  "fairDistribution": 4,
  "localityClustering": 2,
  "shortPaths": 7,
  "timeliness": 5,
  "travelTimeRelax": 0,
  "workerPrefs": 5,
  "workerReduction": 1,
  "workTimeRelax": 0,
  "genderPref": 2,
  "profitability": 3
}

JSON-Schema

All parameters are integer numbers $ 0 \leq x \leq 9 $. You only need to pass the ones you want to use, all others will be implicitly set to 0.

The following presets are currently available (parameters not listed are set to 0):

Unassigned MixedPlanner-Task

The minimum required unassigned task JSON-body looks like this:

{
  "taskID": 200,
  "date": "2019-12-03",
  "duration": 65,
  "timeEarliest": "10:00",
  "timeLatest": "12:00"
}

The full unassigned task JSON-body when using a GeoCoord location looks like this:

{
  "taskID": 200,
  "externalID": "id123",
  "date": "2019-12-03",
  "duration": 65,
  "timeEarliest": "10:00",
  "timeLatest": "12:00",
  "timePriority": 2,
  "location": {
    "lat": 50.878847,
    "lng": 6.964728400000013
  },
  "prefWorkers": [
    1,2
  ],
  "forbWorkers": [
    3,4
  ],
  "capacity": 40,
  "weight": 40,
  "volume": 40,
  "qualification": 3,
  "categories": [
    1
  ],
  "antiCategories": [
    2
  ],
  "exchangeableCategories": [
    4,5,6
  ],
  "twinCategories": [
    3
  ],
  "desiredWorker": 1,
  "initassignedWorker": 1,
  "initassignedOrder": 1,
  "preassignedWorker": 2,
  "prefGender": 1,
  "precedingTasks": [ 
    1, 2
  ],
  "predecessorTasks": [
    3
  ],
  "revenue": 1.25,
  "travelTimeExtra": 2,
  "group": 2
}

The full unassigned task JSON-body when using a Location Site looks like this:

{
  "taskID": 200,
  "externalID": "id123",
  "date": "2019-12-03",
  "duration": 65,
  "timeEarliest": "10:00",
  "timeLatest": "15:00",
  "forbTimeEarliest": "12:30",
  "forbTimeLatest": "12:45",
  "timePriority": 2,
  "locationSiteID": 1,
  "prefWorkers": [
    1,2
  ],
  "antiWorkers": [
    1,2
  ],
  "forbWorkers": [
    3,4
  ],
  "capacity": 40,
  "weight": 40,
  "volume": 40,
  "qualification": 3,
  "categories": [
    1
  ],
  "antiCategories": [
    2
  ],
  "exchangeableCategories": [
    4,5,6
  ],
  "twinCategories": [
    3
  ],
  "desiredWorker": 1,
  "initassignedWorker": 1,
  "initassignedOrder": 1,
  "preassignedWorker": 2,
  "prefGender": 1,
  "precedingTasks": [ 
    1, 2
  ],
  "predecessorTasks": [
    3
  ],
  "revenue": 1.25,
  "travelTimeExtra": 2,
  "group": 2
}

The JSON-Schema of the unassigned task is an extension of the JSON-Schema of an abstract task.

The unassigned task is the incoming task description for the optimizer outlining the restrictions for the optimization.

categories, antiCategories and exchangeableCategories need to be disjoint sets on each task. This means that a category appearing in categories may not appear in antiCategories or exchangeableCategories and vice versa. twinCategories represent a different set and are not affected by this restriction.

Positive numbers for capacity, volume or weight represent loading tasks while negative numbers for capacity, volume or weight represent unloading tasks.

Assigned MixedPlanner-Task

The minimum required assigned task JSON-body looks like this:

{
  "taskID": 200,
  "date": "2019-12-03",
  "duration": 65,
  "timeEarliest": "10:00",
  "timeLatest": "12:00",
  "timeScheduled": "11:01",
  "travelTime": 3,
  "travelDistance": 2.83061,
  "assignedWorker": 2,
  "info": "This task assignment causes negative arrival slack: -6",
  "finalassignedOrder": 3
}

The full assigned task JSON-body when using a GeoCoord location looks like this:

{
  "taskID": 200,
  "externalID": "id123",
  "date": "2019-12-03",
  "duration": 65,
  "timeEarliest": "10:00",
  "timeLatest": "15:00",
  "forbTimeEarliest": "12:30",
  "forbTimeLatest": "12:45",
  "timePriority": 2,
  "location": {
    "lat": 50.878847,
    "lng": 6.964728400000013
  },
  "prefWorkers": [
    1,2
  ],
  "antiWorkers": [
    1,2
  ],
  "forbWorkers": [
    3,4
  ],
  "capacity": 40,
  "weight": 40,
  "volume": 40,
  "qualification": 3,
  "categories": [
    1
  ],
  "antiCategories": [
    2
  ],
  "exchangeableCategories": [
    4,5,6
  ],
  "twinCategories": [
    3
  ],
  "desiredWorker": 1,
  "initassignedWorker": 1,
  "initassignedOrder": 1,
  "preassignedWorker": 2,
  "prefGender": 1,
  "precedingTasks": [ 
    1,2
  ],
  "predecessorTasks": [
    3
  ],
  "revenue": 1.25,
  "travelTimeExtra": 2,
  "timeScheduled": "11:01",
  "travelTime": 3,
  "travelDistance": 2.83061,
  "assignedWorker": 2,
  "info": "This task assignment causes negative arrival slack: -6",
  "profit": 12.21,
  "performResetBeforeAtID": 2,
  "finalassignedOrder": 3,
  "group": 2,
}

The assigned task - after the performed optimization - extends the unassigned task with information about when the task is scheduled and by whom it will be completed. Additionally some predictive metrics about the distance and travel time to reach this task are added.

The JSON-Schema of the assigned task is an extension of the JSON-Schema of an abstract task.

The value travelTime also includes travel times to and from a capacity reset location, as well as the reset duration, if a reset is performed directly before this task. Depending on the integrateDurationExtensions settings, it may also include travelTimeExtra and the travel time multiplicator based on travelTimeRelax. The following table provides the calculations in each case:

In case no actual travel happens (for instance identical locations of consecutive tasks, no location or no startLocation/ endLocation ) the values $max( actualTravelTime, travelTimeMin )$ and similar are zero.

Please note that the formula changes with integrateDurationExtensions set to true influence only output values, since the setting does not change internal calculations or the algorithm result (see MixedPlanner-Metainformation for more details).

Unassigned MixedPlanner-Worker

The minimum required JSON-body of an unassigned worker when using GeoCoord locations looks like this:

{
  "workerID": 1,
  "shiftStart": "06:00",
  "shiftEnd": "14:00",
  "shiftDate": "2019-12-03"
}

The full JSON-body of an unassigned worker when using GeoCoord locations and dontAlter looks like this:

{
  "workerID": 1,
  "externalID": "id123",
  "shiftStart": "06:00",
  "shiftEnd": "14:00",
  "shiftDate": "2019-12-03",
  "startLocation":{
    "lat": 50.878847,
    "lng": 6.964728400000013
  },
  "endLocation":{
    "lat": 50.878847,
    "lng": 6.964728400000013
  },
  "shiftPriority": 2,
  "capacity": 20.5,
  "capacityInitial": 10.1,
  "capacityResetLocationSiteIDs": [
    1,2
  ],
  "capacityResetDuration": 10,
  "maxResets": 2,
  "volume": 12.5,
  "volumeInitial": 5.5,
  "weight": 2.5,
  "weightInitial": 1.0,
  "finalCapacityResetThreshold": 12.1,
  "finalVolumeResetThreshold": 5.5,
  "finalWeightResetThreshold": 1.5,
  "qualification": 1,
  "categories": [
    4,5
  ],
  "prefCategories": [
    6
  ],
  "breakStartEarliest": "12:21",
  "breakEndLatest": "13:00",
  "breakDuration": 10,
  "vehicleType": 1,
  "gender": 1,
  "costsPerKM": 0.05,
  "costsPerMinute": 1.23,
  "costsInitial": 234.56,
  "maxDesiredTotalDistance": 100.0,
  "maxDesiredSingleDistance": 5.0,
  "dontAlter": true,
  "dontVary": true
}

The full JSON-body of an unassigned worker when using Location Sites and dontVary looks like this:

{
  "workerID": 1,
  "externalID": "id123",
  "shiftStart": "06:00",
  "shiftEnd": "14:00",
  "shiftDate": "2019-12-03",
  "startLocationSiteID": 4,
  "endLocationSiteID": 5,
  "shiftPriority": 2,
  "capacity": 20.5,
  "capacityInitial": 10.1,
  "capacityResetLocationSiteIDs": [
    1,2
  ],
  "capacityResetDuration": 10,
  "maxResets": 2,
  "volume": 12.5,
  "volumeInitial": 5.5,
  "weight": 2.5,
  "weightInitial": 1.0,
  "finalCapacityResetThreshold": 12.1,
  "finalVolumeResetThreshold": 5.5,
  "finalWeightResetThreshold": 1.5,
  "qualification": 1,
  "categories": [
    4,5
  ],
  "prefCategories": [
    6
  ],
  "desiredCategory": 12,
  "breakStartEarliest": "12:21",
  "breakEndLatest": "13:00",
  "breakDuration": 10,
  "vehicleType": 1,
  "gender": 1,
  "costsPerKM": 0.05,
  "costsPerMinute": 1.23,
  "costsInitial": 234.56,
  "maxDesiredTotalDistance": 100.0,
  "maxDesiredSingleDistance": 5.0,
  "dontVary": true,
  "dontAlter": true
}

The JSON-Schema of the unassigned worker is an extension of the JSON-Schema of an abstract worker.

The worker has both optional and required parameters as marked in the following table.

When no startLocation or startLocationSiteID is given, the shift of the worker will start at the first assigned task with no travel time or distance to it. 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. (By analogy: endLocation/endLocationSiteID)

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. Travel times, resets, etc still get calculated on both worker and task and the worker and its tasks will be considered in MixedPlanner-Statistics and MixedPlanner-Info.

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.

Assigned MixedPlanner-Worker

The assigned worker - after the performed optimization - extends the unassigned worker with information about when their break is scheduled (when one was given). Additionally some information about the worker can be added in the info field.

The minimum required JSON-body of an assigned worker when using GeoCoord locations and dontAlter looks like this:

{
  "workerID": 1,
  "shiftStart": "06:00",
  "shiftEnd": "14:00",
  "shiftDate": "2019-12-03",
  "travelHomeTime": 2,
  "travelHomeDistance": 1.123,
}

The full JSON-body of an assigned worker when using GeoCoord locations and dontAlter looks like this:

{
  "workerID": 1,
  "externalID": "id123",
  "shiftStart": "06:00",
  "shiftEnd": "14:00",
  "shiftDate": "2019-12-03",
  "startLocationSiteID": 4,
  "endLocationSiteID": 5,
  "shiftPriority": 2,
  "capacity": 20.5,
  "capacityInitial": 10.1,
  "capacityResetLocationSiteIDs": [
    1,2
  ],
  "capacityResetDuration": 10,
  "volume": 12.5,
  "volumeInitial": 5.5,
  "weight": 2.5,
  "weightInitial": 1.0,
  "finalCapacityResetThreshold": 12.1,
  "finalVolumeResetThreshold": 5.5,
  "finalWeightResetThreshold": 1.5,
  "qualification": 1,
  "categories": [
    4,5
  ],
  "prefCategories": [
    6
  ],
  "desiredCategory": 12,
  "breakStartEarliest": "12:21",
  "breakEndLatest": "13:00",
  "breakDuration": 10,
  "vehicleType": 1,
  "gender": 1,
  "costsPerKM": 0.05,
  "costsPerMinute": 1.23,
  "costsInitial": 234.56,
  "maxDesiredTotalDistance": 100.0,
  "maxDesiredSingleDistance": 5.0,
  "dontVary": true,
  "info": "",
  "breakScheduled": "12:30",
  "travelHomeTime": 2,
  "travelHomeDistance": 1.123,
  "performFinalResetAtID": 1,
  "dontAlter": true
}

The JSON-Schema of the assigned worker is an extension of the JSON-Schema of an abstract worker.

If an Unassigned MixedPlanner-Worker does not already contain the data breakStartEarliest, breakEndLatest or breakDuration, integrateGermanBreakRegulations is set to true and the worker has to take a break due to their shift length and German law, the automatically generated break data regarding these values will be added to the Assigned MixedPlanner-Worker as extension. If these values were already written in the Unassigned MixedPlanner-Worker, they do not get changed in the Assigned MixedPlanner-Worker. If the values were not written in the Unassigned MixedPlanner-Worker but integrateGermanBreakRegulations is set to false or German law does not require a break for this shift, no data will be added.

MixedPlanner-History

An example for MixedPlanner-History looks like this

{
  "tasks": [
    {
      "taskID": 0,
      "clientID": 100,
      "scheduling": [
        {
          "date": "2000-01-01",
          "baseScheduleTime": "00:00",
          "baseWorker": 1,
          "timeScheduled": "00:00",
          "assignedWorker": 0,
          "timeVariance": 0,
          "timePriority": 0,
          "timeScheduledAutomatically": "00:00",
          "assignedWorkerAutomatically": 0,
          "actualStartTime": "00:00",
          "actualWorker": 0,
          "prevTask": 0
        },
        ...
      ]
    },
    ...
  ],
  "workers": [
    {
      "workerID": 0,
      "gender": 1,
      "qualification": 1,
      "categories": [ 1,2 ]
    },
    ...
  ]
}

The JSON-schema is called history

MixedPlanner-History-Assignment

The minimum required JSON-body of a MixedPlanner-History-Assignment looks like this

{
  "date": "2000-01-01"
}

The full JSON-body of a MixedPlanner-History-Assignment looks like this

{
  "date": "2000-01-01",
  "baseScheduleTime": "00:00",
  "baseWorker": 1,
  "timeScheduled": "00:00",
  "assignedWorker": 0,
  "timeVariance": 0,
  "timePriority": 0,
  "timeScheduledAutomatically": "00:00",
  "assignedWorkerAutomatically": 0,
  "actualStartTime": "00:00",
  "actualWorker": 0,
  "prevTask": 0
}

The JSON-schema is called History-Assignment

MixedPlanner-History-Task

The JSON-body of a MixedPlanner-History-Task looks like this

{
  "taskID": 0,
  "clientID": 100,
  "scheduling": [
    {
      "date": "2000-01-01",
      "baseScheduleTime": "00:00",
      "baseWorker": 1,
      "timeScheduled": "00:00",
      "assignedWorker": 0,
      "timeVariance": 0,
      "timePriority": 0,
      "timeScheduledAutomatically": "00:00",
      "assignedWorkerAutomatically": 0,
      "actualStartTime": "00:00",
      "actualWorker": 0,
      "prevTask": 0
    },
    ...
  ]
}

The JSON-schema is called History-Task

MixedPlanner-History-Worker

The minimum required JSON-body of a MixedPlanner-History-Worker looks like this

{
  "workerID": 0
}

The full JSON-body of a MixedPlanner-History-Worker looks like this

{
  "workerID": 0,
  "gender": 1,
  "qualification": 1,
  "categories": [ 1,2 ]
}

The JSON-schema is called History-Worker

MixedPlanner-Statistics

The JSON-body of statistics for a calculated plan looks like this:

{
  "configuration": [
    {
      "label": "Short Path",
      "value": 0.777778
    },
    ...
  ],
  "workload": [
    {
      "workerID": 1,
      "values": [
        0,0,0,0,0,0,0.97,1,0.5,0.17,0.07,0.5,0,0,0,0,0,0,0,0,0,0,0
      ]
    },
    ...
  ],
  "travelTimes": [
    {
      "workerID": 1,
      "time": 51
    },
    ...
  ],
  "travelDistances": [
    {
      "workerID": 1,
      "distance": 32.1
    },
    ...
  ],
  "taskTimes": [
    {
      "workerID": 1,
      "time": 145
    },
    ...
],
  "taskBusyness": [
    {
      "workerID": 1, 
      "busyness": 0.3
    },
    ...
  ],
  "travelBusyness": [
    {
      "workerID": 1,
      "busyness": 0.4
    },
    ...
  ],
  "workTimeDistribution": [
    {
      "type": "Working Time",
      "time": 716
    },
    ...
  ],
  "preferredWorkers": [
    {
      "type": "matched",
      "count": 12
    },
    {
      "type": "unmatched",
      "count": 7
    }
  ],
  "preferredGender": [
    {
      "type": "matched",
      "count": 3
    },
    {
      "type": "unmatched",
      "count": 4
    }
  ],
  "desiredWorkers": [
    {
      "type": "matched",
      "count": 9
    },
    {
      "type": "unmatched",
      "count": 13
    }
  ],
  "vehicleTypeDistances": [
    {
      "vehicleType": 0,
      "distance": 9.123
    },
    {
      "vehicleType": 3,
      "distance": 4.2
    },
    ...
  ],
  "impact": [
    {
      "label": "Anticategories",
      "value": 0.123
    },
    ...
  ],
  "routeLength": 146.841095,
  "onTime": 96,
  "planProfitability": 150.12
}

JSON-Schema

The array configuration contains the following fields. They are translated based on the language setting and are all required:

The array workTimeDistribution contains the following fields. They are translated based on the language setting and are all required:

The array impact contains all restriction types and gives a percentage (0.0-1.0) evaluation of each restriction's final influence on the algorithmic optimization and plan result. This can be used to detect logical problems in the input data, i.e. too restrictive time windows, large travel times or a large amount of worker preferences that just cannot be fulfilled. However, please note that if a restriction is listed in impact with a value greater zero, it does not mean that there even is a way to erase its impact. For instance, travel values will always be featured unless the total amount of travel time is zero or the shortPaths option is set to zero.

The following fields are getting written in impact. They get translated based on the language setting and are all optional and only set if greater zero.:

MixedPlanner-Info

The JSON-body of info for a calculated plan with German language settings looks like this:

{
  "text": "Alle Aufgaben wurden valide den Mitarbeitern zugewiesen!",
  "balance": "4 Mitarbeiter sind eingeplant\n6,2 Aufgaben durchschnittlich (pro Mitarbeiter)\n1,2 Aufgaben Abweichung von der durchschnittlichen Aufgabenzahl (pro Mitarbeiter)\nAufgaben- und Reisezeiten in Summe: 886 Minuten\nSchichtzeiten in Summe: 1860 Minuten\nAuslastung (netto): 47,6%",
  "dist": "146,8 km auf der Straße",
  "pref": "12 Aufträge werden von einem gewünschten Mitarbeiter durchgeführt, bei 7 Aufträgen war dies leider nicht sinnvoll oder möglich",
  "relax": "Aufträge:\n\nPrognostizierte kurze Verspätungen [5-30 Minuten] (4%):\n200, \n\nPrognostizierte Verspätungen [über 30 Minuten] (0%):\n\n\nDie anderen 24 Aufgaben (96%) werden pünktlich erreicht!\n\nSchichten:\nAlle Mitarbeiterschichten können eingehalten werden.",
  "time": "170 Minuten auf der Straße\n42,5 Minuten auf der Straße durchschnittlich (pro Mitarbeiter)\n9,0 Minuten Reisezeitvarianz (pro Mitarbeiter)",
  "feasible": false,
  "constructionSites": [
    {
      "constructionSiteID": 666,
      "startDate": "2020-07-23",
      "endDate": "2020-07-25",
      "startPoint": {
        "lat": 48.17083,
        "lng": 11.3292
      },
      "endPoint": {
        "lat": 48.16774,
        "lng": 11.33253
      },
      "info": "Waldstraße gesperrt 2020"
    },
    ...
  ]
}

JSON-Schema

All text in text, balance, dist, pref, relax, time gets translated based on language setting.

Travel Override

Introduced in: v2.31.0

{
  "sparse": [
    {
      "vehicleTypes": [0,2],
      "sourceIDs": [12,13,1,12],
      "targetIDs": [14,11,12,1],
      "travelTime": [3,4,1,1],
      "travelDistance": [2.83,1.5,2.01,3.12]
    },
    {
      "vehicleTypes": [1],
      "sourceIDs": [12,13,1,12],
      "targetIDs": [14,11,12,1],
      "travelTime": [3,4,1,1],
      "travelDistance": [2.83,1.5,2.01,3.12]
    },
    ...
  ],
  "dense": [
    {
      "travelTime": [0,2,3,4,0,2,12,5,0],
      "travelDistance": [0,1.123,2.123,3.456,0,4.5,2.123,10.11,4.9,0],
      "vehicleTypes": [0,3]
    },
    {
      "travelTime": [0,2,3,4,0,2,12,5,0],
      "travelDistance": [0,1.123,2.123,3.456,0,4.5,2.123,10.11,4.9,0],
      "vehicleTypes": [2]
    },
    ...
  ]
}

JSON-Schema

The base schema consists of a single dense and/or a single sparse array, but at least one element:

A single entry in the dense array looks like this: JSON-Schema

Example: The travelTime array [0,2,3,4,0,2,12,5,0] translates to the following 3x3 matrix:

A single entry in the sparse array looks like this: JSON-Schema

• In the text above, LocationSiteID refers to locationSiteID.
• Entries in travelTime and travelDistance are considered "not set" if they are either 0 or -1 and thus will not be used to override algorithm calculations.
• Travel from or to LocationSiteIDs out of bounds (dense)/ Travel not specified in data (sparse) will be considered exactly like unset data

Definition of ShiftPlanner-Types

ShiftPlanner-Metainformation

The minimum required JSON-body of metainformation looks like this:

{
  "dateFrom": "2019-12-03",
  "dateTo": "2019-12-03",
  "resCategory": false,
  "resQualification": false
}

The full JSON-body of metainformation looks like this:

{
  "dateFrom": "2019-12-03",
  "dateTo": "2019-12-03",
  "resCategory": false,
  "resQualification": false,
  "accuracyMode": 1.0,
  "outputLanguage": 1,
  "minQualificationOfTaskCoverage": 2,
  "omnipresentCategoriesOfTaskCoverage": [
    3,5,6
  ],
  "enablePlanSplitting": false,
  "allowUnassignedTasks": true,
  "followBiorhythm": true
}

JSON-Schema (TODO)

The options res* describe which fields from the dataset should be taken into account. More precisely those are:

• resCategories:
  • categories (Task)
  • categories (Worker)
  • exchangeableCategories
  • prefCategories
  • desiredCategory
  • prefWeekCategories
  • prefWeekendCategories
  • omnipresentCategoriesOfTaskCoverage
• resQualification:
  • minQualificationOfTaskCoverage
  • qualification (Task)
  • qualification (Worker)

Using the enablePlanSplitting can be benefitial if your input data contains clearly separateable sets of data, meaning you can create sets of workers and tasks, which can never be assigned to or carry out a task/worker from a different set than its own. In this case the option allows the algorithm to simplify the problem by solving each set separately. Additionally, any automatic input data modifications will be applied separately as well, meaning they'll be more focussed towards the respective set and can work more accurately.

However, due to the nature of the algorithm, this can lead to a timeout without having obtained a solution to the plan, and an error solution will be returned (Code 103). The likelihood of this happening increases with input data size.

Using the option allowUnassignedTasks enables an unassignment behaviour in the algorithm, meaning it will, if deemed necessary, refuse to assign subsets of tasks to any worker. Examples are scenarios where the only qualified workers are overloaded or there is no workers that can even carry out a task. In the output data this can be recognized by the task missing its assignment data, such as timeScheduled or finalassignedOrder. The differences to an assigned task are noted in the description for the Assigned ShiftPlanner-Task. Additionally, the info section will notify of unassignment and, if possible, the reason for it.

ShiftPlanner-Optimization-Parameters

The minimum optimization parameters JSON-body is an empty body. The full body looks like this:

{
  "preset": 1,
  "fairDistribution": 4,
  "timeliness": 5,
  "workerPrefs": 5,
  "teamPrefs": 5,
  "taskPrefs": 5,
  "worktimePrefs": 5,
  "workerReduction": 1,
  "genderPref": 2,
  "profitability": 3
}

JSON-Schema (TODO)

All parameters are integer numbers between 0 and 9 (inclusive). You only need to pass the ones you want to use, the other will be implicitly set to 0.

The following presets are currently available (parameters not listed are set to 0):

Unassigned ShiftPlanner-Task

The minimum required JSON-body of an unassigned task looks like this:

{
  "taskID": 200,
  "date": "2019-12-03",
  "duration": 240,
  "timeEarliest": "06:00",
  "timeLatest": "12:00"
}

The full JSON-body of an unassigned task looks like this:

{
  "taskID": 200,
  "externalID": "id123",
  "date": "2019-12-03",
  "duration": 240,
  "timeEarliest": "06:00",
  "timeLatest": "12:00",
  "timePriority": 2,
  "prefWorkers": [
    1,2
  ],
  "antiWorkers": [
    5,6
  ],
  "forbWorkers": [
    3,4
  ],
  "qualification": 3,
  "categories": [
    1
  ],
  "exchangeableCategories": [
    2,4
  ],
  "preassignedWorker": 2,
  "desiredWorker": 2,
  "prefGender": 1,
  "precedingTasks": [ 
    1,2
  ],
  "predecessorTasks": [ 
    1,2
  ],
  "group": 2,
  "groupOrder": 3,
  "revenue": 2.123,
  "assignmentPriority": 2
}

The JSON-Schema of the unassigned shiftplanner task (TODO) is an extension of the JSON-Schema of an abstract task.

The unassigned task is the incoming task description for the optimizer outlining the restrictions for the optimization.

Tasks within the same group (identical groupID) will still need a Shift each where they will be assigned on seperately. If the whole group or a subset of a group shall be assigned to a single Shift, each task in the set/ subset needs to have a unique groupOrder. The tasks will then be assigned to a single Shift in that order. Tasks without groupOrder within the same group will not get assigned to that Shift and need a seperate Shift each. Note that there can obviously be only one such subset per group.

If tasks are supposed to be on the same worker in a specified order but on seperate Shifts, set the groupID but use precedingTasks or predecessorTasks instead of groupOrder.

Assigned ShiftPlanner-Task

The assigned task - after the performed optimization - extends the unassigned tasks with information about when the task is scheduled and by whom it will be completed.

The minimum required JSON-body of an assigned task looks like this:

{
  "taskID": 200,
  "date": "2019-12-03",
  "duration": 240,
  "timeEarliest": "06:00",
  "timeLatest": "12:00",
  "timeScheduled": "13:45",
  "assignedWorker": 2,
  "info": "",
  "finalassignedOrder": 1, 
  "profit": 1.123
}

The full JSON-body of an assigned task looks like this:

{
  "taskID": 200,
  "externalID": "id123",
  "date": "2019-12-03",
  "duration": 240,
  "timeEarliest": "06:00",
  "timeLatest": "12:00",
  "timePriority": 2,
  "prefWorkers": [
    1,2
  ],
  "antiWorkers": [
    5,6
  ],
  "forbWorkers": [
    3,4
  ],
  "qualification": 3,
  "categories": [
    1
  ],
  "exchangeableCategories": [
    2,4
  ],
  "preassignedWorker": 2,
  "desiredWorker": 2,
  "prefGender": 1,
  "precedingTasks": [ 
    1,2
  ],
  "predecessorTasks": [ 
    1,2
  ],
  "group": 2,
  "groupOrder": 3,
  "revenue": 2.123,
  "timeScheduled": "13:45",
  "assignedWorker": 2,
  "info": "",
  "finalassignedOrder": 1, 
  "profit": 1.123
}