Samsara Integration with Fleet Hub

This integration document will walk you through the steps of integrating Samsara telematics with NextBillion.ai’s Fleet Hub, accessible via NextBillion.ai’s Cloud Console.

Prerequisites

Before proceeding with the integration, ensure that you have the following prerequisites in place:

  1. Access to a Samsara Account
  2. Access to a NextBillion.ai’s Cloud Console

Setting up the Connection

To establish the connection between Samsara and NextBillion.ai, follow these steps:

  1. Log in to NextBillion.ai Cloud Console
docs-image
  1. Navigate to ‘Telematics Integration’ under the ‘Fleet Hub’ section in the left-hand menu.
docs-image
  1. Click on the ‘Add New Connection’ button. This will open the ‘Telematics Connection Editor’ window. In this window, enter a Connection Name and your NextBillion.ai API token, and then proceed to save your settings.
docs-image

You have successfully set up the connection between your Samsara account and NextBillion.ai’s Fleet Hub.

Downloading Addresses from Samsara

To download addresses from your Samsara account, follow the steps mentioned below:

  1. Log in to your Samsara account.
docs-image
  1. Navigate to the Addresses page and click on ‘Download Valid Addresses.’
docs-image
  1. A CSV file containing the addresses will be downloaded to your designated folder.

Downloading Vehicle Data from Samsara

To download vehicle data from Samsara, follow these steps:

  1. Log in to your Samsara account.

  2. Proceed to the Assets page and click on ‘Export to CSV.’

docs-image
  1. The vehicle data will be downloaded in CSV format.

Uploading Address and Vehicle Data to NCC Route Planner

To upload address and vehicle data to NCC Route Planner, adhere to the following steps:

  1. Log in to NCC and navigate to NCC Route Planner.
docs-image
  1. Upload the Address and Vehicle Data CSV files and map the fields accordingly.
docs-image docs-image

Adding Additional Data Fields after CSV Upload

To include more data fields after uploading CSV files, follow one of the following methods:

  • Pre-process your CSV file by adding the desired data directly to the file itself before uploading it. Then, map the new fields during import.

  • Alternatively, upload the file as is and add new data fields via the input editor. Click on ‘Add default attribute’ and map the field accordingly.

docs-image

Sharing Routes from Route Planner to Samsara

To share routes from Route Planner to Samsara, proceed as follows:

  1. View the optimized routes in Route Planner.
  2. Select the connection from the ‘Share’ section in Route Planner.
docs-image
  1. This action will send the routes to the Samsara dashboard, where they will be assigned accordingly.
docs-image
docs-image

How to relay Route details to Samsara while planning routes with Nextbillion.ai ?

  1. Use Vehicle, Job & Shipment metadata to relay route details to Samsara
  2. Check following sections to learn about using metadata specifically with Samsara

Vehicle Metadata

Add a “metadata” attribute for each vehicle to specify any custom vehicle data that should be attached along in the “routes” attribute of the optimized solution. Users can leverage this property to provide additional details/context when sharing vehicle information with integrated systems (TMS, Fleet Management, Driver dispatch etc).

Please note that the metadata content must always be specified in a “key : value” pair format, where the "key" is always a string.

Following is a sample vehicle configuration using the metadata attribute:

Example:

1{
2 "vehicles": [...]",
3}

Job Metadata

Add a “metadata” attribute for each job to specify any custom data that should be attached along with its fulfillment details in the “steps” attribute of the optimized solution. Users can leverage this property to provide additional details/context when sharing information about the job with integrated systems (TMS, Fleet Management, Driver dispatch etc). Please note that the metadata content must always be specified in a “key : value” pair format, where the "key" is always a string.

In order to relay the information for specific fields in Samsara - Job name, address, and notes - we recommend users to add these fields in job’s metadata attribute exactly like the below sample:

1{
2 "jobs": '[..]'
3}

Shipment Metadata

Add “metadata” attribute at each shipment level to specify any custom data that should be attached along with shipment fulfillment details in the “steps” attribute of the optimized solution. Users can leverage this property to provide additional details/context when sharing information about the shipment with integrated systems (TMS, Fleet Management, Driver dispatch etc). Please note that the metadata content must always be specified in a “key : value” pair format, where the "key" is always a string.

In order to relay the information for specific fields in Samsara - shipment name, address, and notes - we recommend users to add these fields in job’s metadata attribute exactly like the below sample:

1{
2 "shipments": '[..]'
3}

Following is a complete request with metadata and description fields configured such that they will auto populate the Samsara fields.

1{
2 "description": "Jobs for customers",
3 "locations": "{...}",
4 "jobs": "[...]",
5 "shipments": "[...]",
6}