Skip to content

Action

Actions are dynamic entities that are able to couple together various static entities at a certain moment in time. For instance a Load action couples together a Consignment and a Vehicle at the moment the Loading happens.

There are various types of Actions:

  • The Stop that models visiting a certain location at a certain time and potentially doing several other actions at that location.
  • The Load action, that models loading in one or multiple Consignments into a vehicle or some sort of container.
  • The Unload action, that models unloading one or multiple Consignments from a vehicle or some other sort of container.
  • The HandOver that indicates transferring a consignment from one Actor to another.
  • The Move that models moving between two or more locations, potentially with detailed route information on how to move between these locations.
  • The AttachTransportEquipment that allows you to attach some equipment to the associated vehicle. Note that you can both load/unload and attach/detach TransportEquipments. For instance loading a container on a ship, or attach a trailer to a truck. So choose the one that is most appropriate.
  • The DetachTransportEquipment that allows you to detach some previously attached equipment from the associated vehicle.
  • The Break action that models a mandatory resting period for the driver of the vehicle. During this period the driver is prohibited from doing any driving activities or other work.
  • The Wait action that models waiting at a particular location during the trip. This can be due to various circumstances such as waiting for the vehicle to be transported by a ferry or train. Or because of waiting at frontiers or docks (e.g. the dock of the loading/unload location is occupied) or traffic prohibitions. The driver is allowed to leave the vehicle during this period. An important aspect distinguishing this from the break action is that waiting times can be shortened because of changing circumstances. For example, if the original waiting time was expected to be 15 minutes because of an occupied dock, but the driver is 10 minutes late, the waiting time can be shortened to 5 minutes until the dock is free.
  • The GenericAction for whenever any of the above actions cannot model the situation appropriately.
  • The Weigh action for whenever a vehicle is weighed at a certain location. This can be used to indicate that the vehicle is weighed at a weigh station, or at a loading/unloading location.
Operations

Get a specific Action by its UUID

Request

Security
BearerToken
Path
UUIDstring, (uuid)required

The unique UUID of this Action

curl -i -X GET \
  'https://otm-api-spec.redocly.app/_mock/api/5.9/otm/api/v5/actions/{UUID}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Returned the entity with the provided UUID

Bodyapplication/json
actionTypestringrequired
Value:"load"
Example:"load"
Discriminator
idstring

Uniquely identifies this entity. A URI can be assigned by the client to indicate where more information can be retrieved. Note that every entity always has a unique EntityId. However since, OTM5.2 it is not required to send it in the request. One can be generated for you by the server.

Example:"e81a7aa3-23a6-4089-b916-52b854c7b6f1"
namestring

Name of the entity. For display purposes and search only.

creationDatestring, (date-time)

The creation date of this entity.

lastModifiedstring, (date-time)

The last modified date of this entity. If none is given the creation date is used instead.

contextEventsArray of any(event)

The context events provides some optional information about the events that can provide additional information on the current state of this entity.

For example: your system might send ETA information for the arrival of a vehicle on a location. To make it clear what caused this ETA to be updated, we can include some information about what caused this ETA update by including an event as context. If your ETA update was caused by a location update, this event can be included as context. If the ETA was caused by a traffic accident on the route of the vehicle, you can include that event in the context.

externalAttributesobject
externalIdentifiersArray of objects(externalIdentifiers)

Standardized identifiers of this entity as known in external systems. Use this to exchange repeatable partner or system specific identifiers without overloading externalAttributes.

Example:
[
  {
    "id": "AAA",
    "scheme": "CAS"
  }
]
lifecyclestring(lifecycle)

A lifecycle models when the data in the action is taking place. You can provide the same action in multiple lifecycles to model how it changes over time. For example the planned and realized time of an action taking place can differ because of unforseen circumstances (such as traffic jams).

Enum:"requested""planned""projected""actual""realized"
Example:"planned"
resultobject(action-result)

The result of the action, can only be present in the actual or realized lifecycles. The result has a required status and optional additional info, like a remark and reason (in the case of failure).

remarkstring

Free text field for adding an on remark on this action.

Example:"loading a consignment"
sequenceNrinteger, (int64)

The sequence number of this action within the entity it is taking place. Can be used to indicate order when no times are present

stopany
consignmentany
Example:
{
  "uuid": "047cfa4d-fd8b-47ba-b8e9-87067294d2fa",
  "entityType": "consignment",
  "associationType": "reference"
}
transportEquipmentany
documentsArray of any

Documents that are relevant for this action. Such as a proof-of-delivery photo, or scanned CMR.

locationany
timeFormatstring
Default:"dateTime"
Enum:"dateTime""recurringDateTime""duration"
startTimestring, (date-time)

The time at which the actions starts in ISO format.

Example:"2021-06-23T14:00:00Z"
endTimestring, (date-time)

The time at which the action is completed in ISO format.

Example:"2021-06-23T14:15:00Z"
recurrencestring, (recurrence)

The recurrence of the date time, should only be set when timeFormat is set to recurringDateTime. The recurrence follows the Recurrence Rule specification

durationstring, (duration)

The duration of this action/event, should only be set when timeFormat is set to duration. The duration follows the ISO 8601 specification

Example:"PT168H"
constraintany
Example:
{
  "entity": {
    "id": "89a7bb4d-8720-4db9-aef7-4c3309186c3e",
    "name": "Example combined constraint",
    "value": { … }
  },
  "associationType": "inline"
}
Response
{
  "id": "e81a7aa3-23a6-4089-b916-52b854c7b6f1",
  "lifecycle": "planned",
  "remark": "loading a consignment",
  "consignment": {
    "uuid": "047cfa4d-fd8b-47ba-b8e9-87067294d2fa",
    "entityType": "consignment",
    "associationType": "reference"
  },
  "startTime": "2021-06-23T14:00:00Z",
  "endTime": "2021-06-23T14:15:00Z",
  "constraint": {
    "entity": { … },
    "associationType": "inline"
  },
  "actionType": "load"
}