Skip to content
/
Get all Shift Schedules b...

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

Create Shift Schedule

Request

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

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

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

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
Bodyapplication/json
namestring

An optional name for this ShiftSchedule.

Example: "Standard 38H"
startobject(ShiftScheduleStart)required

The start date and start week number of this shift schedule

start_datestring(date)required

The calendar day at which this schedule starts.

Example: "2014-08-16"
start_weekinteger>= 1required

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
templatesArray of objects(RecurrencePeriod)non-emptyrequired

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

indexinteger>= 1required

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.

shiftsArray of objects(Shift)required

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.

startobjectrequired

The start range for this specific shift.

earliestobject(TimeInWeek)required

Specifies a time on a specified day of the week.

timestring(Time)^([0-1][0-9]|[2][0-3]):([0-5][0-9])$required

Specify a time, formatted as hh:mm. Supports 00:00-23:59 inclusive.

daystring(DayOfWeek)required

Specifies a day of the week, must match the exhaustive set of values.

Enum"MONDAY""TUESDAY""WEDNESDAY""THURSDAY""FRIDAY""SATURDAY""SUNDAY"
windowstring

Duration from the earliest start until the latest start, formatted as an ISO-8601 compliant Duration string. If provided, it must be positive.

Example: "PT3H"
stopobject

Optional constraints on when this shift should finish.

durationobjectrequired

The limits of the duration of this shift.

at_leaststring

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"
at_moststringrequired

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

Must be:

  • strictly positive,
  • greater than or equal to start.window
  • greater than or equal to at_least if it is provided.
  • lower than P7D (7 days).
Example: "PT12H"
mandatoryboolean

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

Default false
Example: true
start_locationobject(ShiftStartLocation)

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.

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.

contractual_work_timestring

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"
acceptable_additional_work_timestring

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"

Responses

Shift Schedule created

Headers
Preference-Appliedstring

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

Locationstring(URI)

A URI to access the result of the operation.

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 ShiftSchedule ID, generated by the application upon creation.

Example: "f22896d0-ed42-4a14-a935-7a29072bc5ac"
namestring

An optional name for this ShiftSchedule.

Example: "Standard 38H"
startobject(ShiftScheduleStart)required

The start date and start week number of this shift schedule

start_datestring(date)required

The calendar day at which this schedule starts.

Example: "2014-08-16"
start_weekinteger>= 1required

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
templatesArray of objects(RecurrencePeriod)non-emptyrequired

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

indexinteger>= 1required

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.

shiftsArray of objects(Shift)required

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.

startobjectrequired

The start range for this specific shift.

earliestobject(TimeInWeek)required

Specifies a time on a specified day of the week.

timestring(Time)^([0-1][0-9]|[2][0-3]):([0-5][0-9])$required

Specify a time, formatted as hh:mm. Supports 00:00-23:59 inclusive.

daystring(DayOfWeek)required

Specifies a day of the week, must match the exhaustive set of values.

Enum"MONDAY""TUESDAY""WEDNESDAY""THURSDAY""FRIDAY""SATURDAY""SUNDAY"
windowstring

Duration from the earliest start until the latest start, formatted as an ISO-8601 compliant Duration string. If provided, it must be positive.

Example: "PT3H"
stopobject

Optional constraints on when this shift should finish.

durationobjectrequired

The limits of the duration of this shift.

at_leaststring

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"
at_moststringrequired

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

Must be:

  • strictly positive,
  • greater than or equal to start.window
  • greater than or equal to at_least if it is provided.
  • lower than P7D (7 days).
Example: "PT12H"
mandatoryboolean

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

Default false
Example: true
start_locationobject(ShiftStartLocation)

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.

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.

contractual_work_timestring

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"
acceptable_additional_work_timestring

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": [
    { … }
  ]
}

Get all Shift Schedules by Employee

Request

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

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

The business id of the Employee to retrieve ShiftSchedules for.

Responses

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

Bodyapplication/jsonArray [
idstringread-only

The unique ShiftSchedule ID, generated by the application upon creation.

Example: "f22896d0-ed42-4a14-a935-7a29072bc5ac"
namestring

An optional name for this ShiftSchedule.

Example: "Standard 38H"
startobject(ShiftScheduleStart)required

The start date and start week number of this shift schedule

start_datestring(date)required

The calendar day at which this schedule starts.

Example: "2014-08-16"
start_weekinteger>= 1required

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
templatesArray of objects(RecurrencePeriod)non-emptyrequired

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

indexinteger>= 1required

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.

shiftsArray of objects(Shift)required

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.

startobjectrequired

The start range for this specific shift.

earliestobject(TimeInWeek)required

Specifies a time on a specified day of the week.

timestring(Time)^([0-1][0-9]|[2][0-3]):([0-5][0-9])$required

Specify a time, formatted as hh:mm. Supports 00:00-23:59 inclusive.

daystring(DayOfWeek)required

Specifies a day of the week, must match the exhaustive set of values.

Enum"MONDAY""TUESDAY""WEDNESDAY""THURSDAY""FRIDAY""SATURDAY""SUNDAY"
windowstring

Duration from the earliest start until the latest start, formatted as an ISO-8601 compliant Duration string. If provided, it must be positive.

Example: "PT3H"
stopobject

Optional constraints on when this shift should finish.

durationobjectrequired

The limits of the duration of this shift.

at_leaststring

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"
at_moststringrequired

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

Must be:

  • strictly positive,
  • greater than or equal to start.window
  • greater than or equal to at_least if it is provided.
  • lower than P7D (7 days).
Example: "PT12H"
mandatoryboolean

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

Default false
Example: true
start_locationobject(ShiftStartLocation)

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.

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.

contractual_work_timestring

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"
acceptable_additional_work_timestring

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"
versioninteger(Version)

The version of the shift schedule. Present when the shift schedule is returned in a list in a response.

]
Response
application/json
[
  {
    "id": "f22896d0-ed42-4a14-a935-7a29072bc5ac",
    "name": "Standard 38H",
    "start": { … },
    "templates": [ … ],
    "version": 42
  }
]

Update Shift Schedule

Request

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.

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

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

generated_idstring(uuid)required

The generated_id of the ShiftSchedule 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
namestring

An optional name for this ShiftSchedule.

Example: "Standard 38H"
startobject(ShiftScheduleStart)required

The start date and start week number of this shift schedule

start_datestring(date)required

The calendar day at which this schedule starts.

Example: "2014-08-16"
start_weekinteger>= 1required

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
templatesArray of objects(RecurrencePeriod)non-emptyrequired

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

indexinteger>= 1required

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.

shiftsArray of objects(Shift)required

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.

startobjectrequired

The start range for this specific shift.

earliestobject(TimeInWeek)required

Specifies a time on a specified day of the week.

timestring(Time)^([0-1][0-9]|[2][0-3]):([0-5][0-9])$required

Specify a time, formatted as hh:mm. Supports 00:00-23:59 inclusive.

daystring(DayOfWeek)required

Specifies a day of the week, must match the exhaustive set of values.

Enum"MONDAY""TUESDAY""WEDNESDAY""THURSDAY""FRIDAY""SATURDAY""SUNDAY"
windowstring

Duration from the earliest start until the latest start, formatted as an ISO-8601 compliant Duration string. If provided, it must be positive.

Example: "PT3H"
stopobject

Optional constraints on when this shift should finish.

durationobjectrequired

The limits of the duration of this shift.

at_leaststring

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"
at_moststringrequired

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

Must be:

  • strictly positive,
  • greater than or equal to start.window
  • greater than or equal to at_least if it is provided.
  • lower than P7D (7 days).
Example: "PT12H"
mandatoryboolean

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

Default false
Example: true
start_locationobject(ShiftStartLocation)

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.

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.

contractual_work_timestring

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"
acceptable_additional_work_timestring

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"

Responses

Shift Schedule updated

Headers
Preference-Appliedstring

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

Locationstring(URI)

A URI to access the result of the operation.

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 ShiftSchedule ID, generated by the application upon creation.

Example: "f22896d0-ed42-4a14-a935-7a29072bc5ac"
namestring

An optional name for this ShiftSchedule.

Example: "Standard 38H"
startobject(ShiftScheduleStart)required

The start date and start week number of this shift schedule

start_datestring(date)required

The calendar day at which this schedule starts.

Example: "2014-08-16"
start_weekinteger>= 1required

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
templatesArray of objects(RecurrencePeriod)non-emptyrequired

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

indexinteger>= 1required

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.

shiftsArray of objects(Shift)required

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.

startobjectrequired

The start range for this specific shift.

earliestobject(TimeInWeek)required

Specifies a time on a specified day of the week.

timestring(Time)^([0-1][0-9]|[2][0-3]):([0-5][0-9])$required

Specify a time, formatted as hh:mm. Supports 00:00-23:59 inclusive.

daystring(DayOfWeek)required

Specifies a day of the week, must match the exhaustive set of values.

Enum"MONDAY""TUESDAY""WEDNESDAY""THURSDAY""FRIDAY""SATURDAY""SUNDAY"
windowstring

Duration from the earliest start until the latest start, formatted as an ISO-8601 compliant Duration string. If provided, it must be positive.

Example: "PT3H"
stopobject

Optional constraints on when this shift should finish.

durationobjectrequired

The limits of the duration of this shift.

at_leaststring

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"
at_moststringrequired

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

Must be:

  • strictly positive,
  • greater than or equal to start.window
  • greater than or equal to at_least if it is provided.
  • lower than P7D (7 days).
Example: "PT12H"
mandatoryboolean

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

Default false
Example: true
start_locationobject(ShiftStartLocation)

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.

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.

contractual_work_timestring

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"
acceptable_additional_work_timestring

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": [
    { … }
  ]
}

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

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.