Skip to content

Event

Events - like actions - model dynamic entities that couple various static entities at a certain moment in time. Events are used for either real-time updates, or updates on earlier provided data. Notice that in both event types these are updates on earlier provided data, whereas actions are usually used together with the entities they dynamically couple.

There are various kinds of events that fall into the two earlier mentioned kinds.

Real-time updates:

  • The LocationUpdateEvent that provides location data received from some GPS.
  • The SensorUpdateEvent that provides sensor value updates (such as temperature or speed measurements) received from a sensor.
  • The StartMovingEvent, StopMovingEvent, StartEngineEvent, StopEngineEvent that indicate events provided by Fleet Management Systems.

Both real-time and projected/realized events

  • The EmissionEvent that contains information about how much emission has been produced during a move / on a trip / per consignment. Can be provided as an actual value, projected based on some calculation, or realized as measured by some sensor.
  • The FuelConsumedEvent that contains information about how much fuel was consumed during a move / on a trip / per consignment. Can be provided as an actual value, projected based on some calculation, or realized as measured by some sensor.
  • The WeighEvent that contains information about the weights of the vehicle or transport equipment. This can be from a weighbridge, tare weight, manual or from a sensor. Updates on earlier provided data:
  • The UpdateEvent that is used to update an earlier provided entity with new information. Note that only the changed data has to be provided.
  • The AssociationCreatedEvent and AssociationRemovedEvent that allow for static entities to be coupled after the fact. Such as coupling a Vehicle to a Trip.
Operations

Get a specific Event by its UUID

Request

Security
BearerToken
Path
UUIDstring, (uuid)required

The unique UUID of this Event

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

Responses

Returned the entity with the provided UUID

Bodyapplication/json
eventTypestringrequired
Value:"associationCreatedEvent"
Example:"associationCreatedEvent"
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:"fc6b2b0c-2f0a-40c6-a580-212c5c7984c8"
namestring

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

Example:"couple vehicle to trip"
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

External attributes are a simple way to add information in an OpenTripModel message that could not fit into one of the OTM fields otherwise. The externalAttributes member is meant for additional meta data and/or additional ID's of an entity. This can also help to identify an OTM entity in a system by the ID of that system.

Please, use this with caution: having too many external attributes can be a sign of not using OpenTripModel as it was intended.

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"
entity1any(entity-association)required
Example:
{
  "uuid": "50824123-0924-4563-ac1e-ca0e37487823",
  "entityType": "trip",
  "associationType": "reference"
}
entity2any(entity-association)required
Example:
{
  "entity": {
    "id": "b9bb914d-845e-46f2-91ff-31fa4bac2fbe",
    "name": "Bob's Boxtruck",
    "vehicleType": "boxtruck",
    "fuel": "electricity",
    "loadCapacities": [ … ],
    "length": { … },
    "height": { … },
    "width": { … },
    "licensePlate": "AB-12-CD",
    "emptyWeight": { … },
    "entityType": "vehicle"
  },
  "associationType": "inline"
}
actorsArray of any

The actors that are relevant to this event, such as the carrier or shipper it belongs to.

Response
{
  "id": "fc6b2b0c-2f0a-40c6-a580-212c5c7984c8",
  "name": "couple vehicle to trip",
  "lifecycle": "planned",
  "entity1": {
    "uuid": "50824123-0924-4563-ac1e-ca0e37487823",
    "entityType": "trip",
    "associationType": "reference"
  },
  "entity2": {
    "entity": { … },
    "associationType": "inline"
  },
  "eventType": "associationCreatedEvent"
}