OTM5 Concepts

UUIDs

OTM5 uses UUIDs (Universally Unique IDentifiers) to identify entities. If used properly, these IDs can be used to identify entities correctly, even if shared among multiple platforms and organization.

Creating UUIDs

You can create a unique UUID in Java using:

Copy
Copied
import java.util.UUID
UUID myUUID = UUID.randomUUID();

And in C# using:

Copy
Copied
using System;
Guid myUUID myuuid = Guid.NewGuid();

Then assign it to the appropriate entity and share it outside your own organization.

Preferably, all organizations should adopt UUIDs as the one and only mechanism to identify an entity and replace other existing string or number based IDs. This will result in a more consistent experience. It also will make it significantly easier to share data among different organizations.

Often systems already rely on other existing IDs. In this case, you can still deterministically use UUIDs in combination with your existing IDs. UUIDs like v5 can be used to gradually transition.

To ensure that UUIDs generated with v5 are unique it is highly recommended to use a namespace in combination with your UUIDs. The namespace must be a valid UUID or an identifier for internally predefined namespace UUIDs. In other words, you can also use your unique domain URL for example. See also this manual for other options.

In Java:

Copy
Copied
import java.util.UUID

// The namespace, can be a UUID that is generated once and then saved in the
// database, config file, or just as a code constant. You can also use a URL for example.
UUID organizationUUID = UUID.randomUUID(); 


// Somewhere else in you code
String myExistingId = "12345";
// Be sure to include your operational name to avoid clashes with other parties using maybe the same IDs.
String myUniqueId = organizationUUID.toString() + myExistingId;
UUID myUUID = UUID.nameUUIDFromBytes(myUniqueId.getBytes());

Or in C#

Copy
Copied
using System;

public static Guid ToGuid(string src)
{
    byte[] stringbytes = Encoding.UTF8.GetBytes(src);
    byte[] hashedBytes = new System.Security.Cryptography
        .SHA1CryptoServiceProvider()
        .ComputeHash(stringbytes);
    Array.Resize(ref hashedBytes, 16);
    return new Guid(hashedBytes);
};

Using UUIDs

It is mandatory to use UUIDs consistently for which 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

Copy
Copied
{
  "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:

Copy
Copied
{
  "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:

Copy
Copied
{
  "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.

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