Concepts

There are various concepts within the Simacan platform that are universal and do not belong to a single component. This page gives an overview of these concepts and how they work.

IDs

The Simacan platform tracks a lot of different entities, such as the trips, locations, consignments, vehicles, etc. Each of these entities needs to be uniquely identifiable. This allows you to unambiguously find, update and delete the entities without any chance for confusion. To ensure this, each ID needs to behave to certain rules.

IDs vs UUIDs

ID is a shorthand for identification, and is the general term for the property of an entity that allows it to be uniquely identified. UUID stands for Universally Unique IDentifier and is a mechanism for identification.

UUIDs have the following two rules:

1. Each UUID can only refer to one entity. So each UUID can appear only once and unambiguously points to that entity. Since UUIDs are meant to be universally unique this means that this rule is true for the Simacan platform and beyond to other platforms.
2. An entity keeps its UUID forever. If the UUID of an entity 'changes' it is considered a new entity.

These rules in combination with widespread support of UUIDs in various programming languages allow UUIDs to be unique, even over multiple organizations and platforms. Therefore, within Simacan we use UUIDs as the primary way to identify entities.

Simacan is aware that not all IT platforms use UUIDs (yet) and therefor allows parties to use custom numeric or string IDs when needed. However we strongly recommend to use UUIDs where possible.

Creating UUIDs

You can create a unique UUID in Java using:

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

And in C# using:

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:

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 your 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#

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);
};

Note: the recommended approach is to generate a random UUID whenever a new entity is created and save that UUID in the database. This makes the chance of collisions incredibly small.

Using IDs within the Simacan platform

• Simacan recommends using UUIDs as the primary means of identification.
• However it is possible to use other types of identification.
• If you want to make a switch from type of identification to another always consult Simacan. Changing without notification might result in incidents and unexpected behavior.

'Updates' on existing entities with new IDs

It happens regularly that new information comes in and entities need to be updated. It is important that entity IDs remain consistent in these updates as otherwise unexpected behavior happens. Some pitfalls we have noticed in the past:

• The same trip gets different IDs for new updates. Instead of updating the trip, a new trip is created. This affects the data quality and results in many 'phantom' trips that will never get realization data.
• The same stop gets different IDs for new updates. As a result Simacan will cancel the original stop and create a new stop. This affects data quality and results in a large amount of unnecessarily canceled stops.
• The same location gets different IDs for new updates. As a result Simacan will create new locations. This makes location management difficult and some features like last mile guidance will not work anymore.
• The same consignment gets a different ID for new updates. As a result Simacan will create a new consignment. The old consignment will continue to exist as long as it is active in any other trip. Therefore this results in data pollution.
• The same (load or unload) action gets a different ID for new updates. As a result the previous action will be canceled and the new action will replace the previous action. Note that this can affect the Track & Trace portal.

Updates on existing entities with non-unique IDs

Similar to the previous section, it can happen that an ID is reused for a different entity. This has undesirable effects:

• IDs are reused over time. The "same" trip might be driven each week. By reusing the same ID instead of creating a new trip that can be tracked the old trip will be updated and previous realization data will be overridden. To avoid this Simacan rejects updates on trips that are already finished.
• If a stop gets an existing ID it will 'steal' the stop from the existing trip. Unless the stop was already completed. In that case the update will be rejected.
• If an action gets an existing ID it will 'steal' the action from the existing stop. Unless the action was already completed. In that case the update will be rejected.
• If a new location gets an existing ID it will update the existing location. This can mess up history, influence ETA calculations, and might result in drivers being sent to the wrong location.
• If a new consignment gets an existing ID it will update the existing consignment. It also means that different consignments get treated as the same consignment. This makes the consignment view untrustworthy and confusing.

Relationships between entities

Entities do not live in a vacuum and have a relationship with each other. Sometimes it is necessary to move one entity to another entity. For example a stop is moved from one trip to another. Simacan enforces the following rules for moving entities:

• Only planned stops and actions can be moved from one trip/stop to another. So once a stop or action has realization data it cannot be moved anymore. A stop is considered not planned anymore once the start time of the stop has been registered. In other words, once the vehicle is at the location of the stop.
• Stops and actions can be moved. Once a trip update comes in that references an existing stop/action that stop/action will be removed from the original trip and added to the new trip.

Security

To ensure data is secured all the endpoints on the Simacan platform are secured. So, to access one of the endpoints you need to ensure you have valid authentication and authorization. See Auth API for any details.