Fall '24 Setup & Configuration

  • Published on Jan 15, 2025
  • 3 minute(s) read
Prev Next

Overview

The integration with the Samsara API provides direct integration to drivers and the assets they are driving through an ELD device and a phone application. Revenova’s Fleet Management Module requires the use of Samsara ELD tracking.

Samsara provides “push” status updates to the TMS via a sites-based web service. Inbound packets from Samsara are stored in the Queued Transaction table and processed by the QueuedTransactionJob.

Setup

Enter Credentials

Enable the Samsara integration by completing the following steps.

  1. Navigate to TMS Admin.

  2. Select Credentials.

  3. Select the Global Services tab.

  4. Find Samsara in the list and open the card.

  5. Check the Enabled box.

  6. Enter the User ID and Password 1 into the text fields.

  7. Set the Service URL to: https://api.samsara.com.

  8. Set the Test Service URL to: https://api.samsara.com.

  9. Click the Save button when finished.

User ID

Password 1

Password 2

Customer Number

"Revenova"

Required API Key

Remote Site Settings

Upgrading from previous versions of the TMS may have outdated information. Check that the Remote Site Settings for the Samsara integration URL are up to date.

  1. Click the Setup gear icon in the top right corner.

  2. From the drop-down, click Setup.

  3. In the Quick Find Toolbar type Remote Site Settings and click the link.

  4. From the list of remote sites find Samsara and click the Edit link.

  5.  Update the Remote Site URL to: https://api.samsara.com.

Partner Community Setup

The Samsara integration requires a webhook to send information into the TMS. Create an API Site to accept inbound traffic.

  1. Create a Salesforce Site for API Guest User Access.

  2. Set the public access for the Site.

  3. Activate and Publish the Site.

  4. Enter the API URL into the field for Inbound API Community URL under TMS Admin, in the Configuration section. 

  5. Add the following extension to the end of the URL to match the example below: /services/apexrest/rtms/tmslistener?org=[18-character org id]&source=Samsara&pwd=[credentials code field]

  6. Contact Samsara support and provided them this "Post-back" URL to point at your listener.

{API Community URL}/services/apexrest/rtms/tmslistener?org=[18-character org id]&source=Samsara&pwd=[credentials code field]

Example: https://revenova.my.site.com/api/services/apexrest/rtms/tmslistener?org=00D180000008oA9EAI&source=Samsara&pwd=4wGFDgnT950Ovg1

The Samsara integration supports multiple stops for the same Account location.

The bi-directional integration is accomplished with three TMS processes.

  1. The Fleet Management Job invokes API calls on the Samsara API.

  2. Samsara pushes event packets to the application via the TMS Listener and Samsara Event Processor.

  3. The Load LWC widget can send text messages to the driver via the Samsara phone application.

If the Customer is already using Samsara, it is likely that they have many Locations that can be imported into Revenova and create Account records using the Fleet Management Job.

See the Fleet Management Job for more information.

Samsara Portal Setup & Configuration

Required API Key/Token: API Tokens for secure access to the API can be viewed and created on the API Tokens Settings page. Below are instructions on how to set up an API token:

  1. Log in to the Samsara Dashboard and navigate to Settings → API Tokens.

  2. Click + Add an API Token to create a new token.

    1. Enter Revenova Integration as the Name for the API token.

    2. Select a Permission Scope for the API token. Give Full Admin access for this API Token. For Full Admin access, select the Global Read and the Global Write scopes under the Global Dropdown.

    3. Enter a Name and Permission Scope.

    4. Click Save.

Samsara Management Application Setup

  1. Install Samsara ELD in all Fleet Asset tractors/trucks.

  2. Install Samsara Driver Phone Application on all driver smart phones.

  3. From the Samsara Management Application:

    1. Add all driver documents using the names defined in the Customer Invoice Documents table.

      1. The Customer Invoice Document table Synonyms field captures documents from drivers via the Samsara phone application. Existing users of Samsara may use document names that are different from Revenova definitions. Populate this field if this is the case.

    2. Add the following required field to all driver document types:

      1. Is Proof of Delivery (Yes or No)

    3. Configure web hook for push alerts.

    4. Configure your push alert types and thresholds.

    5. From Settings → Fleet → Driver App review setup parameters.

    6. From Settings → Fleet → Dispatch review setup parameters.

Troubleshooting

If the system administrator receives a Fleet Management email with a list of errors, '1) start() method error: invalid token---(rtms)' This means there are invalid Samsara credentials. The job should be stopped until valid credentials are entered.

1) start() method error: invalid token- - -(rtms)

Issue

When running the Fleet Management Job, system admin receives an email containing the following.

1) start() method error: invalid token---(rtms)

(2) start() method error: invalid token---(rtms)

(3) start() method error: invalid token---(rtms)

(4) start() method error: invalid token---(rtms)

(5) start() method error: invalid token---(rtms)

(6) start() method error: invalid token---(rtms)

(7) start() method error: Unexpected character ('r' (code 114)): expected a valid value (number, String, array, object, 'true', 'false' or 'null') at input location [1,2]---(System Code)

Resolution

The credentials for the Samsara integration are invalid. Stop the Fleet Management job and enter valid credentials. Start the Fleet Management Job when the credentials are updated.