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: timeEarliest)

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": {
    "workerPrefs": 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,
      "shiftDate": "2019-12-03",
      "shiftEnd": "14:00",
      "shiftStart": "06:00"
    },
    {
      "workerID": 1,
      "shiftDate": "2019-12-03",
      "shiftEnd": "20:00",
      "shiftStart": "15:00"
    },
    {
      "workerID": 2,
      "shiftDate": "2019-12-03",
      "shiftEnd": "14:00",
      "shiftStart": "06:00"
    }
  ],
  "client": {
    "clientID": "{1234-5678-9123}"
  },
  "history": {
    "tasks": [
      {
        "taskID": 0,
        "scheduling": [
          {
            "date": "2000-01-01"
          }
        ]
      }
    ],
    "workers": [
      {
        "workerID": 0
      }
    ]
  }
}

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": true,
  "resQualification": true,
  "accuracyMode": 1.0,
  "outputLanguage": 1,
  "enablePlanSplitting": false,
  "allowUnassignedTasks": 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)
  • resQualification: qualification (Task), qualification (Worker)

Optimization Parameters

Examples:

{}

{
  "fairDistribution": 1,
  "workerPrefs": 1,
  "qualificationFitting": 1,
  "constancy": 1,
  "groupPrefs": 1
}

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

Input Task

Examples:

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

{
  "taskID": 200,
  "externalID": "id123",
  "clientID": 123,
  "date": "2019-12-03",
  "duration": 65,
  "timeEarliest": "10:00",
  "timeLatest": "12:00",
  "timePriority": 2,
  "prefWorkers": [1,2],
  "qualification": 3,
  "categories": [1],
  "preassignedWorker": 2,
  "initassignedWorker": 1,
  "initassignedOrder": 1,
  "initassignedShiftID": 1,
  "precedingTasks": [1, 2],
  "predecessorTasks": [3],
  "assignmentPriority": 2,
  "preferredGroup": 1,
  "locationSiteID": 1,
  "prefGender": 1
}

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

Restrictions

• initassignedOrder requires initassignedWorker or preassignedWorker.
• initassignedShiftID requires initassignedWorker or preassignedWorker.

Notes

• Regarding qualification: Not assigning a worker with a lower qualification is strict behavior, not assigning a worker with higher qualification depends on the qualificationFitting parameter.

Input Worker

Examples:

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

{
  "workerID": 1,
  "shiftID": 10,
  "externalID": "id123",
  "shiftDate": "2019-12-03",
  "shiftStart": "06:00",
  "shiftEnd": "14:00",
  "shiftPriority": 2,
  "qualification": 1,
  "categories": [4,5],
  "dontAlter": true,
  "dontVary": true,
  "gender": 1
}

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

Restrictions

• Only one of dontVary and dontAlter is allowed to be true

History

Examples:

{
  "tasks": [
    {
      "taskID": 0,
      "scheduling": [
        {
          "date": "2000-01-01"
        }
      ]
    }
  ],
  "workers": [
    {
      "workerID": 0
    }
  ]
}

History-Task

Examples:

{
  "taskID": 0,
  "scheduling": [
    {
      "date": "2000-01-01"
    }
  ]
}

History-Assignment

Examples:

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

{
  "date": "2000-01-01",
  "locationSiteID": 1,
  "timeScheduled": "00:00",
  "assignedWorker": 0,
  "assignedShiftID": 1,
  "assignedOrder": 1,
  "timeScheduledAutomatically": "00:00",
  "assignedWorkerAutomatically": 0,
  "assignedShiftIDAutomatically": 1,
  "assignedOrderAutomatically": 1,
  "actualStartTime": "00:00",
  "actualWorker": 0,
  "actualShiftID": 1,
  "actualOrder": 1
}

History-Worker

Examples:

{
  "workerID": 0
}

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

Examples:

{
  "requestID": "id2103",
  "meta": {
    "dateFrom": "2019-12-03",
    "dateTo": "2019-12-03"
  },
  "parameters": {
    "workerPrefs": 1
  },
  "workers": [
    {
      "workerID": 1,
      "shiftStart": "06:00",
      "shiftEnd": "14:00",
      "info": "text",
      "shiftDate": "2019-12-03"
    },
    {
      "workerID": 2,
      "shiftStart": "05:00",
      "shiftEnd": "16:00",
      "shiftDate": "2019-12-03",
      "info": "text",
    }
  ],
  "tasks": [
    {
      "taskID": 200,
      "date": "2019-12-03",
      "duration": 65,
      "timeEarliest": "10:00",
      "timeLatest": "12:00",
      "timeScheduled": "11:01",
      "assignedWorker": 2,
      "info": "This task assignment causes negative arrival slack: -6"
    },
    {
      "taskID": 200,
      "date": "2019-12-03",
      "duration": 65,
      "timeEarliest": "10:00",
      "timeLatest": "12:00",
      "info": "This task was unassigned"
    }
  ],
  "info": {
    "feasible": false
  },
  "statistics": {
    "impact": [
      {
        "label": "Anticategories",
        "value": 0.123
      }
    ],
    "unassignedTaskIDs": [1,2,3],
    "unassignableTaskIDs": [1,2,3]
  },
  "backendVersion": {
    "schema": "v0.49.9",
    "version": "v2.25.12",
    "rev": "abcde12"
  },
  "client": {
    "clientID": "{1234-5678-9123}"
  }
}

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, 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
  "info": "text"
}

{
  ... // see Input Task
  "timeScheduled": "12:10",
  "assignedWorker": 1,
  "info": "text",
  "finalassignedOrder": 4
}

{
  ... // see Input Task
  "timeScheduled": "12:10",
  "assignedWorker": 1,
  "assignedShiftID": 2,
  "info": "text",
  "finalassignedOrder": 4
},

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:

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

{
  ... // See Input Worker
  "info": "text",
  "tourStart": "12:10",
  "tourEnd": "12:30",
  "totalTaskTime": 100
}

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": "Anticategories",
      "value": 0.123
    }
  ],
  "unassignedTaskIDs": [1,2,3],
  "unassignableTaskIDs": [1,2,3],
  "timeWindowViolationTaskIDs": [1,2,3],
  "history": {
    "tasks": [
      {
        "taskID": 1,
        "preassignedWorker": 1,
        "preferences": [
          {
            "workerID": 0,
            "value": 0.123
          }
        ]
      }
    ]
  }
}

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 tasks has the following fields:

Info

Examples:

{
  "feasible": false
}

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.

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,
      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/floor-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 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:

• date for any Time values in Input Task and Output Task.
• shiftDate for any Time values in Input Worker and Output Worker.

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

GenderType

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

LanguageType

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

Weekday

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

Conventions

• All number values of times (task durations, ...) use the unit minutes.
• Days start at 00:00 and end at 23:59.

Deployment Status

Getting the deployed version

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

Changelog

2024-01-23

• In Error Result: Added workerExternalID with tag v0.11.0.
• In Error Result: Added taskExternalID with tag v0.11.0.

2024-01-07

• Added section Checking your requests for validity.

2023-12-13

• In Input Task: Added prefGender with tag v0.10.0.
• In Input Worker: Added gender with tag v0.10.0.
• In History Assignment: Added assignedShiftID with tag v1.0.0.
• In History Assignment: Added assignedOrder with tag v1.0.0.
• In History Assignment: Added assignedShiftIDAutomatically with tag v1.0.0.
• In History Assignment: Added assignedOrderAutomatically with tag v1.0.0.
• In History Assignment: Added actualShiftID with tag v1.0.0.
• In History Assignment: Added actualOrder with tag v1.0.0.

2023-12-03

• In Input Task: Added locationSiteID with tag v1.0.0.
• In History Assignment: Added locationSiteID with tag v1.0.0.

2023-11-11

• In Error Result: Added additionalErrors with tag v0.9.0.

2023-10-21

• In Statistics: Added history with tag v0.8.0.
• In Additional Validation: Added validations 1509-1511 with tag v0.8.0.

2023-10-18

• In Optimization Parameter: Added description text to constancy.
• In Additional Validation: Added validations 1503-1508.

2023-10-16

• Added Additional Validation.

2023-10-12

• In Optimization Parameters: Added groupPrefs with tag v0.7.0.
• In Input Task: Added clientID with tag v0.7.0.
• In Input Task: Added preferredGroup with tag v0.7.0.

2023-09-19

• In Optimization Parameters: Added qualificationFitting with tag v0.2.0.
• In Optimization Parameters: Added constancy with tag v0.2.0.
• In Input Task: Changed "Depends on" entry of qualification, added qualificationFitting with tag v0.2.0.
• In Input Task: Added section "Notes".

2023-09-16

• Created documentation page.