GPS integration setup (Cartrack)

What this guide covers

Connecting the Fleet module to the Cartrack telematics service so vehicle positions flow into the live map and trip history. This is an administrator task (FLEET_ADMIN).

Where to find it

Open Fleet → GPS Integration.

Cartrack's Fleet API uses a dedicated API credential, which is different from your Cartrack web-portal login. Using the web-portal password will fail with an authentication error.

To obtain it in Cartrack: Settings → API Settings → Manage API Credentials, and copy the long API Password (an API key).

On the GPS Integration page set:

Base URL — the Cartrack Fleet API base (region-specific).
Username — your Cartrack API username.
API Password — the API key from the step above.
Enabled — turn the integration on.

Password field behaviour: for security the API Password field shows blank when you reopen the page. Leaving it blank on save keeps the stored key — only type in it when you actually want to change the key. Do not blank it expecting the old value to remain typed; blank simply means "no change".

Test, poll and import

The page has four actions:

Test connection — verifies the credentials and base URL without storing anything that moves data. Use this first.
Poll now — fetches the current positions immediately (the same thing the background schedule does every ~30 seconds).
Import vehicles — pulls the vehicle list from Cartrack and creates the matching vehicle records for you, so you do not have to type them in by hand.
Remove duplicates / test — cleans up duplicate or test entries.

How vehicles are matched

Each incoming GPS fix is matched to a vehicle by its device id, which for Cartrack is the vehicle's registration as Cartrack reports it. The import sets this for you. If you add a vehicle manually, set its GPS device id to exactly match Cartrack or its fixes will be dropped as "unknown device".

Cartrack "TAG" duplicates: Cartrack may list each vehicle twice — once under its real registration and once under a secondary "TAG" identity. The import detects and skips these duplicates, so a 20-row Cartrack account that is really 10 vehicles imports as 10.

How the feed runs

A background job polls Cartrack roughly every 30 seconds while the integration is enabled.
Positions are cached locally; the live map and lists read the cache (never a live call on a user request).
Trips are derived automatically from the position stream and attributed to whoever holds the vehicle's keys at the time.

Troubleshooting

Authentication error on Test connection — you are almost certainly using the web-portal login. Use the API Password from Manage API Credentials.
A vehicle never appears on the map — check its GPS device id matches the Cartrack registration exactly.
"Poll now" reports nothing stored — the background schedule has probably already ingested the latest fix; a manual poll only stores positions newer than what is already cached.