SIGN INSIGN UP

Back-end notifications

We describe a way how to set up an integration to move telematics data to your server

Suggest Edits

Introduction

:one: Before you start exploring the Notification service, please make sure you are familiar with High-level architecture concept, especially with the part about the multi-instance platform as an instance is a ground-level unit for Notification services. That means rules and settings will be applied to the instance level and will cover all users are located in this instance.

It gives full flexibility to your product. In particular, you can split users into different groups and apply it is own rules for export including destination even if it is a user from a single mobile app.

:two: Make sure you are familiar with Data management options and available datasets

Setting up

  • Notification services for back-end integration :point-right: Setting up
    This option is required if you want to grab data from Damoov platform to store and work with data on your own server. Available data management options are described here. At this moment we support the following notification services:

Setting up

Each dataset available via the data export service has its own notification. The full list of available types of data is available Here

TRIPS:

  • IncomingTrackRemoved (the track was deemed invalid or excluded)
  • IncomingTrackReceived (the track was valid and has been stored as Raw Trips Data) (Recommended)
  • TrackEnrichmentFinished (a track has been converted from raw to processed) (Recommended)

CRASH:

  • DataBufferReceived (a crash buffer was received)
  • CrashDataSetCompleted (data about the crash and the crash buffer have been received)
  • Crash data - AccidentEventFiltered (recommended)

High-level scheme for crash data

3086

Notification samples

Each notification contains the necessary references, like UserID and TrackID, and URL for JSON file. The JSON structure is shown below for all three notification types.

{
  "Event": "IncomingTrackRemoved",
  "Sender": "Data Motion",
  "UserId": "e5f2d616-896d-4610-9bef-9ff823af1275",
  "Object": {
    "Id": "9347f5eb-7aca-48c3-b698-f2c7b35add29",
    "Type": "IncomingTrackSummary",
    "Url": "https://mobilesdk.telematicssdk.com/mobilesdk/incoming/incoming/tracks/removed/9347f5eb-7aca-48c3-b698-f2c7b35add29/v1/"
  },
  "Timestamp": "2020-07-20T14:44:54.9074056Z",
  "Details": {
    "TrackStartDate": "2020-04-29T09:20:48.0000000-06:00",
    "TrackFinishDate": "2020-04-29T09:57:02.0000000-06:00",
    "Reason": "Insufficient Track length"
  }
}

{
  "Event": "IncomingTrackReceived",
  "Sender": "Data Motion",
  "UserId": "e5f2d616-896d-4610-9bef-9ff823af1275",
  "Object": {
    "Id": "9347f5eb-7aca-48c3-b698-f2c7b35add29",
    "Type": "IncomingTrack",
    "Url": "https://mobilesdk.telematicssdk.com/mobilesdk/incoming/incoming/tracks/received/9347f5eb-7aca-48c3-b698-f2c7b35add29/v1/"
  },
  "Timestamp": "2020-07-20T14:44:54.9074056Z",
  "Details": {
    "TrackStartDate": "2020-04-29T09:20:48.0000000-06:00",
    "TrackFinishDate": "2020-04-29T09:57:02.0000000-06:00"
  }
}

{
  "Event": "TrackEnrichmentFinished",
  "Sender": "Data Motion",
  "UserId": "e5f2d616-896d-4610-9bef-9ff823af1275",
  "Object": {
    "Id": "9347f5eb-7aca-48c3-b698-f2c7b35add29",
    "Type": "RichTrack",
    "Url": "https://mobilesdk.telematicssdk.com/mobilesdk/stage/track/get_track/v1?trackToken=9347f5eb-7aca-48c3-b698-f2c7b35add29"
  },
  "Timestamp": "2020-07-20T14:44:54.9074056Z",
  "Details": {
    "ObjectReplaced": true,
    "TracksRemoved": [
      {
        "Id": "3337f5eb-7aca-48c3-b698-f2c7b35add29",
        "Type": "RichTrack"
      },
      {
        "Id": "4447f5eb-7aca-48c3-b698-f2c7b35add29",
        "Type": "RichTrack"
      }
    ]
  }
}

{
  "Event": "AccidentEventReceived",
  "Sender": "Data Motion",
  "UserId": "e5f2d616-896d-4610-9bef-9ff823af1275",
  "ClientId": "User 1234",
  "Object": {
    "Id": "9347f5eb-7aca-48c3-b698-f2c7b35add29",
    "Type": "Accident",
    "Url": "https://api.telematicssdk.com/api/drivingevents/get/v1/Accidents/received/9347f5eb-7aca-48c3-b698-f2c7b35add29"
  },
  "Timestamp": "2021-07-20T14:44:54.9074056Z",
  "Details": {
    "DateReceived": "2021-07-20T14:42:54.8884056Z"
  }
}

{
  "Event": "AccidentEventExtraReceived",
  "Sender": "Data Motion",
  "UserId": "e5f2d616-896d-4610-9bef-9ff823af1275",
  "ClientId": "User 1234",
  "Object": {
    "Id": "9347f5eb-7aca-48c3-b698-f2c7b35add29",
    "Type": "AccidentExtra",
    "Url": "https://api.telematicssdk.com/api/drivingevents/get/v1/Accidents/extras/received/9347f5eb-7aca-48c3-b698-f2c7b35add29"
  },
  "Timestamp": "2021-07-20T14:44:54.9074056Z",
  "Details": {
    "DateReceived": "2021-07-20T14:42:54.8884056Z"
  }
}

{
  "Event": "AccidentEventCompletePackageReceived",
  "Sender": "Data Motion",
  "UserId": "e5f2d616-896d-4610-9bef-9ff823af1275",
  "ClientId": "User 1234",
  "Object": {
    "Id": "9347f5eb-7aca-48c3-b698-f2c7b35add29",
    "Type": "Accident",
    "Url": "https://api.telematicssdk.com/api/drivingevents/get/v1/Accidents/received/9347f5eb-7aca-48c3-b698-f2c7b35add29"
  },
  "Timestamp": "2021-07-20T14:44:54.9074056Z",
  "Details": {
    "PackageDateReceived": "2021-07-20T14:42:54.8884056Z",
    "AccidentPassedFilters":  true
  }
}

{
  "Event": "AccidentEventFiltered",
  "Sender": "Data Motion",
  "UserId": "e5f2d616-896d-4610-9bef-9ff823af1275",
  "ClientId": "User 1234",
  "Object": {
    "Id": "9347f5eb-7aca-48c3-b698-f2c7b35add29",
    "Type": "Accident",
    "Url": "https://api.telematicssdk.com/api/drivingevents/get/v1/Accidents/received/9347f5eb-7aca-48c3-b698-f2c7b35add29"
  },
  "Timestamp": "2021-07-20T14:44:54.9074056Z",
  "Details": {
    "DateFiltered": "2021-07-20T14:42:54.8884056Z"
  }
}

Data samples

For your convenience, we've attached the data from a sample trip (recorded in March 2021 outside Cambridge, UK)

  • Raw Telematics data (notification IncomingTrackReceived) Download JSON file, 1.2 MB
    note that an IncomingTrackRemoved notification technically also links to an object similar to this one, but it will contain little or no useful information, but may be used for troubleshooting if you get many invalid tracks.
  • Processed Trip Data (notification TrackEnrichementFinished) Download JSON file, 341 kB

Data Format Reference

:point-right: Raw telematics data
:point-right: Processed telematics data
:point-right: Crash data

Data processing workflow for vehicle data

Item 5 in the schematic at the top

Note that this is an advanced and rare use case. For most driver behavior and fleet management use cases, you will not need to use this.

Vehicle data collection is an advanced feature that is available as an add-on, and it works as follows: The SDK connects through Bluetooth to a so-called OBD (On-Board Diagnostics) device that talks directly to the car's onboard computer to get data like engine failure codes, maintenance status, etc. One example would be to generate a notification when the "Check Engine" light is on.
This feature requires additional hardware :point-right: Bluetooth OBD and communication via Bluetooth, and requires specific knowledge of the make and model of the car. It is most commonly used by fleet apps that actively manage the vehicles and their maintenance.
:point-right: In-vehicle data

In general, vehicle data is handled in a similar fashion to GPS and Sensor data; data is filtered and enriched, and notifications are sent when a new dataset is available.

Accessing these datasets

Now that we've discussed the main categories of data and how they are processed, let's see how you can access that data. This consists in principle of two steps:
Option API:

  • Get a notification that a new dataset has been processed
  • Access the API to download the data referenced in the notification
    Option Third-party storage
  • Data gets copied by us to your preferred storage provider
  • Get a notification that a new dataset has been copied

Notifications

When a dataset moves from one stage to the next on the Damoov platform, it creates an event. You can subscribe to those events to then access the relevant data

📘

Note

Notification message doesn't contain any track’s data, such as events or waypoints. To get these details, you have to query the track’s data using the Web API service, using credentials received from SNS Message.

We support several well-known notification services, including Amazon and Azure. Each notification contains URLs, identifiers, and credentials for the respective dataset.

🚧

Important

Your back-end or application had to be prepared to receive several notifications related to a single trip. It means the previous version of the track has been updated, and you need to retrieve an updated version from our API again.

An Example where this happens would be that the track was merged with another trip segment. the updated trip will have new trip details (time, distance, etc)

Setting up notifications through Amazon SNS

to set up Amazon SNS, please go to Datahub -> Management -> Platform integration
:point-right: More about Amazon S3
:point-right: How to register AWS SNS

The following AWS information is required to complete the setup:

  • AccessKey
  • Secret
  • AWS Region
  • TopicArn of the SNS queue

Setting up notifications through Azure Service Bus

to set up Amazon SNS, please go to Datahub -> Management -> Platform integration
:point-right: More about Azure service bus

The following Azure information has to be entered to complete the setup:

  • Endpoint=sb://site.servicebus.windows.net/;
  • SharedAccessKeyName=SampleAccessPolicy;
  • SharedAccessKey=s4-0/Lkj4gsmFfro1/s08+E/0DtjtGG7y5q1Pxm4G2Q=

Setting up notifications through Azure Event grid

:point-right: More about Azure event grid

The following Azure information has to be entered to complete the setup:

Copy data to third-party storage

As discussed above, the primary way to access data is to subscribe to notifications and then access the data through our API. Full list of reports

Yet another option is that we periodically copy data to a third-party storage provider of your choice (for example, Amazon S3 bucke), and notify you when new data is available.

When does third-party storage make sense?

Offline Reporting should be used when you are planning to do an elaborate analysis of aggregate data yourself. To avoid excessive repetitive API calls, we offer a download of the entire database to your S3 Bucket. From there, you can either directly read it or further process it into your own data stores.

Notifications about third-party storage updates

to set up Amazon SNS, please go to Datahub -> Management -> Platform integration
:point-right: Full list of reports
:point-right: More about S3

The following AWS information has to be entered to complete the setup:

  • S3 bucket arn:
  • S3 bucket region:
  • access key id:
  • secret access key:
  • Folder:

Updated 9 months ago