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, and checking that the feed is actually running. Changing the settings is an administrator task (FLEET_ADMIN); dispatch can open the console to read it.

Where to find it

Open Fleet → GPS (health · log · integration). The page is titled GPS and has three tabs:

Health — whether the feed is LIVE or DOWN, when the last successful poll was, the newest vehicle position, and a per-vehicle table of last fix, age, status and who holds the keys.
Poll log — the in-memory log of poll attempts on this server node, newest first, with Refresh and Clear buttons.
Integration — the scheduler state for this node and the Cartrack Fleet API settings panel.

The rest of this guide is about the Integration tab.

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

In the Cartrack Fleet API panel set:

Base URL — the Cartrack Fleet API base (region-specific).
API Username — your Cartrack API username.
API Password / Key (leave blank to keep current) — the API key from the step above.
Enable background polling — the switch that turns scheduled polling on.

Press Save to store the settings.

Password field behaviour: for security the password field shows blank (placeholder "unchanged") 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. Blank simply means "no change".

Test, poll, sync and import

The panel has five actions plus Save:

Test connection — saves the settings and verifies the credentials and base URL. Use this first.
Poll now — fetches the current positions immediately, the same call the background schedule makes. It works on any node, whether or not scheduled polling is enabled there.
Sync trips now — pulls trips from Cartrack now instead of waiting for the schedule.
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 30-second timer runs on every server node, but it only polls Cartrack when three things are true: Enable background polling is on, the node was started with the JVM option -Dfleet.gps.enabled=true, and the node is the active scheduler node (-Dnode.name is production, or not set). Otherwise the timer fires and does nothing every tick.
The Integration tab shows this plainly at the top: "Scheduled GPS poll on this node: ENABLED" or "DISABLED", with the current values of both JVM options and whether the scheduler node is ACTIVE or standby.
Positions are cached locally; the live map and lists read the cache (never a live call on a user request).
Trips are derived from the position stream and attributed to whoever holds the vehicle's keys at the time.

The JVM option is read at startup. Adding <jvm-options>-Dfleet.gps.enabled=true</jvm-options> to the Payara domain.xml needs a full server restart — a reload or redeploy will not pick it up.

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.
The Health tab says the feed is DOWN or "Scheduled polling is not enabled on this server node" — open the Integration tab and read the scheduler block. If it says DISABLED, the JVM flag is missing on this node; if the flag is on but the node is standby, polling is deliberately suppressed there.
The Poll log is empty — scheduled polling only logs on the node that runs it. Press Poll now on the Integration tab to record an attempt on the node you are looking at.
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.

Managing vehicles — the GPS device id on the vehicle record.
Live map and vehicle tracking — where the positions end up.
Fleet Management — the map of the whole module.