# 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](https://console.nextbillion.ai/).

## 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.  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.
    -   **API key**: Enter your Samsara API key.
6.  Select **Save** to complete the setup.

![documentation image](https://static.nextbillion.io/docs-next/integrations/samsara/fleet-integration-new-01.webp) 

## 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.

### Upload 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 connection you created during setup.

![documentation image](https://static.nextbillion.io/docs-next/integrations/samsara/fleet-integration-new-02.webp)

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.

![documentation image](https://static.nextbillion.io/docs-next/integrations/samsara/fleet-integration-new-03.webp)

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 connection you created during setup. NCC will automatically fetch and update all vehicle data from your Samsara account.

![documentation image](https://static.nextbillion.io/docs-next/integrations/samsara/fleet-integration-new-04.webp)

Use Route Planner to Generate Optimized Routes

Once address and vehicle data are imported, follow the steps below to generate optimized routes: Open the **‘Route Planner’** app from the left toolbar. Click **‘Start’** on the input screen.

![documentation image](https://static.nextbillion.io/docs-next/integrations/samsara/fleet-integration-new-05.webp)

#### Configure Tab

-   Select the **API type**: Fast or Flexible.
-   Choose your **Samsara connection** from the ‘Select Connection’ dropdown.
-   Click **‘Next’** to proceed.

![documentation image](https://static.nextbillion.io/docs-next/integrations/samsara/fleet-integration-new-06.webp)

#### Jobs Tab

-   Use ‘Select Addresses’ to fetch addresses from Samsara.
-   Choose the addresses you want to include and click ‘Upload’.

![documentation image](https://static.nextbillion.io/docs-next/integrations/samsara/fleet-integration-new-07.webp)

-   Map the VRP attributes to match the uploaded data fields, then click ‘Next’.

![documentation image](https://static.nextbillion.io/docs-next/integrations/samsara/fleet-integration-new-08.webp)

#### Shipments and Depots Tab

Upload shipments and depot data as required or click ‘Skip’ if not needed.

#### Vehicles Tab

-   Use ‘Select Vehicles’ to fetch vehicle data from Motive.

![documentation image](https://static.nextbillion.io/docs-next/integrations/samsara/fleet-integration-new-09.webp)

-   Select the vehicles you want to use and click ‘Upload’.

![documentation image](https://static.nextbillion.io/docs-next/integrations/samsara/fleet-integration-new-010.webp)

-   Map the VRP attributes and click ‘Next’.

![documentation image](https://static.nextbillion.io/docs-next/integrations/samsara/fleet-integration-new-011.webp)

#### Options Tab

Configure additional parameters such as:

-   **Constraints**: Max vehicle overtime, max lateness, max waiting time.
-   **Objective**: Minimize travel cost (distance/duration) or set a custom optimization goal.
-   **Routing Mode**: Select **Car** or **Truck** and specify a **Traffic Timestamp**.

Click **‘Finish Import’** to finalize the setup.

#### Generate Optimized Routes

-   Click **‘Compile’** to visualize routes on the map.
-   Click **‘Run’** to execute the route planner and generate optimized routes.

![documentation image](https://static.nextbillion.io/docs-next/integrations/samsara/fleet-integration-new-012.webp)  

## 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.

![documentation image](https://static.nextbillion.io/docs-next/integrations/samsara/fleet-integration-12.webp)

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

![documentation image](https://static.nextbillion.io/docs-next/integrations/samsara/fleet-integration-13.webp)  

![documentation image](https://static.nextbillion.io/docs-next/integrations/samsara/fleet-integration-14.webp)

### 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:

```json
{
    "vehicles": [
        {
            "id": 281474986740071,
            "start_index": 8,
            "end_index": 8,
            "break": {
                "id": 13,
                "time_windows": [
                    [
                        1715778715,
                        1715793115
                    ]
                ],
                "service": 1800
            },
            "costs": {
                "fixed": 300
            },
            "metadata": {
                "id": "New Trip",
                "name": "Tim",
                "address": "1234, Elm Street, Los Angeles, CA 90001"
            },
            "capacity": [
                50
            ],
            "time_window": [
                1715778715,
                1715793115
            ],
            "skills": [
                2,
                3
            ],
            "max_tasks": 10
        },
    ]
}
```

### 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:

```json
{
    "jobs": [
        {
            "id": "Job 1",
            "description": "Delivery Job in Hyderabad",
            "location_index": 0,
            "service": 300,
            "delivery": [
                10
            ],
            "priority": 2,
            "time_windows": [
                [
                    1715778715,
                    1715793115
                ]
            ],
            "metadata": {
                "name": "John",
                "address": "Mebaz Showroom, Engineers Enclave, Chanda Nagar, Hyderabad, Telangana 500050",
                "notes": "9177940839"
            }
        }
    ]
}
```

### 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:

```json
{
    "shipments": [
        {
            "pickup": {
                "id": 1,
                "description": "Pickup 1",
                "service": 300,
                "location_index": 6,
                "time_windows": [
                    [
                        1715778715,
                        1715793115
                    ]
                ],
                "metadata": {
                    "name": "John",
                    "address": "Jubilee Hills, Hyderabad",
                    "notes": "Find package near porch"
                }
            },
            "delivery": {
                "id": 1,
                "description": "Delivery 1",
                "service": 300,
                "location_index": 7,
                "time_windows": [
                    [
                        1715778715,
                        1715793115
                    ]
                ],
                "metadata": {
                    "name": "Jake",
                    "address": "Hi-Tech City, Hyderabad",
                    "notes": "Place the package near porch"
                }
            },
            "amount": [
                5
            ],
            "skills": [
                2
            ],
            "priority": 1
        }
    ]
}
```

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

```json
{
    "description": "Jobs for customers",
    "locations": {
        "id": 101055,
        "location": [
            "34.00046454950802, -118.27990000000001",
            "34.00756006202506, -118.25826781725674",
            "34.027360024681855, -118.24508927492768",
            "34.077351043796064, -118.21772490191087",
            "34.13990414253301, -118.21671075336727",
            "34.0817421499068, -118.17811073259737",
            "34.028248870536046, -118.32137856689087",
            "34.10960428503378, -118.19555364793968",
            "34.025795595331985, -118.35457854609199",
            "34.026351134721196, -118.20465708842026"
        ]
    },
    "jobs": [
        {
            "id": 10,
            "description": "Pickup Job 10",
            "location_index": 0,
            "service": 600,
            "pickup": [
                20
            ],
            "time_windows": [
                [
                    1715062584,
                    1715123784
                ]
            ],
            "metadata": {
                "name": "John",
                "address": "1234, Elm Street, Los Angeles, CA 90001",
                "notes": "Sample notes",
            }
        },
        {
            "id": 1,
            "description": "Pickup Job 1""location_index": 1,
            "service": 600,
            "pickup": [
                20
            ],
            "time_windows": [
                [
                    1715062584,
                    1715123784
                ]
            ],
            "metadata": {
                "name": "Jake",
                "address": "5678, Maple Avenue, Los Angeles, CA 90011",
                "notes": "Sample notes"
            }
        },
        {
            "id": 2,
            "description": "Pickup Job 2""location_index": 2,
            "service": 600,
            "pickup": [
                20
            ],
            "time_windows": [
                [
                    1715062584,
                    1715123784
                ]
            ],
            "metadata": {
                "name": "Tim",
                "address": "9101, Oak Drive, Los Angeles, CA 90021",
                "notes": "Sample notes"
            }
        },
        {
            "id": 3,
            "description": "Pickup Job 3""location_index": 3,
            "service": 600,
            "pickup": [
                20
            ],
            "time_windows": [
                [
                    1715062584,
                    1715123784
                ]
            ],
            "metadata": {
                "name": "David",
                "address": "2345, Pine Street, Los Angeles, CA 90031",
                "notes": "Sample notes"
            }
        },
        {
            "id": 4,
            "description": "Pickup Job 4""location_index": 4,
            "service": 600,
            "pickup": [
                20
            ],
            "time_windows": [
                [
                    1715062584,
                    1715123784
                ]
            ],
            "metadata": {
                "name": "Henry",
                "address": "6789, Birch Road, Los Angeles, CA 90041",
                "notes": "Sample notes"
            }
        },
        {
            "id": 5,
            "description": "Pickup Job 5""location_index": 5,
            "service": 600,
            "pickup": [
                10
            ],
            "time_windows": [
                [
                    1715062584,
                    1715123784
                ]
            ],
            "metadata": {
                "name": "Joe",
                "address": "1357, Cypress Street, Los Angeles, CA 90032",
                "notes": "Sample notes"
            }
        },
        {
            "id": 6,
            "description": "Pickup Job 6""location_index": 6,
            "service": 600,
            "pickup": [
                10
            ],
            "time_windows": [
                [
                    1715062584,
                    1715123784
                ]
            ],
            "metadata": {
                "name": "Eric",
                "address": "2468, Willow Avenue, Los Angeles, CA 90018",
                "notes": "Sample notes"
            }
        },
        {
            "id": 7,
            "description": "Pickup Job 7""location_index": 7,
            "service": 600,
            "pickup": [
                10
            ],
            "time_windows": [
                [
                    1715062584,
                    1715123784
                ]
            ],
            "metadata": {
                "name": "Jason",
                "address": "3579, Palm Boulevard, Los Angeles, CA 90042",
                "notes": "Sample notes"
            }
        },
        {
            "id": 8,
            "description": "Pickup Job 8""location_index": 8,
            "service": 600,
            "pickup": [
                10
            ],
            "time_windows": [
                [
                    1715062584,
                    1715123784
                ]
            ],
            "metadata": {
                "name": "Tom",
                "address": "4680, Cedar Lane, Los Angeles, CA 90016",
                "notes": "Sample notes"
            }
        },
        {
            "id": 9,
            "description": "Pickup Job 9""location_index": 9,
            "service": 600,
            "pickup": [
                10
            ],
            "time_windows": [
                [
                    1715062584,
                    1715123784
                ]
            ],
            "metadata": {
                "name": "Alex",
                "address": "5791, Magnolia Drive, Los Angeles, CA 90023",
                "notes": "Sample notes"
            }
        }
    ],
    "vehicles": [
        {
            "id": 281474986740071,
            "start_index": 0,
            "end_index": 0,
            "capacity": [
                100
            ],
            "time_window": [
                1715062584,
                1715123784
            ]
        }
    ],
    "shipments": [
        {
            "pickup": {
                "id": 101,
                "location_index": 7,
                "time_windows": [
                    [
                        1715062584,
                        1715123784
                    ]
                ],
                "metadata": {
                    "name": "Stan",
                    "address": "3579, Palm Boulevard, Los Angeles, CA 90042"
                }
            },
            "delivery": {
                "id": 1011,
                "location_index": 8,
                "time_windows": [
                    [
                        1715062584,
                        1715123784
                    ]
                ],
                "metadata": {
                    "name": "Ron",
                    "address": "4680, Cedar Lane, Los Angeles, CA 90016"
                }
            },
            "amount": [
                5
            ]
        }
    ]
}
```