Trigger a manual sync run

The sync worker normally runs on an Adaptive Cadence — every 15 minutes when chargers are active, hourly when idle, weekly when dormant. Trigger a manual sync run when you need fresh transactions reflected in billing immediately: after closing out a session with a VIP customer, while investigating a missing Lago event, or before pulling a reconciliation report.

A manual trigger also bumps the scheduler back to the Active tier (15-minute cadence) for the period that follows, so it’s the right tool when you know activity is about to pick up.

Prerequisites

• You are signed in to the admin web console with operator permissions.
• The sync worker container is running. If it isn’t, a manual trigger silently goes nowhere — the NOTIFY is fire-and-forget with no retry.
• You know which sync run you’re trying to produce. If you’re debugging a specific ChargeBox or idTag, have its identifier handy for the verify step.

Procedure

1. Open the Sync dashboard

   From the admin console sidebar, go to Sync. The dashboard shows the current scheduler tier, the timestamp of the last run, and the Trigger Sync button.

   Screenshot pending

   Sync dashboard with Trigger Sync button visible

2. Click Trigger Sync

   Click Trigger Sync. The console calls POST /api/admin/sync/trigger , which sends a PostgreSQL NOTIFY on the sync_trigger channel and returns immediately with {"message":"Sync trigger notification sent to worker"}.

   The button does not wait for the sync to finish — it only confirms the notification was sent. The sync itself happens asynchronously in the worker.

   Note

   The endpoint is idempotent. If you click twice in quick succession, the second click returns the cached response from the first; the worker will not receive two notifications.

3. Wait for the worker to pick it up

   The sync worker receives the notification within milliseconds over its dedicated LISTEN connection. It then:

   1. Records the manual activity, bumping the scheduler to the Active tier.
   2. Calls handleSync() — unless a sync is already in flight, in which case the trigger is skipped (the worker logs Sync already in progress, skipping...).
   3. Re-evaluates the cadence tier once the run completes.

Verify

Confirm the manual run actually executed:

1. On the Sync dashboard, refresh and check that the “Last run” timestamp has advanced to within the last minute or two.
2. Open the run detail — you should see a new entry showing eventsCreated and transactionsProcessed counts.
3. If you triggered the sync to chase a specific transaction, search the Lago event log for the matching Lago metric event.
4. Confirm the scheduler tier is now Active (15-minute cadence) on the dashboard header.

If you have shell access to the sync worker container, you can also tail its logs and look for:

[Sync Worker] Received sync trigger notification from api
[Sync Worker] Sync completed in 1.42s: 3 events created, 5 transactions processed

If something goes wrong

Caution

The dashboard never updates. The API returned 200 but the sync worker isn’t running, or its LISTEN connection has dropped. Check the worker container’s status and logs. The worker auto-reconnects its LISTEN every 5 seconds on failure, but if the container is down entirely, your notification was lost — there is no retry queue.

Caution

API returns 500 — Failed to trigger sync. The notifier couldn’t open its PostgreSQL connection. Check database connectivity from the web app and retry. No notification was sent, so no state was changed.

Caution

Worker logs Sync already in progress, skipping. A previous run (manual or scheduled) is still executing. Wait for it to finish — its result will cover whatever you were trying to trigger. If runs are consistently overlapping, the underlying sync is slow and needs investigation; manual triggers won’t help.

Caution

Sync completed but the event you expected isn’t there. The trigger only asks the worker to run; it doesn’t change what the sync sees. If the upstream SteVe transaction is missing or malformed, the sync will complete cleanly with that transaction omitted. Check the run’s errors array and the SteVe transaction log directly.

Audit and reversibility

A manual trigger is not destructive. It does not write any state directly — it only asks the worker to run the same sync logic that runs on the cron schedule. Anything the resulting sync creates (Lago events, user mappings, reservation resolutions) is created by the sync run itself and is logged the same way as any scheduled run.

What gets recorded:

• The web app logs Manual sync triggered via notification at INFO.
• The worker logs Received sync trigger notification from api and the resulting Sync completed line with event and transaction counts.
• The resulting sync run appears in the Sync dashboard’s run history alongside scheduled runs.

There is no “undo” for a sync run, because a sync run is itself an idempotent reconciliation — running it again won’t double-count events. If a manual trigger surfaces a bad event in Lago, the correction happens in Lago, not by reverting the sync.

Related

• Adaptive Cadence overview
• Investigate a missing Lago event
• Sync worker deployment
• Glossary: Sync run