The Resources API provides the resources necessary to create a planning.
- Delete Shift Schedule
Create Shift Schedule
Get all Shift Schedules by Employee
Update Shift Schedule
Delete Shift Schedule
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
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
Headers Examples:
Bodyapplication/jsonThe 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.
Indicate no response is needed, can be omitted
Request the result of the operation as response
The start date and start week number of this shift schedule
The one-based index of the template at which this schedule starts. This allows you to offset the week from which the application start extrapolating the potential availability of an Employee. This can be useful for instances where an Employee has a multi-week schedule but you want the even and uneven weeks to line up with the weeks of the year.
The index should always be within the bounds of the schedule's template indices.
Example: 1
List of non-null objects describing one calendar week (MON-SUN) worth of shifts.
One-based index that determines the order in the schedule. Indices should be consecutive within a ShiftSchedule, without gaps. Setting up a schedule with a recurring week off can be achieved by providing an empty shift-array within the corresponding week's template.
List of non-null shifts in this calendar week. The list can remain empty to represent a recurring week off.
Shifts should not overlap within one template, but can also not overlap with the adjoining shift of other templates. The last shift within a template will be validated against the first shift of the next template. When this template is the last template of the schedule the application will roll over to the first template of the schedule for validating the non-overlapping constraint. This also means a single-week schedule should not have any overlap between the last and first shift of the schedule.
The start range for this specific shift.
Specifies a time on a specified day of the week.
The limits of the duration of this shift.
The minimal duration of a shift. Must be an ISO-8601 compliant Duration string. If provided, it must be strictly positive and greater than or equal to start.window.
Example: "PT8H"
Indicates whether the resulting combination is required to be used when planned.
Default false
Example: true
By default, each Shift will start on the start_location defined on the Employee. By specifying this start_location, this Employee will start this Shift on this start_location.
Either a home_base or a address must be provided.
[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.
The duration an employee is contractually expected to work during this shift. This value is used to determine whether the employee worked more or less than expected based on their contract. Note that only the at_least and at_most durations for the current shift influence the work time that will be planned for this shift.
If this field is provided, it must be specified for each shift within the shift schedule. Additionally, acceptable_additional_work_time must be defined for each calender week.
The value must be a zero or positive ISO 8601-compliant duration. [EXPERIMENTAL]
Example: "PT8H"
The additional time an employee is willing to work, if needed, beyond their contractual hours during the current calendar week. This value is used to determine whether the employee’s actual work time exceeds what they are willing to work — defined as the sum of their contractual work time and this additional work time.
If this field is provided, contractual_work_time must also be specified for each shift in the calendar week.
The value must be a strictly positive ISO 8601-compliant duration. [EXPERIMENTAL]
Example: "PT4H"
- Mock serverhttps://developer.conundra.eu/_mock/apis/resource-management/resources-api/employee/{business_id}/shift-schedule/{generated_id}
- Resources API Productionhttps://api.conundra.eu/resource-management/v1/employee/{business_id}/shift-schedule/{generated_id}
Shift Schedule updated
Bodyapplication/json
The unique ShiftSchedule ID, generated by the application upon creation.
Example: "f22896d0-ed42-4a14-a935-7a29072bc5ac"
The start date and start week number of this shift schedule
The one-based index of the template at which this schedule starts. This allows you to offset the week from which the application start extrapolating the potential availability of an Employee. This can be useful for instances where an Employee has a multi-week schedule but you want the even and uneven weeks to line up with the weeks of the year.
The index should always be within the bounds of the schedule's template indices.
Example: 1
List of non-null objects describing one calendar week (MON-SUN) worth of shifts.
One-based index that determines the order in the schedule. Indices should be consecutive within a ShiftSchedule, without gaps. Setting up a schedule with a recurring week off can be achieved by providing an empty shift-array within the corresponding week's template.
List of non-null shifts in this calendar week. The list can remain empty to represent a recurring week off.
Shifts should not overlap within one template, but can also not overlap with the adjoining shift of other templates. The last shift within a template will be validated against the first shift of the next template. When this template is the last template of the schedule the application will roll over to the first template of the schedule for validating the non-overlapping constraint. This also means a single-week schedule should not have any overlap between the last and first shift of the schedule.
The start range for this specific shift.
Specifies a time on a specified day of the week.
The limits of the duration of this shift.
The minimal duration of a shift. Must be an ISO-8601 compliant Duration string. If provided, it must be strictly positive and greater than or equal to start.window.
Example: "PT8H"
Indicates whether the resulting combination is required to be used when planned.
Default false
Example: true
By default, each Shift will start on the start_location defined on the Employee. By specifying this start_location, this Employee will start this Shift on this start_location.
Either a home_base or a address must be provided.
[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.
The duration an employee is contractually expected to work during this shift. This value is used to determine whether the employee worked more or less than expected based on their contract. Note that only the at_least and at_most durations for the current shift influence the work time that will be planned for this shift.
If this field is provided, it must be specified for each shift within the shift schedule. Additionally, acceptable_additional_work_time must be defined for each calender week.
The value must be a zero or positive ISO 8601-compliant duration. [EXPERIMENTAL]
Example: "PT8H"
The additional time an employee is willing to work, if needed, beyond their contractual hours during the current calendar week. This value is used to determine whether the employee’s actual work time exceeds what they are willing to work — defined as the sum of their contractual work time and this additional work time.
If this field is provided, contractual_work_time must also be specified for each shift in the calendar week.
The value must be a strictly positive ISO 8601-compliant duration. [EXPERIMENTAL]
Example: "PT4H"
Response
application/json
{ "id": "f22896d0-ed42-4a14-a935-7a29072bc5ac", "name": "Standard 38H", "start": { "start_date": "2014-08-16", "start_week": 1 }, "templates": [ { … } ] }
- Mock serverhttps://developer.conundra.eu/_mock/apis/resource-management/resources-api/employee/{business_id}/shift-schedule/{generated_id}
- Resources API Productionhttps://api.conundra.eu/resource-management/v1/employee/{business_id}/shift-schedule/{generated_id}
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