Content

Telematics Integrations

Use this guide to connect Samurai CMMS to your telematics providers, keep asset locations and meter readings in sync, and review sync history and asset matching.

Who should use this guide? Administrators or fleet/maintenance staff responsible for maintaining telematics connections and reviewing synced asset data.

Before you start

• You need access to Settings > API Integrations in Samurai CMMS (requires the integrations:update permission).
• You need API credentials from your telematics provider. The credentials required depend on the provider — see the table in step 1.
• Samurai CMMS matches telematics assets to your Samurai assets automatically by serial number, equipment number, or asset number. Keep those fields accurate on your Samurai asset records to improve matching.

Supported providers

1. Configure a telematics integration

1. In Samurai CMMS, open Settings > API Integrations.
2. Find the card for your provider under Available (or Installed if already configured).
3. Select + Add (or Configure on an existing connection).
4. Enter a Company Name to identify this connection — you can add more than one connection per provider, for example one per subsidiary or business unit.
5. Enter the credentials required for your provider:
   • CAT VisionLink: Client ID, Client Secret, Token URL, Scope, API Base URL.
   • Volvo CareTrack: Client ID, Client Secret, Token URL, Scope, API Base URL, plus Gateway Client ID and Gateway Client Secret.
   • Bell Fleet@matic: Client Secret, Token URL, API Base URL, Username, Password.
   • Telematics Guru: Organisation ID, Instance (e.g. api-apac04), API Key.
   • Komatsu KOMTRAX: Username, Password, Subscriber ID.
6. Toggle Enabled on.
7. Select Save.

Updating an existing connection: Leave the secret/password/API key field blank to keep the saved value. Saved secrets are never displayed.

2. Test the connection

1. On a saved, enabled connection, select Test Connection.
2. Samurai CMMS authenticates with the provider and requests a page of fleet data without importing anything, then reports whether the credentials work and basic details such as asset count.
3. If the test fails, recheck the credentials and URLs entered in step 1, then try again.

3. Sync telematics data

Each connection has a single Sync Telematics button that imports three things in one run: matched assets, GPS locations, and cumulative meter readings (e.g. operating hours, distance, fuel used — the exact meters depend on what the provider reports).

1. Open Settings > API Integrations and confirm the connection is Connected.
2. Select Sync Telematics.
3. Wait for the result message, e.g. "CAT telematics sync succeeded: 42 matched asset(s), 42 location(s), and 40 usage reading(s) imported."
4. Only one manual sync can run at a time per connection — if you see a message that a sync is already running, wait for it to finish.

4. Schedule automatic syncs

1. On the connection, turn on Auto Sync.
2. Choose Syncs per Day: 1, 2, or 3.
   • 1 sync/day runs at 6:00 AM.
   • 2 syncs/day run at 6:00 AM and 6:00 PM.
   • 3 syncs/day run at 6:00 AM, 2:00 PM, and 10:00 PM.
3. These times use the server's timezone, not a per-company timezone setting.
4. Scheduled syncs only run for connections that are both Enabled and have Auto Sync on.

5. Review sync history

1. On the connection, select View Log.
2. The log lists sync runs from the last 30 days, showing: trigger type (manual or scheduled), status (success/failed), start time, assets received, locations imported, meter readings imported, failed records, and an error code if the run failed.
3. Use this to confirm scheduled syncs are running and to diagnose failures without needing to run a new sync.

6. How asset matching works

Samurai CMMS matches telematics assets to Samurai assets automatically — there is no manual "link asset" action.

• Matching is attempted by serial number first, then equipment number or asset number, depending on the provider.
• Assets that can't be matched (no match, or more than one possible match) are still recorded but their location and meter data is not imported until matched.

To review matching:

1. Open Reference Tables > Telematics Mappings.
2. Use the filters for Provider, Manufacturer, Match Status, and Match Method to narrow the list.
3. Check the Match Status and Match Method columns for each provider asset, along with the linked Samurai Asset and Last Seen date.
4. For unmatched assets, verify the serial number or equipment number on the Samurai asset record matches what the provider reports, then run a sync again.

7. Where synced data appears

• Asset list: a barometer icon appears next to metered assets — blue if the asset has a matched telematics mapping, grey otherwise.
• Meter Readings panel on an asset: a provider badge (logo and name) appears next to a meter when its readings came from a telematics sync.
• Asset Map / Location views: synced GPS positions appear as markers. Locations older than 30 days are flagged as stale.

Telematics integrations do not currently import fault codes or diagnostic trouble codes — only location and meter/usage data.

Troubleshooting

Test Connection fails

Recheck the credentials, token URL, and API base URL entered in Configure. For Volvo, also confirm the Gateway Client ID/Secret are correct — these are separate from the main OAuth credentials.

Connection shows an error message

The card displays the last sync error under the connection status. Common causes are expired or revoked credentials, or a provider outage. Update credentials in Configure if needed, then select Test Connection before syncing again.

Assets are missing location or meter data after a sync

Open Reference Tables > Telematics Mappings and check the asset's Match Status. If it's unmatched or ambiguous, correct the serial number or equipment number on the Samurai asset (or resolve the duplicate), then run Sync Telematics again.

Scheduled sync didn't run

Confirm both Enabled and Auto Sync are on for the connection, and check View Log for a failed run and its error code. Scheduled sync times are fixed (6 AM / 2 PM / 6 PM / 10 PM server time) based on the Syncs per Day setting.

Sync fails repeatedly with an authentication error

Provider credentials may have expired or been rotated on the provider's side. Update them in Configure, save, and use Test Connection to confirm before running Sync Telematics again.

Support checklist

If you need help, capture the following details before contacting support:

• The provider and connection (Company Name) affected.
• The connection status and error message shown on the integration card.
• The relevant entry from View Log, including the error code.
• The affected asset's Match Status and Match Method from Telematics Mappings, if data isn't appearing on an asset.
• The approximate date and time of the failed sync attempt.