Vehicle store integration

The vehicle store integration enables TSPs to feed the TraX vehicle store with vehicle definitions that become searchable by the TraX mobile app.

To make it easier for TraX mobile app users to model the digital vehicle replica where sensors are planned to be commissioned, the TraX mobile app provides a search capability that can be used to retrieve vehicle definitions from the TraX vehicle store.

The vehicle store integration consists of three different flows that the TSP should implement to provide a one-way synchronization of vehicle definitions with SKF.

🚩 Application integration objectives

• Implement a flow that updates all vehicle definitions (flow 1)
• Implement a flow that updates recently changed vehicle definition (flow 2)
• Implement a flow that updates requested vehicle definitions (flow 3) NOTE: CURRENTLY NOT IN SCOPE

We recommend that you review the TraX Partner API reference to learn about the behavior of the API (endpoints, payloads, and much more). The API reference can be viewed online, or downloaded for viewing in your preferred OpenAPI renderer.

Update all vehicle definitions (flow 1)

The purpose of this flow is to perform a complete update/refresh of all vehicle definitions to the TraX vehicle store.

Vehicle definitions are uploaded to SKF using the web API. Here's an example that shows how to upload two vehicle definitions belonging to a fleet identified by the ID "1234":

Request: POST /fleets/1234/vehicles

// Request payload example
{
  "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"
      }
  ]
}

Implementation requirements & notes

• All vehicle definitions in the scope of TraX MUST be refreshed when the integration flow is started, and every 7 days.
• The endpoint POST /fleets/{fleetId}/vehicles is restricted to 7000 vehicles per request (about 1 MB of data).
• The fleetId and vehicleId attributes are immutable and hence MUST NOT change.

Update recently changed vehicle definition (flow 2)

The purpose of this flow is to ensure that vehicle definitions are reasonably up-to-date data.

Choosing a method for capturing vehicle definition changes

Determining if a vehicle's definition has changed can be accomplished in many different ways. The choice usually comes down to the integration capabilities of the TSP´s platform.

In this guide we outline two options to capture vehicle definition changes:

• Option A: Event-driven updates - Changes are captured using event-driven capabilities of the TSP's integration architecture
• Option B: Scheduled partial/delta updates - Changes are captured using database-centric techniques to capture changes

RECOMMENDED: We recommend Option A: Event-driven updates because it provides near real-time updates to the TraX vehicle store, ensuring TraX mobile app users have access to an up-to-date list of the TSP's vehicle definitions.

Implementing Option A: Event-driven updates

This approach involves defining filters (or subscribers) that capture vehicle definition change events.

Define filters based on these criteria:

• Vehicle created
• Vehicle updated**
• Vehicle deleted

Vehicle definition updates are limited to attributes: vin, vehicleName, brand & model. Changing fleetId and/or vehicleId in a vehicle's definition is not supported through the web API in TraX.

Implementing Option B: Scheduled partial/delta updates

This implementation option works by determining which vehicle definitions have changed since the last run. The practice of capturing the change in a database is commonly referred to as Change Data Capture (CDC). It's a technique that captures database inserts, updates, and deletes (along with DDL changes) and replays it in a target database.

Once the changes have been captured and represented in a database, a flow needs to process each record and propagate the change to the TraX vehicle store. The flow SHOULD be scheduled to be executed each hour.

Create or update a vehicle definition in the TraX vehicle store

Once a change has been captured, the change needs to be propagated to the TraX vehicle store. Here's an example that shows how to create or update an existing vehicle definition in the TraX vehicle store. In this example, the vehicle is identified by the fleetId "1234" and the vehicleId "740f410b":

Request: POST /fleets/1234/vehicles/740f410b

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

Delete a vehicle definition in the TraX vehicle store

And in the case the TSP's TraX implementation has determined that a vehicle definition should be deleted from the TraX vehicle store, here's an example request that would delete the same vehicle definition that was previously created or updated in the TraX vehicle store

Request: DELETE /fleets/1234/vehicles/740f410b

Update requested vehicle definitions (flow 3) NOT CURRENTLY IN SCOPE

The primary driver for this flow is to enable TraX mobile app users to view nearby vehicles on a map. Users can then select a vehicle from the map and quickly start commissioning sensors.

Most vehicle definition information remains valid over time - such as vehicle name and VIN, other information such as the geographicPosition quickly becomes outdated as soon as the vehicle starts moving.

The "Update requested vehicle definitions" flow enables SKF to request the TSP to enrich certain vehicle definitions with accurate geographic position information. <p "118"> Note that by design, the "Update all vehicle definitions" or the "Update recently changed vehicle definition" flows do not include the geographicPosition. Only when there is an actual TraX mobile app user that may have a need to know about nearby vehicles, the geographic position of a vehicle is shared with SKF.

IMPORTANT: The Request updates flow is not part of the initial launch of TraX.

Retrieving "vehicle information outdated" events

The request to update certain vehicles is communicated with the TSP through a vehicle information outdated event. The event can be retrieved in two ways:

• From a web API endpoint: GET /vehicles/events
• Or from a queue (recommended): trax.{name of tsp}.vehicle

The vehicle information outdated event can look as follows:

// Example of a vehicle information outdated event
{
  "vehicleEvents": [
    {
      "eventId": 1,
      "eventType": "Vehicle information outdated",
      "resourceType": "Vehicle",
      "eventData": {
        "selectionCriteria": {
          "fleetName": "Ken Foods Inc.",
          "fleetId": "1234",
          "vehicleName": "SPACE TRUCK 8459",
          "vin": "C25HA5R6LO5T2TE",
          "vehicleId": "740f410b-7f37-4dbc-9cc5-f7c160005dc7",
          "latitude": 57.69699,
          "longitude": 11.9865,
          "radius": 50
        },
        "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6"
      }
    }
  ]
}

Processing "vehicle information outdated" events

<p "159"> The selectionCriteria section of the vehicle information outdated event contains filtering criteria such as vehicleName, vin, or geographic location in the form of latitude and longitude. The vehicle information outdated event will contain at least one selection criterion (e.g. vin).

Below is an excerpt of the selectionCriteria section where all filtering criteria are provided:

{
  ...
  "selectionCriteria": {
    "fleetName": "Ken Foods Inc.",
    "fleetId": "1234",
    "vehicleName": "SPACE TRUCK 8459",
    "vin": "C25HA5R6LO5T2TE",
    "vehicleId": "740f410b-7f37-4dbc-9cc5-f7c160005dc7",
    "latitude": 57.69699,
    "longitude": 11.9865,
    "radius": 50
  }
 ...

And here's another example where only a few selection criteria are provided:

{
  ...
  "selectionCriteria": {
    "fleetName": "Ken Foods Inc.",
    "fleetId": "1234",
    "latitude": 57.69699,
    "longitude": 11.9865,
    "radius": 50
  }
 ...

Use the provided selection criteria to query the TSP's local vehicle database for a list of vehicle definitions.

Also notice that the fleetId and requestId attribute in the vehicle information outdated event needs to be part of the later API request to upload vehicle definitions to the TraX vehicle store. Below is an excerpt that shows where these attributes are located:

{
  "vehicleEvents": [
    {
      ...
      "eventData": {
        "selectionCriteria": {
          ...
          "fleetId": "1234",
          ...
        },
        "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6"
      }
    }
  ]
}

Update the TraX vehicle store with

The next step is to upload the previously determined vehicle definitions to SKF.

In this example, we include the fleetId "1234" and requestId "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6" as part of the URL in the request:

Request: POST /fleets/1234/vehicles/request/d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6

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

Implementation requirements & notes

• The vehicle information outdated events will expire from the queue after 120 seconds
• Rules for matching vehicle definitions in the TSP's vehicle database: (1) vehicleName should return matches at any position, and (2) vin should return matches starting from the left.
• Notice that vehicleName and vin can be partial values, hence if the TSP's vehicles are available in a database, you may want to make use of the SQL operator "LIKE". For example, the field vehicleName contains the value "TRUCK 8459", in this case, the request should retrieve all vehicles with "TRUCK 8459" in the name, such as "SPACE TRUCK 8459".
• The POST /fleets/{fleetId}/vehicles/request/{requestId} endpoint is restricted to 200 vehicles per request