A developers introduction to the ShimId

With the goal in mind of making continuous technology improvements, adding new vehicle diagnostics is key. From the software perspective, this means adding new diagnostics to allow users to interact with the ever-increasing amount of engine data that Geotab’s GO device provides.

In the MyGeotab API, an object called a “Diagnostic” is used to represent a type of reading that is retrieved from the engine. Different Diagnostics have different identifiers (Ids), which indicate what each Diagnostic represents.

For example, there is an Id called DiagnosticOdometerId and any Diagnostic with this Id would represent an odometer reading. Geotab provides hundreds of different diagnostics to their customers through the API. The Ids for these are found in the KnownId class, which acts as a central point where all system Ids can be accessed.

Flaws with the System

While this system works very well, it has been found to have one flaw. Let’s say there is a client using version 1 of the MyGeotab Software Development Kit (SDK) to pull all of the Diagnostics from a server that is also running version 1. Everything is working fine until the server is updated to version 2, and this update has a new Diagnostic and a new Id added. The client, still on version 1, tries to get this new Diagnostic. The Diagnostic will have an Id that the client does not know about, causing the client’s system to crash when trying to convert the JSON representation of the Diagnostic object from JSON to C# (Note: this problem only exists when using the C# API).

A real world analogy of this is caller id on telephones. If a phone gets a call from an unknown number it doesn’t fail, it simply displays ‘Unknown Number’. Geotab feels its SDK should work the same way.

In order to get the new Diagnostic, the client must update to version 2 of the SDK. However, Geotab felt that asking their clients to update their applications with a new SDK every time servers were updated was too much to ask- this led to the introduction of a new object called a ShimId.

The Shimmy

A ShimId is a subclass of the Id object and allows clients to handle system Ids that are not present in the KnownId class. If we refer back to the previous example, rather than failing when a client using version 1 of the SDK gets a Diagnostic from the server that only exists in version 2, the client will create a ShimId object. A ShimId is basically a string representation of the unknown Id; it has no key or GUID and it very closely resembles how Ids are handled in the JavaScript API.

The ShimId is best explained using an example. In this example all of the status data over the past hour for one device will be retrieved. All of the Diagnostics will then be collected for that data and one can then output these items to the console.

After gathering all of the status data, a dictionary of unique Diagnostics is created (no duplicates because it would be inefficient). Looking at this dictionary, you can see that one of the Ids is a ShimId. This Id–DiagnosticWindshieldWipersOnId–must exist on the server, but not on the client.

The neat thing about ShimIds is that we can send ShimIds back to the server and it will know how to handle them. Just because we do not know about this Id, does not mean that we can’t ask the server to give us the associated Diagnostic.

As you can see, we were able to successfully handle a Diagnostic that we knew nothing about.  ShimIds allow you to maintain your code without the need for adjustment should Geotab make any changes to the SDK. ShimIds don’t just apply to Diagnostics, but rather they can be used with any entity available in the SDK.

In order to be able to use ShimIds, all you need to do is download the latest MyGeotab SDK and add it to your project. You should not have to change any code, but it is highly recommended that you update to the latest SDK in order to see the benefit of ShimIds. Once you do, your application will be able to handle any future additions Geotab makes to the SDK.

For more information, please leave your questions or comments in the box below: