Skip to content
/
Update Employee Availabil...

Conundra Resources API (1.27.2)

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

Download OpenAPI description
resources-api.json
resources-api.yaml
Overview
URL
https://servicedesk.conundra.eu
Servers
Mock server
https://developer.conundra.eu/_mock/apis/resource-management/resources-api
Resources API Production
https://api.conundra.eu/resource-management/v1

Health check

Miscellaneous endpoints for general API functionality

Operations

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.

Operations

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.

Operations

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.

Operations

Get Employee Availability

Request

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

Security
clientCredentials
Path
business_idstring^[a-zA-Z0-9.~\-_]{1,512}$required

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

generated_idstring(uuid)required

The unique identifier of the Availability to retrieve.

Responses

Employee Availability is retrieved

Headers
ETagstring

A weak Etag (ex W/"<etag_value>") which contains the current version of the entity

Example: "W/\"25\""
Bodyapplication/json
idstringread-only

The unique Availability ID.

Example: "f22896d0-ed42-4a14-a935-7a29072bc5ac"
employee_idstring(EmployeeId)^[a-zA-Z0-9.~\-_]+$read-only

The unique Employee ID.

start_locationobject(AvailabilityStartLocation)

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), unless that employee is on a Journey. In that case they will continue to use the same TransportResource until the Journey is done.

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

end_locationobject(EndLocation)

[EXPERIMENTAL] Property to define an endLocation. When left blank, the Employee will make a round-trip and the endLocation will match the startLocation.

Only one option is allowed, either address, home_base or at_last_activity can be set.

earliest_startstring(date-time)required

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

Example: "2021-01-01T04:15:30Z"
latest_startstring(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.

Example: "2021-01-01T06:00:00Z"
latest_stopstring(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.

Example: "2021-01-01T16:00:00Z"
min_durationstring

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.

Example: "PT8H"
max_durationstringrequired

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

Example: "PT12H"
mandatoryboolean

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

Default false
Example: true
home_base_idstringDeprecated

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.

Deprecated in favor of the start_location property.

Example: "a-home-base-id"
Response
application/json
{
  "id": "f22896d0-ed42-4a14-a935-7a29072bc5ac",
  "employee_id": "employee-42",
  "start_location": {
    "address": { … },
    "home_base": { … },
    "at_last_end": false,
    "name": "Conundra",
    "address_line": "Voordries 41b",
    "city": "Oosterzele",
    "zip_code": "9860",
    "country_code": "BE",
    "geo_point": { … }
  },
  "home_base_id": "a-home-base-id",
  "end_location": {
    "address": { … },
    "home_base": { … },
    "at_last_activity": true
  },
  "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

Request

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.

Security
clientCredentials
Path
business_idstring^[a-zA-Z0-9.~\-_]{1,512}$required

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

generated_idstring(uuid)required

The unique identifier of the Availability to update.

Headers
PreferArray 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-Matchstring

Weak Etag used for optimistic locking.

Example: W/"24"
Bodyapplication/json
start_locationobject(AvailabilityStartLocation)

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), unless that employee is on a Journey. In that case they will continue to use the same TransportResource until the Journey is done.

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

end_locationobject(EndLocation)

[EXPERIMENTAL] Property to define an endLocation. When left blank, the Employee will make a round-trip and the endLocation will match the startLocation.

Only one option is allowed, either address, home_base or at_last_activity can be set.

earliest_startstring(date-time)required

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

Example: "2021-01-01T04:15:30Z"
latest_startstring(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.

Example: "2021-01-01T06:00:00Z"
latest_stopstring(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.

Example: "2021-01-01T16:00:00Z"
min_durationstring

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.

Example: "PT8H"
max_durationstringrequired

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

Example: "PT12H"
mandatoryboolean

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

Default false
Example: true
home_base_idstringDeprecated

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.

Deprecated in favor of the start_location property.

Example: "a-home-base-id"

Responses

Availability updated.

Headers
ETagstring

A weak Etag (ex W/"<etag_value>") which contains the current version of the entity

Example: "W/\"25\""
Preference-Appliedstring

Indicates whether a preference has been applied. (ex return=representation)

Locationstring(URI)

A URI to access the result of the operation.

Bodyapplication/json
idstringread-only

The unique Availability ID.

Example: "f22896d0-ed42-4a14-a935-7a29072bc5ac"
employee_idstring(EmployeeId)^[a-zA-Z0-9.~\-_]+$read-only

The unique Employee ID.

start_locationobject(AvailabilityStartLocation)

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), unless that employee is on a Journey. In that case they will continue to use the same TransportResource until the Journey is done.

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

end_locationobject(EndLocation)

[EXPERIMENTAL] Property to define an endLocation. When left blank, the Employee will make a round-trip and the endLocation will match the startLocation.

Only one option is allowed, either address, home_base or at_last_activity can be set.

earliest_startstring(date-time)required

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

Example: "2021-01-01T04:15:30Z"
latest_startstring(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.

Example: "2021-01-01T06:00:00Z"
latest_stopstring(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.

Example: "2021-01-01T16:00:00Z"
min_durationstring

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.

Example: "PT8H"
max_durationstringrequired

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

Example: "PT12H"
mandatoryboolean

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

Default false
Example: true
home_base_idstringDeprecated

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.

Deprecated in favor of the start_location property.

Example: "a-home-base-id"
Response
application/json
{
  "id": "f22896d0-ed42-4a14-a935-7a29072bc5ac",
  "employee_id": "employee-42",
  "start_location": {
    "address": { … },
    "home_base": { … },
    "at_last_end": false,
    "name": "Conundra",
    "address_line": "Voordries 41b",
    "city": "Oosterzele",
    "zip_code": "9860",
    "country_code": "BE",
    "geo_point": { … }
  },
  "home_base_id": "a-home-base-id",
  "end_location": {
    "address": { … },
    "home_base": { … },
    "at_last_activity": true
  },
  "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

Request

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.

Security
clientCredentials
Path
business_idstring^[a-zA-Z0-9.~\-_]{1,512}$required

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

generated_idstring(uuid)required

The unique identifier of the Availability to delete.

Headers
If-Matchstring

Weak Etag used for optimistic locking.

Example: W/"24"

Responses

Deletion has succeeded and body is empty

Response
No content

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.

Operations

Transport Resource

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

Operations

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.

Operations

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.

Operations

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.

Operations

Deployment [EXPERIMENTAL]

Endpoints used for managing Deployments. A Deployment represents the actual assignment of an Employee to one or more TransportResources for a specific time period and location. External deployments can be created to represent work assignments that are managed outside of the Resource Management system. Releasing or unreleasing routes in PTV OptiFlow also manages Deployments. These Deployments are managed internally by Resource Management and cannot be modified by this API.

Operations

Actual

Actuals capture the worked hours for an Employee during a completed work shift. This data is used to provide insights into actual worked hours compared to contractual hours, and also helps steer the optimization algorithm towards creating a balanced work week that fulfills contractual hours without significant undershooting or overshooting.

By their nature, Actuals should always represent completed work shifts and therefore should always be in the past, adding Actuals that end in the future could lead to undesired behaviour.

Operations
Company
PTV Logistics
Copyright © Conundra BV - PTV Logistics GmbH. All right reserved.