Vehicle Store Integration

Introduction

The purpose of the Vehicle Store integration is to enable a one-way synchronization of vehicles from the TSP to SKF.

TraX mobile app users can quickly search for vehicles in the Vehicle Store, ensuring data quality by eliminating the risks associated with manual data entry, such as incorrect VINs.

Behind the scenes, each vehicle is identified by a Vehicle ID provided by the TSP. This, combined with a TSP-provided Fleet ID, creates a robust vehicle identifier, allowing SKF to accurately identify which vehicle a sensor has been commissioned on, as described in the Sensor Configuration Integration.

The Vehicle Store acts as a "staging table," meaning that adding a vehicle makes it searchable in the TraX mobile app but does not add it to SKF's IoT platform. You have to use the TraX mobile app for that.

We highly recommend reviewing the TraX web API OpenAPI document to fully understand the API's functionality, including its endpoints, payloads, and other important details.

Objectives 🎯

Application Integration

• Establish a one-way synchronization of vehicles from the TSP platform to the SKF Vehicle Store. Include vehicles that are planned to be equipped with TraX sensors.

Adding, Updating, and Removing Vehicles

The Vehicle Store integration should support adding, updating, and removing vehicles. How these actions are triggered depends on the features available in each TSP's platform. 

Vehicle Event	API Operation
Vehicle Created	POST /fleets/{fleetId}/vehicles
Vehicle Updated	PUT /fleets/{fleetId}/vehicles/{vehicleId}
Vehicle Deleted	DEL /fleets/{fleetId}/vehicles/{vehicleId}

The table above shows how vehicle events correspond to operations in the TraX web API:

Capturing Vehicle Events

This guide outlines two methods for capturing vehicle changes, but there are additional options available.

Option A: Capturing Vehicle Events in an event-driven architecture

• Changes are detected using the event-driven capabilities of the TSP's integration architecture.
• This approach employs filters (or subscribers) to capture vehicle events.

RECOMMENDED: We recommend Option A for near real-time updates to the TraX Vehicle Store, ensuring TraX mobile app users always have an up-to-date list of the TSP’s vehicle definitions

Option B: Capturing Vehicle Events Using Database-centric Techniques

• The process of tracking changes in a database is commonly known as Change Data Capture (CDC).
• CDC captures database inserts, updates, and deletes (along with DDL changes) and replays them in a target database.
• After capturing and storing the changes in a database, each change must be propagated to the Vehicle Store. We recommend running the synchronization process hourly.

Maintaining a List of Vehicles in the Vehicle Store Using the TraX Web API

The primary function of the Vehicle Store integration is to facilitate the uploading of vehicles intended for TraX sensor installation.

Fleet- and Vehicle Identifiers

Vehicle identification is crucial in the connected TraX model as it allows SKF to notify the TSP about which vehicle a sensor was either commissioned or decommissioned.

A "linked vehicle" is identified in the same way in both SKF’s and the TSP’s platforms, using a TSP-provided vehicle ID and fleet ID. Other identification methods, such as using the vehicle’s VIN or name/description, are not reliable.

A vehicle’s “linked status” is shown by a circle to the left of the vehicle’s name in the TraX mobile app. A green circle indicates the vehicle is linked, while a white circle indicates that the vehicle is not linked.

Implementation Requirements and Notes

• The fleetId and vehicleId attributes are immutable and must not be changed. Both these identifiers are provided by the TSP.
• For more information about the technical specifications of the TraX web API, please refer to the TraX web API OpenAPI documentation.
• All vehicles in the Vehicle Store should be refreshed every three to seven days.
• The endpoint POST /fleets/{fleetId}/vehicles is limited to 7000 vehicles per request (approximately 1 MB of data).

Register a Fleet

A fleet must be added to the SKF platform before any vehicles within it can be uploaded to the Vehicle Store.

// Add a fleet

POST /fleets

{
  "fleetId": "159032dc-e809-4a84-b5eb-15b4c0159138",
  "fleetName": "Ken Trucks Inc."
}

Add a Vehicle

A new vehicle can be added to the Vehicle Store when a user flags a specific vehicle or an entire fleet for TraX deployment in the TSP's UI.

// Add a vehicle

POST /fleets/1234/vehicles

{
  "vehicles": [
    {
      "vehicleId": "740f410b-7f37-4dbc-9cc5-f7c160005dc7",
      "vin": "C25HA5R6LO5T2TE",
      "vehicleName": "SPACE TRUCK 8459",
      "brand": "Volvo",
      "model": "VHD 300 AF"
      }
  ]
}

Update a Vehicle

// Update a vehicle

PUT /fleets/1234/vehicles/740f410b

{
  "vehicle": {
    "vehicleId": "740f410b",
    "vin": "C25HA5R6LO5T2TE",
    "vehicleName": "SPACE TRUCK 8459",
    "brand": "Volvo",
    "model": "VHD 300 AF"
    }
  }

Delete a Vehicle

// Delete a vehicle

DELETE /fleets/1234/vehicles/740f410b

Add or Update Several Vehicles

It´s the same API operation for adding or updating one or several vehicles.

// Create or update multiple vehicles

POST /fleets/1234/vehicles

{
  "vehicles": [
    {
      "vehicleId": "740f410b-7f37-4dbc-9cc5-f7c160005dc7",
      "vin": "C25HA5R6LO5T2TE",
      "vehicleName": "SPACE TRUCK 8459",
      "brand": "Volvo",
      "model": "VHD 300 AF"
      },
    {
      "vehicleId": "ff2951c2-34a6-481f-92c5-c6a5f502bf55",
      "vin": "1FMZK05135GAGG488",
      "vehicleName": "Monster truck 1234",
      "brand": "Hot Wheels",
      "model": "Ford Monster Truck"
      }
  ]
}