Mini TMS - Samsara Integration Example

This repository demonstrates how to integrate Samsara's Connected Operations Platform with a Transportation Management System (TMS). It showcases key integration patterns and best practices for building a modern TMS that leverages Samsara's real-time location tracking, driver safety features, and form management capabilities.

Key Features

• Real-time Location Tracking: Live tracking of vehicles and drivers using Samsara's live sharing URLs
• Driver Safety: Integration with Samsara's driver safety features and alerts
• Form Management: Dynamic form templates that sync with Samsara's form system
• Webhook Integration: Real-time event processing from Samsara's webhook system
• OAuth Authentication: Secure authentication with Samsara's OAuth system

Prerequisites

• Ruby 3.2.0 or higher
• PostgreSQL 14 or higher
• Redis (for background jobs)
• Samsara Marketplace app OAuth credentials (Client ID and Secret)

Getting Started

1. Clone the repository:

   git clone https://github.com/samsarahq/tms-sample.git
   cd tms-sample

2. Install dependencies:

   bundle install

3. Set up the database:

   bin/rails db:create db:migrate

4. Configure environment variables:

rails credentials:edit

Update these credentials

secret_key_base:

samsara:
  client_id:
  client_secret:

confluent:
  bootstrap_servers: ""
  key:
  secret:

5. Start the development server:

   bin/dev

The application will be available at http://localhost:3000.

Key Integration Points

1. OAuth Authentication

• Auth Controller: Handles Samsara OAuth flow
• Routes: OAuth callback endpoints
• User Model: Stores Samsara access tokens

2. Real-time Location Tracking

• Stop Model: Stores Samsara live sharing URLs
• Stop Show View: Displays live tracking iframe
• Location Fetching: Background job for location updates

3. Form Management

• Form Template Model: Syncs with Samsara forms
• Form Templates Controller: CRUD operations
• Form Submissions: Stores driver form responses

4. Webhook Integration

• Webhooks Controller: Processes Samsara events
• Kafka Messages: Stores webhook events
• Event Processing: Handles different event types

Development Workflow

1. Authentication:

   • Visit /auth/samsara to start OAuth flow
   • Complete Samsara authentication
   • Access token is stored in the user record

2. Form Templates:

   • Create form templates at /form_templates
   • Templates sync with Samsara's form system
   • Assign templates to stops for driver completion

3. Live Tracking:

   • View live tracking at /routes/:id/stops/:id
   • Real-time updates via Samsara's live sharing URLs
   • Background job fetches location updates

4. Webhook Events:

   • View webhook events at /webhooks
   • Monitor Kafka messages at /kafka_messages
   • Events are processed asynchronously

Testing

Run the test suite:

bin/rails test

Contributing

This repository is a snapshot sample and is not accepting contributions. It is purely for reference while building your integration.

Resources

• Samsara API Documentation
• Samsara OAuth Guide
• Samsara Webhooks
• Samsara Forms