generic header image

A developers introduction to the ShimId

Published on October 20, 2014 in Fleet Management by Nathan Mascitelli |  2 minute read

A Developers Introduction to the ShimId. With the goal in mind of making continuous technology improvements, adding new vehicle diagnostics is key.

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:

If you liked this post, let us know!


Geotab's blog posts are intended to provide information and encourage discussion on topics of interest to the telematics community at large. Geotab is not providing technical, professional or legal advice through these blog posts. While every effort has been made to ensure the information in this blog post is timely and accurate, errors and omissions may occur, and the information presented here may become out-of-date with the passage of time.

Get industry tips and insights

Sign up for monthly news and tips from our award-winning fleet management blog. You can unsubscribe at any time.

Republish this article for free

Other posts you might like

Two women in a business meeting sitting in front of charts and a laptop

Empowering Success: Unleashing the Domino Effect of Connected Women

Insights from Women in Fleet Leadership at Geotab Connect

February 16, 2024

Construction worker looking over at something

Routes to riches – Geotab Routing and Optimization drives operational efficiency and cost management

Geotab's Routing and Optimization software blends economic intelligence with operational strategy, reshaping fleet management for improved cost and resource efficiency.

February 15, 2024

Person standing behind a container with signal illustration

How asset tracking drives risk management and lower insurance costs

Learn how asset trackers improve risk management and reduce insurance costs in transportation and logistics, featuring expert insights from Marsh, a leader in insurance and risk advice.

February 15, 2024

multiple vehicles on the road

What is ADAS?

ADAS are in-vehicle technologies designed to enhance vehicle safety and assist the driver in better controlling the vehicle.

January 12, 2024