Samsara-Fleet Hub Integration

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 NextBillion.ai’s Cloud Console

Setting up the Connection

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

1. Sign in to the NCC using your NextBillion.ai credentials.
2. From the NCC homepage, open the left navigation pane.
3. Select Fleet Hub, then choose Integrations under the Setup section.
4. On the Telematics Integration page, select Add New Connection.
5. In the Add New Connection dialog box, enter the following information:
   • Connection name: Enter a descriptive name for the integration.
   • Choose a service from the list: Select Samsara from the dropdown menu.
   • Select the Data Residency Region of your choice
   • API key: Enter your Samsara API key.
6. Select Save to complete the setup

Upload Address and Vehicle Data

After setting up the connection, upload your address and vehicle data to the NextBillion.ai Cloud Console (NCC) by following these steps.

Import Address Data

1. In the left navigation pane, select Addresses under the Data section.
2. On the Addresses page, select Import Data in the upper-right corner.
3. In the From Connections dropdown, select the Samsara connection you created during setup.

1. In the Import Addresses dialog box, configure the following options:
   • Fetch all: Select this checkbox to import all available addresses.
   • Created after: Optionally, specify a date and time to import only addresses created after that timestamp.
2. Select Import to begin the import process. NCC will fetch and display address data from your Samsara account.

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

Import Vehicle Data

1. In the left navigation pane, select Vehicles under the Data section.
2. On the Vehicles page, select Import Data in the upper-right corner.
3. In the From Connections dropdown, select the Samsara connection you created during setup. NCC will automatically fetch and update all vehicle data from your Samsara account.

Use Route Planner to Generate Optimized Routes

Once address and vehicle data are imported, head to Route Planner app in the left navigation pane. On the Route Planner page, follow the instructions for each page below, to generate optimized routes:

Set Preferences Tab

1. Choose your preferred configuration.
2. Go on to select / configure different preferences like - objectives, constraints, grouping rules, depots, task relations and routing configurations, time-zones etc.
3. The last option on the Set Preferences Tab relates to sharing the optimized solution to external integrations. Select the Samsara connection configured previously and click “Next”.

Add Orders Tab

1. Use Other ways to upload > Add from Addresses to fetch addresses from Samsara.

2. From the Select from Addresses page, choose to upload either Individual or Groups addresses.

3. Click ‘Upload’.

   

4. Map the Optimization attributes to match the uploaded data fields, then click ‘Next’.

Add Vehicles Tab

1. Use Other ways to upload > Add from Vehicles to fetch addresses from Samsara.

2. From the Select from Vehicles page, choose to upload either Individual or Groups addresses.

3. Click ‘Upload’.

   

4. Map the VRP attributes and click ‘Next’ to finalize the setup.

Once vehicles are uploaded, on the preview screen:

• Verify the tasks, vehicles and preferences configured.
• Click ‘Generate Route’ to execute and visualise optimized routes on the map.

Sharing Routes from Route Planner to Samsara

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

1. On the “Solution” screen, view the optimized routes in Route Planner.
2. Select the Samsara connection from the Share > Dispatch To Connection dropdown.

This action will send the routes to the Samsara dashboard, where they will be assigned accordingly.

Configure Metadata for JSON Input

When using the Input JSON method to configure order and vehicle inputs for optimization, we need to provide an additional metadata attribute for each of Orders and Vehicles to meet Samsara’s requirements of mandatory fields.

Order Metadata

Add a “metadata” attribute for each job or shipment to specify any custom data that should be attached along with its fulfillment details in the “steps” attribute of the optimized solution. Please note that the metadata content must always be specified in a “key : value” pair format, where the "key" is always a string.

Users can leverage this property to provide additional details/context when sharing information about the Order external systems.In order to relay the information for specific fields in Samsara - “name”, “address”, and “notes” - we recommend users to add these fields in metadata attribute exactly like the below sample:

Example Jobs JSON

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

Example Shipments JSON

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

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. Please note that the metadata content must always be specified in a “key : value” pair format, where the "key" is always a string.

Users can leverage this property to provide additional details/context when sharing vehicle information with integrated systems (TMS, Fleet Management, Driver dispatch etc). Following is a sample vehicle configuration using the metadata attribute:

Example Vehicles JSON

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