OTM5 Concepts

UUIDs

OTM5 uses UUIDs (Universally Unique IDentifiers) to identify entities. See also this page for an elaborate explanation of UUIDs

The most important rules for using UUIDs is to use them consistently. Therefore there are two rules:

1. Every UUID should only refer to one single entity, in other words, you cannot reuse UUIDs for different entities.
2. An entity can only have one UUID. So if you need to update the same entity, you need to use the same UUID.

Associations

OTM5 has the notion of associations that allow you to either provide the data inline (complete), or refer to an earlier shared entity using a reference. Within the Simacan platform we use mostly inline data, but also expect and use references for consignments and locations.

Note that as a result of using associations there is an additional level of nesting. For example a load with an inline consignment

{
  "actionType": "load",
  "consignment": {
    "associationType": "inline", // determine whether inline or reference is used
    "entity": {
      // actual consignment information starts here
      "id": "<consignment UUID>",
      "type": "frozen goods",
      ...
    }
  }
}

Whenever this same consignment is used again in the same message, instead of repeating it, it is custom to just use the reference:

{
  "actionType": "unload",
  "consignment": {
    "associationType": "reference",
    "uuid": "<consignment UUID>" // same UUID as used before
  }
}

Lifecycles

Logistics is a tricky domain where involved entities change continously and time is hard to capture. During the lifetime of a trip data is continously updated and enriched the more we know about the real-time situation. To deal with this OTM introduces the concept of lifecycles.

When trip data comes in on the Simacan platform this is usually before execution starts, and thus all data contained is based on whatever is planned to happen. Within the Control Tower, Simacan enriches this data with estimated arrival times based on the real-time traffic data and the GPS updates of the vehicle. So, next to the original stop planned times, we now also have projected times of when the stop is expected to be visited. Once the stop has been visited we also gain the realized times of what actually did happen. Each of these could be different since the real world is often different than what we plan it to be. Lifecycles are used to provide a 'phase' to actions and events. Within the Simacan platform we use these lifecycles in two ways:

1. Provide the latest state of each action. For example, whenever a trip is active the first stop could be realized whereas the following stops have an ETA and are thus in the projected lifecycle. This is used in the otm-api for consignments.
2. Provide multiple states of each action. Whenever a trip is active we might have stops that are realized. In this case we communicate both the original planned data and the potentially different realized data. This is used in the eta-to-otm and realized-trip-to-otm exports.

As a result, it is often the case that the same stop appears multiple times in the list of actions, but with a different lifecycle.

This could look something like (most fields are left out for brevity, this is not a complete trip), notice that the two stops have the same UUID but a different lifecycle:

{
  "entityType": "trip",
  "actions": [
    {
      "associationType": "inline",
      "entity": {
        "actionType": "stop",
        "id": "ec6bbe61-4ce3-4f9e-b41d-c5d413529fe6",
        "lifecycle": "planned",
        "startTime": "2022-05-31T10:00Z"
      }      
    },
    {
      "associationType": "inline",
      "entity": {
        "actionType": "stop",
        "id": "ec6bbe61-4ce3-4f9e-b41d-c5d413529fe6",
        "lifecycle": "realized",
        "startTime": "2022-05-31T10:13Z"
      }      
    }, 
  ]
}

Generally, stops with the same UUID but within different lifecycles are places sequential within the actions (sorted by lifecycle). However whenever the planned and projected/realized stops happen in a different order they can also happen within a different order within the trip.

External Attributes

Logistics and traffic is a complex domain. To avoid bloating OTM5 with too many fields and make the standard more complex OTM5 introduced the concept of external attributes.

External attributes allow you to add data to entities without the need for them to be part of the OTM5 standard itself. Simacan also uses these external attributes, most notably on the trip, the stop, and the consignment.

External attributes are optionally present in the externalAttributes fields and can take any JSON format, but often are just key-value pairs. Below an example of some external attributes on the trip.

{
  "entityType": "trip",
  "name": "My trip",
  "externalAttributes": {
    "tripId": "trip-1234",
    "shift": "Morning shift"
  }
}