The Resources API provides the resources necessary to create a planning.
Conundra Resources API (1.27.2)
Download OpenAPI description
Overview
Servers
Mock server
https://developer.conundra.eu/_mock/apis/resource-management/resources-api
Resources API Production
https://api.conundra.eu/resource-management/v1
- Mock serverhttps://developer.conundra.eu/_mock/apis/resource-management/resources-api/employee/{business_id}
- Resources API Productionhttps://api.conundra.eu/resource-management/v1/employee/{business_id}
The Employee was successfully retrieved. Details are in the response body.
Bodyapplication/json
Unique identifier for this Employee.
Example: "employee-42"
The name of this Employee. Both properties are nullable to allow for regional differences.
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.
Example: ["digital side mirrors","driving license D"]
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.
Example: ["Dutch","English"]
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.
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.
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_resourceon anotherEmployeewith overlapping availabilities - unavailability of the
TransportResource.
Example: "0-ABC-123"
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.
Example: ["big bag"]
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 maintains a precision of 4.
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.
Example: ["Employee-label-A"]
[EXPERIMENTAL] Various properties that will have an impact on the planning of a route in PTV OptiFlow.
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 OptiFlow with relevant information for the end users.
Keys should not be blank nor contain periods.
Response
application/json
{ "business_id": "employee-42", "name": { "first_name": "Jan", "last_name": "Van den Berghe" }, "driver_skills": [ "digital side mirrors", "driving license D" ], "skills": [ "Dutch", "English" ], "start_location": { "name": "Conundra", "address_line": "Voordries 41b", "city": "Oosterzele", "zip_code": "9860", "country_code": "BE", "geo_point": { … } }, "home_base": { "business_id": "depot-1" }, "linked_resource": "0-ABC-123", "wont_do": [ "big bag" ], "cost": { "per_kilometer": 0.9, "per_hour": 46.8, "fixed": 213 }, "labels": [ "Employee-label-A" ], "route_settings": { "driving_speed_factor": 1.25, "max_stops_per_shift": 3 }, "custom_data": { "shop_manager": "John Smith" } }
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
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