Create Employee Availability

Request

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.

Security

clientCredentials

Path

employee_idstring^[a-zA-Z0-9.~\-_]{1,512}$required

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

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:

minimal

Indicate no response is needed, can be omitted

["return=minimal"]

representation

Request the result of the operation as response

["return=representation"]

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

Payload

{
  "start_location": {
    "address": { … },
    "home_base": { … },
    "at_last_end": false,
    "name": "PTV Logistics",
    "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": false
  },
  "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
}

Responses

Availability created.

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.