ReDoc documentation

Conundra Resources API (1.12.0)

Download OpenAPI specification:Download

URL: https://servicedesk.conundra.eu License: Terms & conditions Terms of Service

The Resources API provides the resources necessary to create a planning.

Changelog

  • Add end_location to Employee Availability. [EXPERIMENTAL]

Health check

Miscellaneous endpoints for general API functionality

Health check

The ping-endpoint can be used for validating a connection with the application. It will authenticate the caller and respond pong if everything is set-up correctly.

Securitykeycloak
Responses
200

Returned when the application is responsive and you are authenticated.

401

Authentication required

get/ping
Response samples
text/plain
pong

Employee

Endpoints used for managing the general information regarding your Employees. These endpoints are meant for managing Employees whose role is relevant for the functionality in Resource Management, ie: typically only those Employees capable of operating TransportResources.

Find out more

Upsert Employee

Create or update an Employee. A unique ID (business_id) is required to identify the Employee. Calling this endpoint with an existing business_id will update the Employee.

Modifying (or retrieving) an Employee will provide the caller with a version number for this Employee. This version can be passed to the upsert endpoint as a weak ETag in the If-Match header. This allows the caller to ensure that the Employee has not been modified since the last time it was retrieved.

Securitykeycloak
Request
path Parameters
business_id
required
string^[a-zA-Z0-9.~\-_]+$

Unique identifier for this Employee. Should only contain characters which do not need URL encoding.

header Parameters
Prefer
Array of strings

The RFC7240 Prefer header indicates that a particular server behavior is preferred by the client but is not required for successful completion of the request (see RFC 7240).

The following behavior (see Examples) is supported by this API:

  • return=<minimal|representation> is used to suggest the server to return using 204 without resource (minimal) or using 200 or 201 with resource (representation) in the response body on success.
Examples:
Indicate no response is needed, can be omitted
return=minimal
Request the result of the operation as response
return=representation
If-Match
string

Weak Etag used for optimistic locking.

Example: W/"24"
Request Body schema: application/json
object (EmployeeName)

The name of this Employee. Both properties are nullable to allow for regional differences.

driver_skills
Array of strings

driver_skills are only meaningful in relation to a linked TransportResource. They are skills of the Employee that determine the feasibility of a ResourceCombination and the resulting capabilities of this ResourceCombination.

skills
Array of strings

skills are inherent to the Employee regardless of the vehicle they are operating, such as language skills. They are available to the ResourceCombination, regardless of the linked TransportResource.

object (NamedGeoAddress)

An ad-hoc location from which this Employee will start each work shift, unless otherwise specified on more specific entities. When using an ad-hoc location, the Employee will only be assigned to TransportResources with a matching start_location (name-based match).

Either address information or geo point must be provided. Resolved address information will be read only and be filled out after resolving.

Either a home_base or a start_location must be provided.

object (LinkedHomeBase)

The business_id of a known HomeBase in the system. This represents the location from which this Employee will start each work shift, unless otherwise specified on more specific entities. When located at a HomeBase, the Employee will only be assigned to TransportResources with a matching home_base. This is conceptually the same as using an ad-hoc start_location, but with centralized address management which automatically propagates changes on the root entity.

Either a home_base or a start_location must be provided.

linked_resource
string

A reference to the TransportResource (by business_id) which should be linked to this Employee if possible. The algorithm will try to adhere to this requirement as much as possible, but this may not be possible in case of:

  • differing start_location/home_base
  • conflicting linked_resource on another Employee with overlapping availabilities
  • unavailability of the TransportResource.
wont_do
Array of strings

Allows you to control the capabilities of a ResourceCombination for this Employee. This property can be used to disable a TransportResource's capabilities.

A use case could be disabling one type of cargo due. Suppose the Employee is unable to handle the big bag cargo type, but you chose to define cargo types as capabilities on the TransportResource, you can add big bag to this Employee's won't do.

object (Cost)

Costs associated with this Employee, which will be combined with assigned TransportResources in the resulting ResourceCombination. These costs help steer the optimization algorithm towards an optimal solution.

The addition of costs is precision-safe, so decimal values can be used.

labels
Array of strings

Labels provided by the Employee to its ResourceCombination. Using labels allows you to select subsets of ResourceCombinations for use in an optimization by configuring them in the Resource Filter.

driving_speed_factor
number <double> > 0

[EXPERIMENTAL] This is the factor by which the default speed of the resulting ResourceCombination gets multiplied.

A use case could be a learning driver that might drive 10% slower than his/her colleagues. Setting the driving_speed_factor to 0.90 ensures the optimization algorithm takes this into account.

object (CustomData)

Custom data is an extendable hashmap of key-value pairs for client usage. These values have no meaning in the context of Resource Management, but can be used to enrich the data in Order Book with relevant information for the end users.

Keys should not be blank nor contain periods.

Responses
201

Employee created or updated

204

Employee created or updated

400

Bad request

404

Not found

409

Conflict

412

This status is returned when an entity is updated with an outdated version in the If-Match header.

put/employee/{business_id}
Request samples
application/json
{
  • "name": {
    },
  • "driver_skills": [
    ],
  • "skills": [
    ],
  • "start_location": {
    },
  • "home_base": {
    },
  • "linked_resource": "0-ABC-123",
  • "wont_do": [
    ],
  • "cost": {
    },
  • "labels": [
    ],
  • "driving_speed_factor": 1.25,
  • "custom_data": {
    }
}
Response samples
application/json
{
  • "business_id": "employee-42",
  • "name": {
    },
  • "driver_skills": [
    ],
  • "skills": [
    ],
  • "start_location": {
    },
  • "home_base": {
    },
  • "linked_resource": "0-ABC-123",
  • "wont_do": [
    ],
  • "cost": {
    },
  • "labels": [
    ],
  • "driving_speed_factor": 1.25,
  • "custom_data": {
    }
}

Get Employee

Get an existing Employee, defined by their business_id.

Securitykeycloak
Request
path Parameters
business_id
required
string^[a-zA-Z0-9.~\-_]+$

The unique ID (business_id) used to create this Employee.

Responses
200

The Employee was successfully retrieved. Details are in the response body.

404

Not found

get/employee/{business_id}
Response samples
application/json
{
  • "business_id": "employee-42",
  • "name": {
    },
  • "driver_skills": [
    ],
  • "skills": [
    ],
  • "start_location": {
    },
  • "home_base": {
    },
  • "linked_resource": "0-ABC-123",
  • "wont_do": [
    ],
  • "cost": {
    },
  • "labels": [
    ],
  • "driving_speed_factor": 1.25,
  • "custom_data": {
    }
}

Delete Employee

Delete an Employee, defined by their business_id. Removing an Employee will remove all related sub-resources.

Note: Deployed ResourceCombinations (eg: used in a released route in an optimization) will not be removed.

Securitykeycloak
Request
path Parameters
business_id
required
string^[a-zA-Z0-9.~\-_]+$

A unique identifier of an entity instance. Should only contain characters which do not need URL encoding.

header Parameters
If-Match
string

Weak Etag used for optimistic locking.

Example: W/"24"
Responses
204

Deletion has succeeded and body is empty. Sub-resources will be removed asynchronously.

400

Bad request

404

Not found

412

This status is returned when an entity is updated with an outdated version in the If-Match header.

delete/employee/{business_id}
Response samples
application/problem+json
{
  • "title": "Validation exception",
  • "detail": "The field contains invalid business formatting.",
  • "violations": [
    ]
}

Shift Schedule

ShiftSchedules can be used to describe the recurring pattern for an Employee's availability. They do not trigger availabilities themselves, but can be used to generate availabilities according to this schedule, through the application's user interface.

Providing ShiftSchedules enables planners to do long-term planning using the Employee Overview in the UI, since this allows us to predict when an Employee should be available.

Find out more

Create Shift Schedule

Endpoint to create a ShiftSchedule. An identifier will be generated by the application. This identifier can be retrieved from the Location header, or response body (if the Prefer header is set to return=representation).

Securitykeycloak
Request
path Parameters
business_id
required
string^[a-zA-Z0-9.~\-_]+$

The business id of the Employee to create a ShiftSchedule for.

header Parameters
Prefer
Array of strings

The RFC7240 Prefer header indicates that a particular server behavior is preferred by the client but is not required for successful completion of the request (see RFC 7240).

The following behavior (see Examples) is supported by this API:

  • return=<minimal|representation> is used to suggest the server to return using 204 without resource (minimal) or using 200 or 201 with resource (representation) in the response body on success.
Examples:
Indicate no response is needed, can be omitted
return=minimal
Request the result of the operation as response
return=representation
Request Body schema: application/json
name
string

An optional name for this ShiftSchedule.

required
object (ShiftScheduleStart)

The start date and start week number of this shift schedule

required
Array of objects (RecurrencePeriod) non-empty

List of non-null objects describing one calendar week (MON-SUN) worth of shifts.

Responses
201

Shift Schedule created

204

Shift Schedule created

400

Bad request

404

A Not Found is triggered on creation, if the Employee does not exist.

409

A conflict occurs when the ShiftSchedule overlaps with an existing ShiftSchedule.

Note: Since there is no end date on a ShiftSchedule, it is only possible to create 1 ShiftSchedule. Trying to add a second one will always overlap with the existing one.

post/employee/{business_id}/shift-schedule
Request samples
application/json
{
  • "name": "Standard 38H",
  • "start": {
    },
  • "templates": [
    ]
}
Response samples
application/json
{
  • "id": "f22896d0-ed42-4a14-a935-7a29072bc5ac",
  • "name": "Standard 38H",
  • "start": {
    },
  • "templates": [
    ]
}

Get all Shift Schedules by Employee

Retrieve all ShiftSchedules for a given Employee, identified by their business id.

Securitykeycloak
Request
path Parameters
business_id
required
string^[a-zA-Z0-9.~\-_]+$

The business id of the Employee to retrieve ShiftSchedules for.

Responses
200

Known ShiftSchedules for the Employee. List may be empty if no ShiftSchedules were found.

404

A Not Found is triggered on retrieval, if the Employee does not exist.

get/employee/{business_id}/shift-schedule
Response samples
application/json
[
  • {
    }
]

Update Shift Schedule

Update an existing ShiftSchedule for an Employee.

The generated_id is determined by the application and was returned on creation. A list of existing ShiftSchedules can be retrieved by using the getShiftSchedulesByEmployeeId endpoint.

Securitykeycloak
Request
path Parameters
business_id
required
string^[a-zA-Z0-9.~\-_]+$

The business id of the Employee to update this ShiftSchedule for.

generated_id
required
string <uuid>

The generated_id of the ShiftSchedule to update.

header Parameters
Prefer
Array of strings

The RFC7240 Prefer header indicates that a particular server behavior is preferred by the client but is not required for successful completion of the request (see RFC 7240).

The following behavior (see Examples) is supported by this API:

  • return=<minimal|representation> is used to suggest the server to return using 204 without resource (minimal) or using 200 or 201 with resource (representation) in the response body on success.
Examples:
Indicate no response is needed, can be omitted
return=minimal
Request the result of the operation as response
return=representation
If-Match
string

Weak Etag used for optimistic locking.

Example: W/"24"
Request Body schema: application/json
name
string

An optional name for this ShiftSchedule.

required
object (ShiftScheduleStart)

The start date and start week number of this shift schedule

required
Array of objects (RecurrencePeriod) non-empty

List of non-null objects describing one calendar week (MON-SUN) worth of shifts.

Responses
201

Shift Schedule updated

204

Shift Schedule updated

400

Bad request

404

A Not Found is triggered on retrieval, if either the Employee or the ShiftSchedule does not exist.

412

This status is returned when an entity is updated with an outdated version in the If-Match header.

put/employee/{business_id}/shift-schedule/{generated_id}
Request samples
application/json
{
  • "name": "Standard 38H",
  • "start": {
    },
  • "templates": [
    ]
}
Response samples
application/json
{
  • "id": "f22896d0-ed42-4a14-a935-7a29072bc5ac",
  • "name": "Standard 38H",
  • "start": {
    },
  • "templates": [
    ]
}

Delete Shift Schedule

Update an existing ShiftSchedule for an Employee.

The generated_id is determined by the application and was returned on creation. A list of existing ShiftSchedules can be retrieved by using the getShiftSchedulesByEmployeeId endpoint.

Securitykeycloak
Request
path Parameters
business_id
required
string^[a-zA-Z0-9.~\-_]+$

The business id of the Employee to delete this ShiftSchedule for.

generated_id
required
string <uuid>

The generated_id of the ShiftSchedule to delete.

header Parameters
If-Match
string

Weak Etag used for optimistic locking.

Example: W/"24"
Responses
204

Deletion has succeeded and body is empty

404

Not found

412

This status is returned when an entity is updated with an outdated version in the If-Match header.

delete/employee/{business_id}/shift-schedule/{generated_id}
Response samples
application/problem+json
{
  • "title": "Validation exception",
  • "detail": "The field contains invalid business formatting."
}

Availability

Availabilities define a specific time range during which an Employee is available to execute tasks. These can either be derived from a ShiftSchedule (via the user interface) or created on an ad-hoc basis.

When an Availability is created or updated, it triggers a consolidation process that generates a snapshot of the corresponding Employee at that moment, referred to as an AvailableEmployee. This snapshot accounts for relocations (managed through the user interface) and Unavailabilities, ensuring a single source of truth for the Employee's status at that point in time.

Any modifications to this AvailableEmployee snapshot activate an algorithm that evaluates potential ResourceCombinations involving the Employee's Availability. During this evaluation, potential TransportResources are assessed. If the heuristic identifies that a specific ResourceCombination would enhance the overall solution's fitness, it is either created or updated.

Find out more

Get all Employee Availabilities

Retrieves all Availabilities for a single Employee (identified by their business_id) within an optional time range.

This endpoint will return any overlapping Availability, so it is possible for the returned Availability to have a time range that spills outside of the provided time range. Overlap is determined for the widest possible range on an Availability, ie: earliest_startup until (calculated)latest_stop`.

When providing a time range, it can be open (either from or until is provided) or closed (both from and until are provided).

Securitykeycloak
Request
path Parameters
business_id
required
string^[a-zA-Z0-9.~\-_]+$

The unique identifier of the Employee for whom to retrieve Availabilities.

query Parameters
from
string <date-time>

The start of the time range to retrieve Availabilities for. If not provided, the time range will be open-ended, starting from the earliest Availability for this Employee.

Example: from=2021-01-01T10:15:30Z
until
string <date-time>

The end of the time range to retrieve Availabilities for. If not provided, the time range will be open-ended, ending at the latest Availability for this Employee.

If both from and until are provided, until must not be lower than from.

Example: until=2021-01-05T10:15:30Z
Responses
200

Employee Availabilities that overlap with the provided time range. This list can be empty. Each item contains the Availability's version for optimistic locking purposes.

400

Bad request

404

The Employee was not found.

get/employee/{business_id}/availability
Response samples
application/json
[
  • {
    }
]

Create Employee Availability

Add an Availability for an Employee. An identifier will be generated by the application. This identifier can be retrieved from the Location header, or response body (if the Prefer header is set to return=representation).

New Availabilities should not overlap with existing Availabilities.

Securitykeycloak
Request
path Parameters
business_id
required
string^[a-zA-Z0-9.~\-_]+$

The unique identifier of the Employee for whom to create an Availability.

header Parameters
Prefer
Array of strings

The RFC7240 Prefer header indicates that a particular server behavior is preferred by the client but is not required for successful completion of the request (see RFC 7240).

The following behavior (see Examples) is supported by this API:

  • return=<minimal|representation> is used to suggest the server to return using 204 without resource (minimal) or using 200 or 201 with resource (representation) in the response body on success.
Examples:
Indicate no response is needed, can be omitted
return=minimal
Request the result of the operation as response
return=representation
Request Body schema: application/json
object (NamedGeoAddress)

An ad-hoc location from which this Employee will start this specific work shift. This overrides the ad-hoc start_location or home base on the Employee. When using an ad-hoc location, the Employee will only be assigned to TransportResources with a matching start_location (name-based match).

Either address information or geo point must be provided. Resolved address information will be read-only and be filled out after resolving.

An ad-hoc start_location is mutually exclusive with providing a home_base, but neither is mandatory for an Availability.

home_base_id
string

The business_id of a known HomeBase in the system. This represents the location from which this Employee will start this specific work shift. This overrides the ad-hoc start_location or home base on the Employee. When located at a HomeBase, the Employee will only be assigned to TransportResources with a matching home_base. This is conceptually the same as using an ad-hoc start_location, but with centralized address management which automatically propagates changes on the root HomeBase entity.

A home_base is mutually exclusive with providing an ad-hoc start_location, but neither is mandatory for an Availability.

object
earliest_start
required
string <date-time>

The earliest instant that the Employee can start this work shift.

latest_start
string <date-time>

The latest instant that the Employee can start this work shift. If not provided, the optimization will potentially introduce wait time starting from the earliest_start if this Employee is used to execute tasks.

latest_stop
string <date-time>

The latest time at which the availability should end. This can be useful for defining schedules with a lenient start window, but where the Employee has a hard stop at a certain time. It should be between (earliest_start + min_duration) and (latest_start + max_duration).

If no latest_stop is provided, it will be extrapolated from the latest_start and max_duration properties.

min_duration
string

The minimal duration of a shift during the Availability. Must be an ISO-8601 compliant Duration string. If no min_duration is provided, the application will treat the max_duration as the min_duration when it needs to determine the timeframe in which this shift ends.

max_duration
required
string

The maximum duration of a shift during the Availability. Must be an ISO-8601 compliant Duration string.

mandatory
boolean
Default: false

Indicates whether the resulting combination is required to be used when planned

Responses
201

Availability created.

204

Availability created

400

Bad request

404

Not found

409

A conflict occurs when the Availability overlaps with an existing Availability. There should be no overlap between availabilities, since this could lead to overlapping deployments of the same Employee.

post/employee/{business_id}/availability
Request samples
application/json
{
  • "start_location": {
    },
  • "home_base_id": "a-home-base-id",
  • "end_location": {
    },
  • "earliest_start": "2021-01-01T04:15:30Z",
  • "latest_start": "2021-01-01T06:00:00Z",
  • "latest_stop": "2021-01-01T16:00:00Z",
  • "min_duration": "PT8H",
  • "max_duration": "PT12H",
  • "mandatory": true
}
Response samples
application/json
{
  • "id": "f22896d0-ed42-4a14-a935-7a29072bc5ac",
  • "employee_id": "employee-42",
  • "start_location": {
    },
  • "home_base_id": "a-home-base-id",
  • "end_location": {
    },
  • "earliest_start": "2021-01-01T04:15:30Z",
  • "latest_start": "2021-01-01T06:00:00Z",
  • "latest_stop": "2021-01-01T16:00:00Z",
  • "min_duration": "PT8H",
  • "max_duration": "PT12H",
  • "mandatory": true
}

Delete Employee Availabilities

Delete all existing Employee Availabilities that overlap using an open or closed a time range. Overlap is determined for the widest possible range on an Availability, ie: earliest_startup until (calculated)latest_stop`.

Note: Any overlapping Availabilities will be removed, an Availability` can be partially outside of the provided time range.

Securitykeycloak
Request
path Parameters
business_id
required
string^[a-zA-Z0-9.~\-_]+$

A unique identifier of an entity instance. Should only contain characters which do not need URL encoding.

query Parameters
from
string <date-time>
Example: from=2021-01-01T10:15:30Z
until
string <date-time>
Example: until=2021-01-05T10:15:30Z
Responses
204

Deletion has succeeded and body is empty

400

Bad request

404

Not found

delete/employee/{business_id}/availability
Response samples
application/problem+json
{
  • "title": "Validation exception",
  • "detail": "The field contains invalid business formatting.",
  • "violations": [
    ]
}

Get Employee Availability

Retrieve an existing Availability, identified by its generated_id, for an Employee, identified by their business_id.

Securitykeycloak
Request
path Parameters
business_id
required
string^[a-zA-Z0-9.~\-_]+$

The unique identifier of the Employee for whom to retrieve an Availability.

generated_id
required
string <uuid>

The unique identifier of the Availability to retrieve.

Responses
200

Employee Availability is retrieved

404

No Availability found with this generated_id for the specified Employee.

get/employee/{business_id}/availability/{generated_id}
Response samples
application/json
{
  • "id": "f22896d0-ed42-4a14-a935-7a29072bc5ac",
  • "employee_id": "employee-42",
  • "start_location": {
    },
  • "home_base_id": "a-home-base-id",
  • "end_location": {
    },
  • "earliest_start": "2021-01-01T04:15:30Z",
  • "latest_start": "2021-01-01T06:00:00Z",
  • "latest_stop": "2021-01-01T16:00:00Z",
  • "min_duration": "PT8H",
  • "max_duration": "PT12H",
  • "mandatory": true
}

Update Employee Availability

Update a specific Availability, identified by its generated_id, for an Employee, identified by their business_id. The updated Availability should not overlap with existing Availabilities.

Securitykeycloak
Request
path Parameters
business_id
required
string^[a-zA-Z0-9.~\-_]+$

The unique identifier of the Employee for whom to update an Availability.

generated_id
required
string <uuid>

The unique identifier of the Availability to update.

header Parameters
Prefer
Array of strings

The RFC7240 Prefer header indicates that a particular server behavior is preferred by the client but is not required for successful completion of the request (see RFC 7240).

The following behavior (see Examples) is supported by this API:

  • return=<minimal|representation> is used to suggest the server to return using 204 without resource (minimal) or using 200 or 201 with resource (representation) in the response body on success.
Examples:
Indicate no response is needed, can be omitted
return=minimal
Request the result of the operation as response
return=representation
If-Match
string

Weak Etag used for optimistic locking.

Example: W/"24"
Request Body schema: application/json
object (NamedGeoAddress)

An ad-hoc location from which this Employee will start this specific work shift. This overrides the ad-hoc start_location or home base on the Employee. When using an ad-hoc location, the Employee will only be assigned to TransportResources with a matching start_location (name-based match).

Either address information or geo point must be provided. Resolved address information will be read-only and be filled out after resolving.

An ad-hoc start_location is mutually exclusive with providing a home_base, but neither is mandatory for an Availability.

home_base_id
string

The business_id of a known HomeBase in the system. This represents the location from which this Employee will start this specific work shift. This overrides the ad-hoc start_location or home base on the Employee. When located at a HomeBase, the Employee will only be assigned to TransportResources with a matching home_base. This is conceptually the same as using an ad-hoc start_location, but with centralized address management which automatically propagates changes on the root HomeBase entity.

A home_base is mutually exclusive with providing an ad-hoc start_location, but neither is mandatory for an Availability.

object
earliest_start
required
string <date-time>

The earliest instant that the Employee can start this work shift.

latest_start
string <date-time>

The latest instant that the Employee can start this work shift. If not provided, the optimization will potentially introduce wait time starting from the earliest_start if this Employee is used to execute tasks.

latest_stop
string <date-time>

The latest time at which the availability should end. This can be useful for defining schedules with a lenient start window, but where the Employee has a hard stop at a certain time. It should be between (earliest_start + min_duration) and (latest_start + max_duration).

If no latest_stop is provided, it will be extrapolated from the latest_start and max_duration properties.

min_duration
string

The minimal duration of a shift during the Availability. Must be an ISO-8601 compliant Duration string. If no min_duration is provided, the application will treat the max_duration as the min_duration when it needs to determine the timeframe in which this shift ends.

max_duration
required
string

The maximum duration of a shift during the Availability. Must be an ISO-8601 compliant Duration string.

mandatory
boolean
Default: false

Indicates whether the resulting combination is required to be used when planned

Responses
201

Availability updated.

204

Availability updated.

400

Bad request

404

Not found

412

This status is returned when an entity is updated with an outdated version in the If-Match header.

put/employee/{business_id}/availability/{generated_id}
Request samples
application/json
{
  • "start_location": {
    },
  • "home_base_id": "a-home-base-id",
  • "end_location": {
    },
  • "earliest_start": "2021-01-01T04:15:30Z",
  • "latest_start": "2021-01-01T06:00:00Z",
  • "latest_stop": "2021-01-01T16:00:00Z",
  • "min_duration": "PT8H",
  • "max_duration": "PT12H",
  • "mandatory": true
}
Response samples
application/json
{
  • "id": "f22896d0-ed42-4a14-a935-7a29072bc5ac",
  • "employee_id": "employee-42",
  • "start_location": {
    },
  • "home_base_id": "a-home-base-id",
  • "end_location": {
    },
  • "earliest_start": "2021-01-01T04:15:30Z",
  • "latest_start": "2021-01-01T06:00:00Z",
  • "latest_stop": "2021-01-01T16:00:00Z",
  • "min_duration": "PT8H",
  • "max_duration": "PT12H",
  • "mandatory": true
}

Delete Employee Availability by id

Delete an existing Availability, identified by its generated_id, for an Employee, identified by their business_id. This will remove a ResourceCombination tied to this Availability if it was not deployed by releasing a route in an optimization.

Securitykeycloak
Request
path Parameters
business_id
required
string^[a-zA-Z0-9.~\-_]+$

The unique identifier of the Employee for whom to delete an Availability.

generated_id
required
string <uuid>

The unique identifier of the Availability to delete.

header Parameters
If-Match
string

Weak Etag used for optimistic locking.

Example: W/"24"
Responses
204

Deletion has succeeded and body is empty

404

Not found

412

This status is returned when an entity is updated with an outdated version in the If-Match header.

delete/employee/{business_id}/availability/{generated_id}
Response samples
application/problem+json
{
  • "title": "Validation exception",
  • "detail": "The field contains invalid business formatting."
}

Unavailability [EXPERIMENTAL]

Unavailabilities define a specific time range during which an Employee is unavailable to execute tasks. This can be due to sickness, holiday, or other temporary absences. During its duration, the employee can not be matched with a transport resource and used as part of the planning.

[EXPERIMENTAL] Create Employee Unavailability

Create an unavailability for an employee

Securitykeycloak
Request
path Parameters
business_id
required
string^[a-zA-Z0-9.~\-_]+$

A unique identifier of an entity instance. Should only contain characters which do not need URL encoding.

header Parameters
Prefer
Array of strings

The RFC7240 Prefer header indicates that a particular server behavior is preferred by the client but is not required for successful completion of the request (see RFC 7240).

The following behavior (see Examples) is supported by this API:

  • return=<minimal|representation> is used to suggest the server to return using 204 without resource (minimal) or using 200 or 201 with resource (representation) in the response body on success.
Examples:
Indicate no response is needed, can be omitted
return=minimal
Request the result of the operation as response
return=representation
Request Body schema: application/json
from
required
string <date-time>
to
required
string <date-time>
description
string
Responses
201

Employee Unavailability created

204

Employee Unavailability created

400

Bad request

404

Not found

412

This status is returned when an entity is updated with an outdated version in the If-Match header.

post/employee/{business_id}/unavailability
Request samples
application/json
{
  • "from": "2021-01-01T06:00:00Z",
  • "to": "2021-01-10T06:00:00Z",
  • "description": "holiday"
}
Response samples
application/json
{
  • "id": "f22896d0-ed42-4a14-a935-7a29072bc5ac",
  • "employee_id": "employee-42",
  • "from": "2021-01-01T06:00:00Z",
  • "to": "2021-01-10T06:00:00Z",
  • "description": "holiday"
}

[EXPERIMENTAL] Get all Employee Unavailabilities by Employee business id

Get all Employee Unavailabilities by Employee business id. When a from and until are provided, we match any Unavailabilities that overlap with this range.

Securitykeycloak
Request
path Parameters
business_id
required
string^[a-zA-Z0-9.~\-_]+$

A unique identifier of an entity instance. Should only contain characters which do not need URL encoding.

query Parameters
from
string <date-time>
Example: from=2021-01-01T10:15:30Z
until
string <date-time>
Example: until=2021-01-05T10:15:30Z
Responses
200

Employee Unavailabilities are retrieved

400

Bad request

404

Not found

get/employee/{business_id}/unavailability
Response samples
application/json
[
  • {
    }
]

[EXPERIMENTAL] Upsert Employee Unavailability

Create or update an unavailability for an employee.

Securitykeycloak
Request
path Parameters
generated_id
required
string <uuid>

A generated identifier for an entity instance.

business_id
required
string^[a-zA-Z0-9.~\-_]+$

A unique identifier of an entity instance. Should only contain characters which do not need URL encoding.

header Parameters
Prefer
Array of strings

The RFC7240 Prefer header indicates that a particular server behavior is preferred by the client but is not required for successful completion of the request (see RFC 7240).

The following behavior (see Examples) is supported by this API:

  • return=<minimal|representation> is used to suggest the server to return using 204 without resource (minimal) or using 200 or 201 with resource (representation) in the response body on success.
Examples:
Indicate no response is needed, can be omitted
return=minimal
Request the result of the operation as response
return=representation
If-Match
string

Weak Etag used for optimistic locking.

Example: W/"24"
Request Body schema: application/json
from
required
string <date-time>
to
required
string <date-time>
description
string
Responses
201

Employee Unavailability created or updated.

204

Employee Unavailability created or updated.

400

Bad request

404

Not found

put/employee/{business_id}/unavailability/{generated_id}
Request samples
application/json
{
  • "from": "2021-01-01T06:00:00Z",
  • "to": "2021-01-10T06:00:00Z",
  • "description": "holiday"
}
Response samples
application/json
{
  • "id": "f22896d0-ed42-4a14-a935-7a29072bc5ac",
  • "employee_id": "employee-42",
  • "from": "2021-01-01T06:00:00Z",
  • "to": "2021-01-10T06:00:00Z",
  • "description": "holiday"
}

[EXPERIMENTAL] Delete Employee Unavailability by id

Securitykeycloak
Request
path Parameters
generated_id
required
string <uuid>

A generated identifier for an entity instance.

business_id
required
string^[a-zA-Z0-9.~\-_]+$

A unique identifier of an entity instance. Should only contain characters which do not need URL encoding.

header Parameters
If-Match
string

Weak Etag used for optimistic locking.

Example: W/"24"
Responses
204

Employee Unavailability deleted

400

Bad request

404

Not found

412

This status is returned when an entity is updated with an outdated version in the If-Match header.

delete/employee/{business_id}/unavailability/{generated_id}
Response samples
application/problem+json
{
  • "title": "Validation exception",
  • "detail": "The field contains invalid business formatting.",
  • "violations": [
    ]
}

[EXPERIMENTAL] Get Employee Unavailability by id

Securitykeycloak
Request
path Parameters
generated_id
required
string <uuid>

A generated identifier for an entity instance.

business_id
required
string^[a-zA-Z0-9.~\-_]+$

A unique identifier of an entity instance. Should only contain characters which do not need URL encoding.

Responses
200

Employee Unavailability retrieved

404

Not found

get/employee/{business_id}/unavailability/{generated_id}
Response samples
application/json
{
  • "id": "f22896d0-ed42-4a14-a935-7a29072bc5ac",
  • "employee_id": "employee-42",
  • "from": "2021-01-01T06:00:00Z",
  • "to": "2021-01-10T06:00:00Z",
  • "description": "holiday"
}

Transport Resource

Endpoints used for managing the general information regarding your Transport Resources. These can be Trucks, Trailers and Tractors.

Upsert Transport Resource

Upsert a single TransportResource.

As a TransportResource is considered to be always available unless a TransportResourceUnavailability says otherwise, its presence will result in the application trying to create ResourceCombinations by matching AvailableEmployees with this TransportResource.

Securitykeycloak
Request
path Parameters
business_id
required
string^[a-zA-Z0-9.~\-_]+$

A unique identifier of an entity instance. Should only contain characters which do not need URL encoding.

header Parameters
Prefer
Array of strings

The RFC7240 Prefer header indicates that a particular server behavior is preferred by the client but is not required for successful completion of the request (see RFC 7240).

The following behavior (see Examples) is supported by this API:

  • return=<minimal|representation> is used to suggest the server to return using 204 without resource (minimal) or using 200 or 201 with resource (representation) in the response body on success.
Examples:
Indicate no response is needed, can be omitted
return=minimal
Request the result of the operation as response
return=representation
If-Match
string

Weak Etag used for optimistic locking.

Example: W/"24"
Request Body schema: application/json
type
required
string (ResourceType)

A TRACTOR is a pulling unit, a TRAILER a cargo unit and a TRUCK is both a pulling and cargo unit.

Enum: "TRACTOR" "TRAILER" "TRUCK"
license_plate
string
requirements
Array of strings unique

List of requirements the Employee must fulfill to be allowed to use this TransportResource.

capabilities
Array of strings unique

Capabilities this TransportResource provides to the ResourceCombination.

required_capabilities
Array of strings unique

List of requirements the Employee must fulfill, which will be provided as capabilities to the ResourceCombination.

skilled_capabilities
Array of strings unique

List of capabilities which will be provided to the ResourceCombination, if the Employee has matching driver_skills.

cant_do
Array of strings unique

List of capabilities which will be disabled on the resulting ResourceCombination. For example: A TRACTOR with a faulty electric plug, can not be used with a TRAILER that exposes a capability which requires this plug.

Array of objects (Capacity) [ 1 .. 8 ] items unique

These capacities mirror the Order Book capacities.

linked_resource
string

The business_id of another TransportResource on the same location that should be coupled with this one no matter what. This is known as a fixed coupling.

By using this you can indicate that a tractor should always be coupled with a specific trailer (or the other way around). There is no need to specify the linking in both directions. This overwrites all requirements and as such could lead to seemingly invalid situations, but this is at the discretion of the planner.

object (NamedGeoAddress)

The start_location where this TransportResource is based.

Either address information or geo point must be provided. The resolved information will be read only and be filled out after resolving.

Either a home_base or a start_location must be provided.

object (LinkedHomeBase)

Conceptually the same as start_location, but with centralized address management.

Either a home_base or a start_location must be provided.

reference
string

Optional, internal reference (eg: fleet number, ...) for the TransportResource.

object (CustomData)

Custom data is an extendable hashmap of key-value pairs for client usage. These values have no meaning in the context of Resource Management, but can be used to enrich the data in Order Book with relevant information for the end users.

Keys should not be blank nor contain periods.

labels
Array of strings

Labels provided by the TransportResource for its Combination.

inactive
boolean
Default: false

Flag to indicate whether a TransportResource can be used for creating ResourceCombinations. When set to true, all future ResourceCombinations will be removed.

object (Cost)
object (Characteristics)

[EXPERIMENTAL] Technical characteristics of this Transport Resource.

Responses
201

Transport Resource created or updated

204

Transport Resource created or updated

400

Bad request

404

Not found

412

This status is returned when an entity is updated with an outdated version in the If-Match header.

put/transport-resource/{business_id}
Request samples
application/json
{
  • "type": "TRACTOR",
  • "license_plate": "1-ABC-987",
  • "requirements": [
    ],
  • "capabilities": [
    ],
  • "required_capabilities": [
    ],
  • "skilled_capabilities": [
    ],
  • "cant_do": [
    ],
  • "capacities": [
    ],
  • "linked_resource": "trailer-1",
  • "start_location": {
    },
  • "home_base": {
    },
  • "reference": "fleet-reference-47",
  • "custom_data": {
    },
  • "labels": [
    ],
  • "inactive": false,
  • "cost": {
    },
  • "characteristics": {
    }
}
Response samples
application/json
{
  • "business_id": "tractor-1",
  • "type": "TRACTOR",
  • "license_plate": "1-ABC-987",
  • "requirements": [
    ],
  • "capabilities": [
    ],
  • "required_capabilities": [
    ],
  • "skilled_capabilities": [
    ],
  • "cant_do": [
    ],
  • "capacities": [
    ],
  • "linked_resource": "trailer-1",
  • "start_location": {
    },
  • "home_base": {
    },
  • "reference": "fleet-reference-47",
  • "custom_data": {
    },
  • "labels": [
    ],
  • "inactive": false,
  • "cost": {
    },
  • "characteristics": {
    }
}

Get Transport Resource by business id

Get an existing TransportResource

Securitykeycloak
Request
path Parameters
business_id
required
string^[a-zA-Z0-9.~\-_]+$

A unique identifier of an entity instance. Should only contain characters which do not need URL encoding.

Responses
200

Transport Resource is retrieved

404

Not found

get/transport-resource/{business_id}
Response samples
application/json
{
  • "business_id": "tractor-1",
  • "type": "TRACTOR",
  • "license_plate": "1-ABC-987",
  • "requirements": [
    ],
  • "capabilities": [
    ],
  • "required_capabilities": [
    ],
  • "skilled_capabilities": [
    ],
  • "cant_do": [
    ],
  • "capacities": [
    ],
  • "linked_resource": "trailer-1",
  • "start_location": {
    },
  • "home_base": {
    },
  • "reference": "fleet-reference-47",
  • "custom_data": {
    },
  • "labels": [
    ],
  • "inactive": false,
  • "cost": {
    },
  • "characteristics": {
    }
}

Delete Transport Resource by business id

Delete an existing TransportResource.

Upon deleting, the application will also remove ResourceCombinations using this TransportResource and try to find replacements. All unavailabilities and relocations related to this TransportResource will be removed as well.

Securitykeycloak
Request
path Parameters
business_id
required
string^[a-zA-Z0-9.~\-_]+$

A unique identifier of an entity instance. Should only contain characters which do not need URL encoding.

header Parameters
If-Match
string

Weak Etag used for optimistic locking.

Example: W/"24"
Responses
204

Deletion has succeeded and body is empty

400

Bad request

404

Not found

412

This status is returned when an entity is updated with an outdated version in the If-Match header.

delete/transport-resource/{business_id}
Response samples
application/problem+json
{
  • "title": "Validation exception",
  • "detail": "The field contains invalid business formatting.",
  • "violations": [
    ]
}

Unavailability [EXPERIMENTAL]

Unavailabilities define a specific time range during which a TransportResource is unavailable. This can be due to, for example, technical issues. During its duration, the TransportResource can not be matched with an available Employee and used as part of the planning.

[EXPERIMENTAL] Create TransportResource Unavailability

This endpoint allows you to create an Unavailability with a generated ID. This can be used for ad hoc Unavailabilities or situations where the source system does not contain any unique IDs.

See the PUT operation for more information on the functional impact of adding a new unavailability.

Securitykeycloak
Request
path Parameters
business_id
required
string^[a-zA-Z0-9.~\-_]+$

A unique identifier of an entity instance. Should only contain characters which do not need URL encoding.

header Parameters
Prefer
Array of strings

The RFC7240 Prefer header indicates that a particular server behavior is preferred by the client but is not required for successful completion of the request (see RFC 7240).

The following behavior (see Examples) is supported by this API:

  • return=<minimal|representation> is used to suggest the server to return using 204 without resource (minimal) or using 200 or 201 with resource (representation) in the response body on success.
Examples:
Indicate no response is needed, can be omitted
return=minimal
Request the result of the operation as response
return=representation
Request Body schema: application/json
from
required
string <date-time>
to
required
string <date-time>

must be strictly greater than from

description
string
Responses
201

Unavailability created.

204

Unavailability created

400

Bad request

404

Not found

post/transport-resource/{business_id}/unavailability
Request samples
application/json
{
  • "from": "2021-01-01T06:00:00Z",
  • "to": "2021-01-10T06:00:00Z",
  • "description": "maintenance"
}
Response samples
application/json
{
  • "id": "string",
  • "transport_resource_id": "tractor-1",
  • "from": "2021-01-01T06:00:00Z",
  • "to": "2021-01-10T06:00:00Z",
  • "description": "maintenance"
}

[EXPERIMENTAL] Get all TransportResource Unavailabilities by TransportResource business id

Get all TransportResource Unavailabilities by TransportResource business id. When a from and until are provided, we match any Unavailabilities that overlap with this range.

Securitykeycloak
Request
path Parameters
business_id
required
string^[a-zA-Z0-9.~\-_]+$

A unique identifier of an entity instance. Should only contain characters which do not need URL encoding.

query Parameters
from
string <date-time>
Example: from=2021-01-01T10:15:30Z
until
string <date-time>
Example: until=2021-01-05T10:15:30Z
Responses
200

Transport Resource is retrieved

400

Bad request

404

Not found

get/transport-resource/{business_id}/unavailability
Response samples
application/json
[
  • {
    }
]

[EXPERIMENTAL] Upsert TransportResource Unavailability

Create or update a TransportResourceUnavailability.

When a TransportResource becomes unavailable, the ResourceCombinations whose guaranteed working time overlapped with the unavailability are deleted. For other overlaps the existing combinations are only re-evaluated.

Securitykeycloak
Request
path Parameters
generated_id
required
string <uuid>

A generated identifier for an entity instance.

business_id
required
string^[a-zA-Z0-9.~\-_]+$

the business id of the TransportResource for which to add an unavailability

header Parameters
Prefer
Array of strings

The RFC7240 Prefer header indicates that a particular server behavior is preferred by the client but is not required for successful completion of the request (see RFC 7240).

The following behavior (see Examples) is supported by this API:

  • return=<minimal|representation> is used to suggest the server to return using 204 without resource (minimal) or using 200 or 201 with resource (representation) in the response body on success.
Examples:
Indicate no response is needed, can be omitted
return=minimal
Request the result of the operation as response
return=representation
If-Match
string

Weak Etag used for optimistic locking.

Example: W/"24"
Request Body schema: application/json
from
required
string <date-time>
to
required
string <date-time>

must be strictly greater than from

description
string
Responses
201

Unavailability updated.

204

Unavailability updated.

400

Bad request

404

Not found

put/transport-resource/{business_id}/unavailability/{generated_id}
Request samples
application/json
{
  • "from": "2021-01-01T06:00:00Z",
  • "to": "2021-01-10T06:00:00Z",
  • "description": "maintenance"
}
Response samples
application/json
{
  • "id": "string",
  • "transport_resource_id": "tractor-1",
  • "from": "2021-01-01T06:00:00Z",
  • "to": "2021-01-10T06:00:00Z",
  • "description": "maintenance"
}

[EXPERIMENTAL] Delete TransportResource Unavailability by id

Securitykeycloak
Request
path Parameters
generated_id
required
string <uuid>

A generated identifier for an entity instance.

business_id
required
string^[a-zA-Z0-9.~\-_]+$

A unique identifier of an entity instance. Should only contain characters which do not need URL encoding.

header Parameters
If-Match
string

Weak Etag used for optimistic locking.

Example: W/"24"
Responses
204

Unavailability deleted

400

Bad request

404

Not found

delete/transport-resource/{business_id}/unavailability/{generated_id}
Response samples
application/problem+json
{
  • "title": "Validation exception",
  • "detail": "The field contains invalid business formatting.",
  • "violations": [
    ]
}

[EXPERIMENTAL] Get TransportResource Unavailability by id

Securitykeycloak
Request
path Parameters
generated_id
required
string <uuid>

A generated identifier for an entity instance.

business_id
required
string^[a-zA-Z0-9.~\-_]+$

A unique identifier of an entity instance. Should only contain characters which do not need URL encoding.

Responses
200

Transport Resource Unavailability is retrieved

404

Not found

get/transport-resource/{business_id}/unavailability/{generated_id}
Response samples
application/json
{
  • "id": "string",
  • "transport_resource_id": "tractor-1",
  • "from": "2021-01-01T06:00:00Z",
  • "to": "2021-01-10T06:00:00Z",
  • "description": "maintenance"
}

Home Base [EXPERIMENTAL]

A Home Base is a reusable address that is used to specify the location of Employees or Transport Resources. Instead of specifying a full address for each of these, the user can create a single reusable HomeBase and assign it to all.

Updates to an assigned HomeBase are propagated to all future resources using it.

[EXPERIMENTAL] Upsert Home Base

Upsert a single HomeBase. Once it is created Employees and Transport Resources can make use of it.

Securitykeycloak
Request
path Parameters
business_id
required
string^[a-zA-Z0-9.~\-_]+$

A unique identifier of an entity instance. Should only contain characters which do not need URL encoding.

Request Body schema: application/json
name
string

Name of the home base

object (GeoAddress)

Either address information should be present, or otherwise the geo point. The resolved information will be read only and be filled out after resolving.

plan_group
string

the plan group to which this HomeBase belongs

Responses
201

HomeBase created or updated

204

HomeBase created or updated

400

Bad request

412

This status is returned when an entity is updated with an outdated version in the If-Match header.

put/home-base/{business_id}
Request samples
application/json
{
  • "name": "Ghent - Headquarters",
  • "address": {
    },
  • "plan_group": "cargo planning"
}
Response samples
application/json
{
  • "name": "Ghent - Headquarters",
  • "address": {
    },
  • "plan_group": "cargo planning"
}

[EXPERIMENTAL] Get Home Base

Get a single HomeBase.

Securitykeycloak
Request
path Parameters
business_id
required
string^[a-zA-Z0-9.~\-_]+$

A unique identifier of an entity instance. Should only contain characters which do not need URL encoding.

Responses
204

HomeBase retrieved

400

Bad request

404

Not found

get/home-base/{business_id}
Response samples
application/json
{
  • "name": "Ghent - Headquarters",
  • "address": {
    },
  • "plan_group": "cargo planning"
}

[EXPERIMENTAL] Delete Home Base

Delete a single HomeBase.

A HomeBase can only be deleted when there are no resources left referring to it.

Securitykeycloak
Request
path Parameters
business_id
required
string^[a-zA-Z0-9.~\-_]+$

A unique identifier of an entity instance. Should only contain characters which do not need URL encoding.

Responses
204

HomeBase deleted

400

Bad request

409

Conflict

412

This status is returned when an entity is updated with an outdated version in the If-Match header.

delete/home-base/{business_id}
Response samples
application/problem+json
{
  • "title": "Validation exception",
  • "detail": "The field contains invalid business formatting.",
  • "violations": [
    ]
}

Forecast [EXPERIMENTAL]

A forecast is the expected the number of shifts that will be required on the given day and location. They is used in the context of capacity planning: a difference in the forecast and the available shifts can indicate ue in the planning. The provided forecasts are only used to show to the end user and are not taken into account for any of the calculations made by the application.

[EXPERIMENTAL] Upsert Forecast

Upsert a single Forecast

Securitykeycloak
Request
path Parameters
date
required
string <date>

Date for which to upsert a forecast

Example: 2023-10-01
location
required
string

Name of the location for which to upsert the forecast

Example: Ghent
header Parameters
Prefer
Array of strings

The RFC7240 Prefer header indicates that a particular server behavior is preferred by the client but is not required for successful completion of the request (see RFC 7240).

The following behavior (see Examples) is supported by this API:

  • return=<minimal|representation> is used to suggest the server to return using 204 without resource (minimal) or using 200 or 201 with resource (representation) in the response body on success.
Examples:
Indicate no response is needed, can be omitted
return=minimal
Request the result of the operation as response
return=representation
Request Body schema: application/json
expected_shifts
integer >= 0

Expected number of shifts

Responses
201

Forecast created or updated

204

Forecast created or updated

400

Bad request

put/resource-overview/{date}/{location}/forecasts
Request samples
application/json
{
  • "expected_shifts": 27
}
Response samples
application/json
{
  • "expected_shifts": 27,
  • "location": "Ghent",
  • "date": "2023-10-01"
}

[EXPERIMENTAL] Get Forecast

Get a single Forecast.

Securitykeycloak
Request
path Parameters
date
required
string <date>

Date for which to delete the forecast

Example: 2023-10-01
location
required
string

Name of the location for which to delete the forecast

Example: Ghent
Responses
204

Forecast retrieved

400

Bad request

404

Not found

get/resource-overview/{date}/{location}/forecasts
Response samples
application/json
{
  • "expected_shifts": 27,
  • "location": "Ghent",
  • "date": "2023-10-01"
}

[EXPERIMENTAL] Delete Forecast

Delete a single Forecast.

Securitykeycloak
Request
path Parameters
date
required
string <date>

Date for which to delete the forecast

Example: 2023-10-01
location
required
string

Name of the location for which to delete the forecast

Example: Ghent
Responses
204

Forecast deleted

400

Bad request

delete/resource-overview/{date}/{location}/forecasts
Response samples
application/problem+json
{
  • "title": "Validation exception",
  • "detail": "The field contains invalid business formatting.",
  • "violations": [
    ]
}