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.

Currently the API solely supports JSON formatted data with a schema that is used to validate the data. Non-valid requests are immediately rejected with an error message. In each section a downloadable corresponding JSON schema in the latest version is linked.

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 Deployment Status.

Examples in this documentation will use all listed fields regardless of their introduced version, so please check availability before using them.

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: qualification)
• 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 an 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.

Checking your requests for validity

To check your request json for validity you can download validation scripts here:

Post a new plan

HTTP-Endpoint

This endpoint is used to POST a new problem description for obtaining an optimized plan based on it.

Request

Example

{
  "meta": {
    "dateFrom": "2019-12-03",
    "dateTo": "2019-12-03"
  },
  "parameters": {
    "fairDistribution": 4,
    "timeliness": 5,
    "workerPrefs": 5,
    "workerReduction": 1
  },
  "tasks": [
    {
      "date": "2019-12-03",
      "duration": 65,
      "taskID": 200,
      "timeEarliest": "10:00",
      "timeLatest": "12:00"
    },
    {
      "date": "2019-12-03",
      "duration": 25,
      "taskID": 201,
      "timeEarliest": "16:00",
      "timeLatest": "17:00"
    }
  ],
  "workers": [
    {
      "workerID": 1,
      "shifts": [
        {
          "shiftStart": "08:00",
          "shiftEnd": "20:00",
          "shiftDate": "2019-12-03",
          "shiftID": 1
        }
      ]
    }
  ],
  "client": {
    "clientID": "{1234-5678-9123}"
  }
}

Result

Example of an ID

AAAAAAAAABBBBBBBBBBBBBBBEEEEEEEEEEEEEEEEEDDDDDDDDDD

Posting a plan returns an ID to monitor the planning process and retrieve the solution.

Status-Codes

Client Information

Examples:

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

Restrictions

• Minimum length: 1.

Meta Information

Examples:

{
  "dateFrom": "2019-12-03",
  "dateTo": "2019-12-03"
}

{
  "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,
  "minConcurrentSolutions": 1,
  "minTaskDuration": 10
}

Notes

• 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)

Optimization Parameters

Examples:

{}

{
  "preset": 0,
}

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

All parameters (except preset) 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):

Input Task

Examples:

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

{
  "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,
  "maxQualification": 6,
  "categories": [1],
  "exchangeableCategories": [2,4],
  "preassignedWorker": 2,
  "desiredWorker": 2,
  "prefGender": 1,
  "predecessorTasks": [1,2],
  "group": 2,
  "revenue": 2.123,
  "assignmentPriority": 2,
  "initassignedWorker": 1,
  "initassignedOrder": 1
}

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

Input Worker

Examples:

{
  "workerID": 1
}

{
  "workerID": 1,
  "externalID": "id123",
  "qualification": 1,
  "categories": [1,2],
  "desiredCategory": 12,
  "prefCategories": [3],
  "prefWeekCategories": [2],
  "prefWeekendCategories" : [3],
  "prefWorkers": [5,43],
  "antiWorkers": [5,43],
  "shifts": [
    {
      "shiftStart": "05:00",
      "shiftEnd": "12:00",
      "shiftDate": "2019-12-03"
    }
  ],
  "gender": 1,
  "expectedWorkingMinutes": 9200,
  "minWorkingMinutes": 8000,
  "maxWorkingMinutes": 12000,
  "maxConsecutiveWorkdays": 6,
  "minConsecutiveWorkdays": 6,
  "prefConsecutiveWorkdays": 6,
  "carryoverConsecutiveWorkdays": 0,
  "maxConsecutiveOffdays": 2,
  "minConsecutiveOffdays": 2,
  "prefConsecutiveOffdays": 15,
  "carryoverConsecutiveOffdays": 1,
  "minBreakMinutesBetweenTasks": 600,
  "maxDailyWorkingMinutes": 600,
  "minFreeSaturdays": 4,
  "minFreeSundays": 5,
  "maxWeeklyWorkingMinutes": 3000,
  "carryoverWorkingMinutesLastWeek": 50,
  "maxTwoWeekWorkingMinutes": 4800,
  "carryoverWorkingMinutesSecondLastWeek": 2100,
  "dontVary": true,
  "costsPerMinute": 1.123,
  "costsInitial": 100.12,
  "precTaskDate": "2019-12-02",
  "precTaskScheduled": "12:00",
  "precTaskDuration": 120,
  "precNightShifts": 2,
  "maxOrderedGroups": 2,
  "maxDesiredOrderedGroups": 1,
  "maxNightShifts": 3,
  "maxDesiredNightShifts": 2,
  "minFreeWeekends": 2,
  "minDesiredFreeWeekends": 1,
  "maxConsecutiveSameTaskStart": 1,
  "maxDesiredConsecutiveSameTaskStart": 1,
  "maxWeeklyWorkingDays": 1,
  "prefWeeklyWorkingDays": 1,
  "carryoverWorkingDaysLastWeek": 12,
  "minConsecutiveFreeWeekends": 1,
  "minDesiredConsecutiveFreeWeekends": 1,
  "maxConsecutiveFreeWeekends": 1,
  "maxDesiredConsecutiveFreeWeekends": 1,
  "minConsecutiveWorkingWeekends": 1,
  "minDesiredConsecutiveWorkingWeekends": 1,
  "maxConsecutiveWorkingWeekends": 1,
  "maxDesiredConsecutiveWorkingWeekends": 1,
  "precWeekendWorkingDay": "2019-12-01",
  "carryoverConsecutiveWorkingWeekends": 1
}

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

Restrictions

• Only one of carryoverConsecutiveWorkdays and carryoverConsecutiveOffdays is allowed
• Only one of maxConsecutiveSameTaskStart and maxDesiredConsecutiveSameTaskStart is allowed

Notes

• Categories specified in desiredCategory, prefCategories, prefWeekCategories, prefWeekendCategories are automatically considered valid as if they're listed in categories.

• The parameter precNightShifts is used for carrying over the biorhythm between different, consecutive plans. As such, the tasks on the days directly before the plan start are relevant. As an example, let the plan start on 2020-05-01:

  • If on 2020-04-30 no task was scheduled or a task was scheduled that did not overlap with the midnight to 2020-05-01, the value has to be 0.
  • If on 2020-04-30 a task was scheduled that overlaps with midnight to 2020-05-01, the value has to be at least 1; exactly 1 if this is not true for 2020-04-29.
  • If, additionally to the case above, on 2020-04-29 a task was scheduled that overlaps with midnight to 2020-04-30, the value has to be at least 2; exactly 2 if this is not true for 2020-04-28.
  • And so on...

• If either precTaskDate, precTaskScheduled, or precTaskDuration is set, all of the values have to be set. If precNightShifts is set, all of the three mentioned values have to be set as well.

• Please note the following behavior regarding free weekend consideration (minFreeWeekends, minConsecutiveFreeWeekends, maxConsecutiveFreeWeekends, etc):

  • If the last day of the plan is a Saturday, that weekend will not count as a free weekend.
  • For all weekend counters (e.g. minFreeWeekends): If the first day of the plan is a Sunday, data from precTaskDate will get used to determine if this starting weekend can be "free" or not. If precTaskDate if is earlier than the Saturday and nothing is assigned on Sunday, the weekend is considered a free weekend for this plan, if either the precTaskDate is the Saturday or a task is assigned on Sunday, it is not. If no precTaskDate is given, the weekend will not count as a free weekend regardless.
  • For all consecutive weekend counters (e.g. minConsecutiveFreeWeekends): If precWeekendWorkingDay is set, its data will be used to determine the amount of free weekends before plan start. If it isn't set, zero free weekends before the plan will be assumed. If in addition the first day of the plan (dateFrom) is a Sunday, that weekend will count as a working weekend.

• Important edge case behavior for carryoverConsecutiveWorkingWeekends:

  • dateFrom is not a Sunday: carryoverConsecutiveWorkingWeekends should behave like all carry over data (e.g. carryoverConsecutiveWorkdays) - its value should be the amount of consecutive working weekends (at least one task performed on Saturday or Sunday) directly before the start of the planning horizon (dateFrom). If the last weekend before dateFrom was free, carryoverConsecutiveWorkingWeekends should either not be set or 0.
  • dateFrom is a Sunday, there was a task on the Saturday directly before that (precWeekendWorkingDay should be set to exactly that Saturday): carryoverConsecutiveWorkingWeekends must count the weekend dateFrom is on as a working weekend. E.g. if the last complete weekend before dateFrom was a working weekend, the counter should be at 2.
  • dateFrom is a Sunday but not task was on Saturday: This is the important edge case, since now it's up to the optimizer, whether or not the weekend will be free or not. In this case, the weekend dateFrom is on must not be considered for carryoverConsecutiveWorkingWeekends, the value must act as if dateFrom was on Saturday instead. E.g. if Saturday was free but the last two weekends before that Saturday were working weekends, carryoverConsecutiveWorkingWeekends must be set to 2. This allows the optimizer to carry on with the working weekends streak if it assigns a task on Sunday but also break the streak if it doesn't.

• All fields with "carryover data" (precTaskDate, carryoverConsecutiveWorkdays, ...) are not validated against each other. It is the responsibility of the requester to ensure valid and correct data.

Shift

Examples:

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

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

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

History

Introduced in: v3.4.0

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

{
  "workers": [
    {
      "workerID": 1,
      "excludedDays": [
        "2023-02-12",
        "2023-02-11"
      ]
    }
  ],
  "tasks": [
    {
      "taskID": 1,
      "scheduling": [
        {
          "date": "2023-01-01",
          "assignedWorker": 11,
          "assignedWorkerAutomatically": 11,
          "actualWorker": 1,
          "actualStartTime": "12:30"
        }
      ]
    }
  ],
  "additionalTasks": [
    {
      "taskID": 2,
      "date": "2022-12-31",
      "timeEarliest": "12:00",
      "timeLatest": "12:00",
      "duration": 120
    }
  ]
}

The ShiftPlanner history contains historical data for plan tasks and workers as well as additional tasks that are not part of the optimization but can provide further information for the historical data analysis.

History-Worker

Introduced in: v3.4.0

{
  "workerID": 1
}

{
  "workerID": 1,
  "excludedDays": [
    "2023-02-12",
    "2023-02-11"
  ],
  "preferenceFulfilledOn": [
    "2023-02-12",
    "2023-02-11"
  ],
  "preferenceNotFulfilledOn": [
    "2023-02-12",
    "2023-02-11"
  ]
}

A History-Worker is a worker which is also featured in the workers array of the request, connected via workerID. It provides further worker-specific information to the history entries.

History-Task

Introduced in: v3.4.0

{
  "taskID": 2,
  "scheduling": [
    {
      "date": "2022-12-24",
      "assignedWorker": 2,
      "assignedWorkerAutomatically": 1,
      "actualWorker": 1,
      "actualStartTime": "12:30"
    }
  ]
}

A History-Task contains all historical assignments of the task with its taskID in either the tasks array of the request or the additionalTasks array in the request's history.

History-Assignment

Introduced in: v3.4.0

{
  {
    "date": "2022-12-24"
  }
}

{
  {
    "date": "2022-12-24",
    "assignedWorker": 11,
    "assignedWorkerAutomatically": 11,
    "actualWorker": 1,
    "actualStartTime": "12:30"
  }
}

A History-Assignment contains the data of exactly one historical assignment.

Check status/retrieve a Plan

HTTP-Endpoint

This endpoint is used to get the status of a plan or retrieve the plan once the calculation has been finished.

Request

In the header of the request the field Accept must be set to application/json. The <ID> which was delivered as a result of the post request needs to be given in the URL.

Status-Codes

Result

Example

{
  "meta": {
    "dateFrom": "2019-12-03",
    "dateTo": "2019-12-03"
  },
  "parameters": {
    "fairDistribution": 4,
    "timeliness": 5,
    "workerPrefs": 5,
    "workerReduction": 1
  },
  "tasks": [
    {
      "date": "2019-12-03",
      "duration": 65,
      "taskID": 200,
      "timeEarliest": "10:00",
      "timeLatest": "12:00",
      "timeScheduled": "13:45",
      "assignedWorker": 2,
      "assignedShift": 1,
      "info": "text",
      "finalassignedOrder": 1,
      "profit": 1.123
    },
    {
      "date": "2019-12-03",
      "duration": 25,
      "taskID": 201,
      "timeEarliest": "16:00",
      "timeLatest": "17:00",
      "info": "unassigned task"
    }
  ],
  "workers": [
    {
      "workerID": 1,
      "shifts": [
        {
          "shiftStart": "08:00",
          "shiftEnd": "20:00",
          "shiftDate": "2019-12-03",
          "shiftID": 1
        }
      ],
      "info": "text"
    }
  ],
  "client": {
    "clientID": "{1234-5678-9123}"
  },
  "statistics": {
    "impact": [
      {
        "label": "Minimum consecutive offdays",
        "value": 0.777778
      }
    ],
    "unassignedTaskIDs": [1,2,3],
    "unassignableTaskIDs": [2,3,4]
  },
  "info":{
    "text": "text",
    "feasible": true
  },
  "backendVersion": {
    "schema": "v0.49.9",
    "version": "v2.25.12",
    "rev": "abcde12"
  }
}

The resulting plan mostly extends the Request by the fields marked "Extension" below:

Error Result

Example

{
  "requestID": "id32013",
  "error_msg": " |-| ERROR: Task #12 has itself assigned as preceding task. (129) |-| contact email: support@adiutabyte.de",
  "version": "1.0.0",
  "type": "error",
  "errorID": 129,
  "taskID": 12,
  "backendVersion": {
    "schema": "v0.49.9",
    "version": "v2.25.12",
    "rev": "abcde12"
  },
  "additionalErrors": [
    {
      "errorID": 129,
      "error_msg": " |-| ERROR: Task #13 has itself assigned as preceding task. (129) |-| contact email: support@adiutabyte.de",
      "taskID": 13
    }
  ]
}

If your request contains errors which leads to unsatisfiable plans or an internal error occurred, you will receive a error response instead of a plan.

The objects in additionalErrors contain the following fields:

The error_msg gets translated based on language settings.

Error-ID

A list of errorID values and explanations can be found here.

Backend Version

Examples:

{
  "schema": "v0.0.0"
}

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

Output Task

Examples:

{
  ... // See Input Task
  "timeScheduled": "13:45",
  "assignedWorker": 2,
  "assignedShift": 1,
  "info": "text",
  "finalassignedOrder": 1,
  "profit": 1.123
}

{
  ... // See Input Task
  "info": "text"
}

The json schema for the Output Task extends the schema of the Input Task by all the fields marked "Extension" in the table below. If allowUnassignedTasks was set to true, an "unassigned version" of the output task can be returned which is missing all assignment data.

Output Worker

Examples:

{
  ... // Same as Input Worker
}

{
  ... // See Input Worker
  "info": "text"
}

The json schema for the Output Worker extends the schema of the Input Worker by all the fields marked "Extension" in the table below:

Statistics

Examples:

{
  "impact": [
    {
      "label": "Minimum consecutive offdays",
      "value": 0.777778
    }
  ],
  "timeWindowViolationTaskIDs": [1,2,3],
  "unassignedTaskIDs": [1,2,3],
  "unassignableTaskIDs": [2,3,4],
  "history": {
    "workers": [
      {
        "workerID": 1,
        "weeklyShifts": [
          {
            "weekday": 0,
            "shiftStart": "10:00",
            "shiftEnd": "14:00",
            "workPreferenceFactor": -0.25
          }
        ],
        "minConsecutiveWorkdays": 1,
        "maxConsecutiveWorkdays": 1,
        "minConsecutiveOffdays": 1,
        "maxConsecutiveOffdays": 1,
        "minFreeSaturdays": 1,
        "minFreeSundays": 1,
        "minFreeWeekends": 1,
        "maxWeeklyWorkingDays": 1,
        "maxNightShifts": 1,
        "maxConsecutiveSameTaskStart": 1,
        "preferenceFactor": 1.5
      }
    ]
  }
}

The statistics provide some general data for evaluating the result. They are based on the adjusted data that the optimization is performed on. Differences to the tasks'/workers' input data are noted in their respective info fields.

The history entry contains the data from the history analysis:

Each entry in workers has the following fields.

WeekdayStatisticsData are objects with data for a weekday:

Info

Examples:

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

The info texts provide some textual context to the solution. They are based on the adjusted data that the optimization is performed on. Differences to the tasks'/workers' input data are noted in their respective info fields.

All text in text gets translated based on language setting.

Additional Validation

Every request must adhere to the defined schemas or it cannot be processed. However, even if it does, there might still be issues with the contained data. For that reason, a content validation is performed after accepting the request, the details of which are listed below.

There are multiple times a validation is performed on the input data. If an issue is found, the corresponding error message will tell you exactly at which step the validation failed:

• Validation of raw input data, excluding data excluded by resCategory or resQualification.
• Validation of input data after removing all unassignable tasks (this is only relevant is allowUnassignedTasks is set to true).
• Validation of history adjusted data (this is only relevant if a history is included in the input data)
• Validation after adjusting data (if enablePlanSplitting is true, the error message will tell you which subset of data had the issue).

If allowUnassignedTasks is set to true, the first of these validations is allowed to fail some validations (the list below will tell you which). In this case the task is simply removed from calculation. You can determine these unassignable tasks from their info section in the output or the array unassignableTasks in statistics.

List of all content requirements

Examples

The following examples shall provide a starting point to build from when using the API for the first time. If you'd like to see one added, please contact us.

Posting/ Retrieving a plan

The example to the right provides a simple javascript template to post/get a request/response. Authentication details can be found here.

require('cross-fetch/polyfill');
const fetch = require('cross-fetch');
const AmazonCognitoIdentity = require('amazon-cognito-identity-js');

// authentication
const userPool = new AmazonCognitoIdentity.CognitoUserPool({
  UserPoolId: "[myUserPoolId]", // see authentication page
  ClientId: "[myClientId]" // see authentication page
});

const authenticationDetails = new AmazonCognitoIdentity.AuthenticationDetails({
  Username: "[myUserName]", // see login details of your adiutaByte account
  Password: "[myPassword]"
});

const cognitoUser = new AmazonCognitoIdentity.CognitoUser({
  Username: "[myUserName]", // see login details of your adiutaByte account
  Pool: userPool
});

const token = await new Promise((resolve, reject) => cognitoUser.authenticateUser(authenticationDetails, {
  onSuccess: function (result) {
    const thisToken = result.getIdToken().getJwtToken();
    resolve(thisToken);
  },
  onFailure: function (err) {
    console.log(err);
    reject();
  }
}));

// posting a request
const headers = {
  'Content-Type': 'application/json',
  'Authorization': token
};

const request = {
  meta: {
    dateFrom: "2019-12-03",
    dateTo: "2019-12-03"
  },
  parameters: {},
  tasks: [
    {
      date: "2019-12-03",
      duration: 65,
      taskID: 200,
      timeEarliest: "10:00",
      timeLatest: "12:00"
    }
  ],
  workers: [
    {
      workerID: 1,
      shifts: [
        {
          shiftID: 1,
          shiftStart: "03:00",
          shiftEnd: "12:00",
          shiftDate: "2019-12-03"
        }
      ]
    }
  ]
};

const postOptions = {
  method: 'post',
  headers: new Headers(headers),
  body: JSON.stringify(request)
};

const postURL = `https://[env].compute-adiutabyte.de/shift-description`; // see endpoint section

const ID = await new Promise((resolve, reject) => fetch(postURL, postOptions)
  .then(async res => {
    if (res.ok) {
      const data = await res.json();
      console.log("Successfully posted request! ID:", data);
      resolve(data);
    }
    else {
      console.error("Error while posting request:", res.status);
      reject();
    }
  }));

// get solution
let status = 423;
while (status === 423) {

  const getURL = `https://[env].compute-adiutabyte.de/plan/${ID}`; // see endpoint section

  const getOptions = {
    method: 'get',
    headers: new Headers(headers)
  };

  const solution = await new Promise((resolve, reject) => fetch(getURL, getOptions)
    .then(async res => {
      status = res.status;
      resolve(res);
    }));

  if (status === 200) {
    const solutionText = await solution.text();
    console.log("Solution:", JSON.parse(solutionText));
    break;
  }
  else if (status !== 423) {
    console.error("Error while getting solution:", status);
    break;
  }

  await new Promise(resolve => setTimeout(resolve, 5000));
}

Common plan for scheduling

The following json template can be used as a starting point when creating plans for any time span.

Locked Workers

If only a subset and tasks and workers shall be optimized, it usually suffices to not include theses in your request. However, if those already calculated workers shall be included in info/statistics, there is a way to "lock" these workers for the algorithm (a common use case is re-optimizing a subsection of workers/tasks from a previous request - either to improve the solution or because changes have been made).

All locked workers that shall not receive additional tasks, the flag dontVary needs to be set to true. Any task that is already assigned to this worker needs to have its initassignedWorker or preassignedWorker set to the worker this task is supposed to be assigned to. Additionally it needs to be set at which position in the worker's tour the task should be positioned (initassignedOrder). The request then looks like this:

Common data types

Integers/Numbers

Examples:

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

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.

Date

Examples:

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

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:

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

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

• "hh": hours, $ 0 \leq x \leq 10^{10} -1 $
• "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 Input Task and Output 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".

GenderType

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

LanguageType

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

Weekday

Introduced in: v3.4.0

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

Conventions

• All number values of times (task durations, working time limits, ...) use the unit minutes.
• Days start at 00:00 and end at 23:59.
• Tasks always count towards the date they are assigned on. For example, a task assigned Fri 23:00 - Sat 02:00 will only count towards Friday for all relevant counters: maxDailyWorkingMinutes, minFreeWeekends, ...

Deployment Status

Getting the deployed version

Introduced in: v3.9.0

Aside from checking this page, you can also get the deployed versions via a GET request.

HTTP-Endpoint

Result

{
  "version": "v3.9.15",
  "schema": "v0.78.0",
  "meta-data": "v15",
  "api-scripts": "v1.5.0"
}

Status-Codes

Deprecation Warnings

v4.0.0

• In Input Task: Removed precedingTasks.
• In Input Task: Removed groupOrder.
• In Input Task: Removed initassignedShift.
• In Input Worker: Changed the requirements of dontVary, from initassignedShift to a combination of initassignedWorker and initassignedOrder.
• In Shift: Removed shiftID.
• In Output Task: Removed assignedShift.

Changelog

2024-01-23

• In Error Result: Added workerExternalID with tag v4.1.0.
• In Error Result: Added taskExternalID with tag v4.1.0.

2024-01-07

• Added section Checking your requests for validity.

2023-12-03

• Added deprecation warnings for v4.0.0.
• Added section Deprecation Warnings.
• In Input Task: Deprecated precedingTasks with tag v4.0.0.
• In Input Task: Deprecated groupOrder with tag v4.0.0.
• In Input Task: Deprecated initassignedShift with tag v4.0.0.
• In Input Task: Added initassignedWorker with tag v4.0.0.
• In Input Task: Added initassignedOrder with tag v4.0.0.
• In Input Worker: Updated description for dontVary.
• In Shift: Deprecated shiftID with tag v4.0.0.
• In Output Task: Deprecated assignedShift with tag v4.0.0.
• In Additional Validation: Added validations 1220-1224 with tag v4.0.0, marked validations 1201, 1202, 1205, 1210 - 1214 as removed with tag v4.0.0.
• In Examples: Updated examples to work with v4.0.0.

2023-11-23

• In Additional Validation: Marked validation 1215 as being removed in v3.10.1.
• In Additional Validation: Updated validation 1200 with tag v3.10.1.

2023-11-11

• In Error Result: Added additionalErrors with tag v3.10.0.

2023-10-18

• In Additional Validation: Added validations 1502-1507.

2023-10-16

• Added Additional Validation.

2023-09-12

• In Meta Information: Added minTaskDuration with tag v3.10.0.

2023-08-29

• In Input Worker: Added carryoverConsecutiveWorkingWeekends with tag v3.9.0.
• In Examples: Added Posting/Retrieving a plan.
• Some minor restructuring.

2023-08-13

• In Input Worker: Added minConsecutiveWorkingWeekends with tag v3.9.0.
• In Input Worker: Added minDesiredConsecutiveWorkingWeekends with tag v3.9.0.
• In Input Worker: Added maxConsecutiveWorkingWeekends with tag v3.9.0.
• In Input Worker: Added maxDesiredConsecutiveWorkingWeekends with tag v3.9.0.
• In Output Worker: Added minConsecutiveWorkingWeekends with tag v3.9.0.
• In Output Worker: Added minDesiredConsecutiveWorkingWeekends with tag v3.9.0.
• In Output Worker: Added maxConsecutiveWorkingWeekends with tag v3.9.0.
• In Output Worker: Added maxDesiredConsecutiveWorkingWeekends with tag v3.9.0.

2023-08-09

• In Deployment Status: Added Getting the deployed version with tag v3.9.0.
• In Input Worker: Added minConsecutiveFreeWeekends with tag v3.9.0.
• In Input Worker: Added minDesiredConsecutiveFreeWeekends with tag v3.9.0.
• In Input Worker: Added maxConsecutiveFreeWeekends with tag v3.9.0.
• In Input Worker: Added maxDesiredConsecutiveFreeWeekends with tag v3.9.0.
• In Input Worker: Added precWeekendWorkingDay with tag v3.9.0.
• In Output Worker: Added minConsecutiveFreeWeekends with tag v3.9.0.
• In Output Worker: Added minDesiredConsecutiveFreeWeekends with tag v3.9.0.
• In Output Worker: Added maxConsecutiveFreeWeekends with tag v3.9.0.
• In Output Worker: Added maxDesiredConsecutiveFreeWeekends with tag v3.9.0.
• In Output Worker: Added precWeekendWorkingDay with tag v3.9.0.

2023-08-02

• In Error ID: Moved section to Subpage.

2023-07-05

• In Input Worker: Changed description of field minBreakMinutesBetweenTasks with tag v3.8.35.
• In Statistics: Fixed shiftStart, shiftEnd (in history -> weeklyShifts) being marked "required".

2023-05-25

• In Known Bugs: Added Error 301 when using multi-worker restrictions.

2023-05-12

• Added Examples.
• In Error Result: Added section "Error-ID".

2023-05-08

• In Optimization Types: Renamed Unassigned Task to Input Task.
• In Optimization Types: Renamed Assigned Task to Output Task.
• In Optimization Types: Renamed Unassigned Worker to Input Worker.
• In Optimization Types: Renamed Assigned Worker to Output Worker.

2023-05-03

• In Error Result: Updated error code ranges with tag v3.8.21.

2023-04-22

• Added Deployment Status.

2023-04-14

• In Optimization Parameters: Added preset Random (value: 0) with tag v3.8.16.

2023-04-03

• In Conventions: Added convention.
• In Unassigned Task: Fixed description of timePriority.
• In Meta Information: Changed description of minQualificationOfTaskCoverage with tag v3.8.12.
• In Meta Information: Changed description of omnipresentCategoriesOfTaskCoverage with tag v3.8.12.

2023-03-30

• In Meta Information: Changed resQualification to optional with tag v2.37.0.
• In Meta Information: Changed resCategories to optional with tag v2.37.0.
  • Both these field have been optional since v2.37.0. However, this change was not documented in the API description at the time.

2023-03-24

• In Unassigned Task: Added maxQualification with tag v3.8.0.
• In Assigned Task: Added maxQualification with tag v3.8.0.

2023-03-14

• Created standalone ShiftPlanner documentation.

2023-03-13

• Moved Shift to Optimization Types.
• In Unassigned Task: Changed description of preassignedWorker with tag v3.6.1.
• In Unassigned Worker: Changed description of maxConsecutiveSameTaskStart with tag v3.5.1.
• In Unassigned Worker: Changed description of maxDesiredConsecutiveSameTaskStart with tag v3.5.1.