Using the Systemise integrationBeta

This guide covers day-to-day use of the Systemise integration for Vectis fleet administrators and Systemise administrators. It assumes the integration is already installed and connected; if not, start with Systemise integration setup.

How data flows#

Events flow from Vectis to Systemise as signed webhooks. Changes flow from Systemise to Vectis through authenticated API calls. Both directions are automatic once the integration is connected.

Assigning a vehicle to a job#

Vehicles are assigned in Systemise when you schedule or edit a job.

1. Edit the job

   Open the job in Systemise and edit it. Set the job's start and end times, so vehicle availability can be shown.

2. Choose a pool

   In the Vehicle (Vectis Fleet) section, choose a pool from the Pool list. Pools are the vehicle groups set up in Vectis (for example "Site Vehicles" or "Utes").

3. Choose a vehicle

   The vehicles available for the job's time window are listed. Select the one you want.

4. Save the job

   Save. The vehicle is assigned, pending its booking.

What happens next:

• Systemise records a link between the job and the future Vectis booking, with status pending.
• When the job is scheduled, the integration creates a booking in Vectis for that vehicle, covering the job's scheduled times.
• The job then shows Vehicle Booked.
• The booking is attributed to the Vectis driver linked to the job's employee (through employee sync).

How bookings are created and cancelled#

Creation#

When a Systemise job is scheduled with a vehicle assigned, the integration creates a Vectis booking for that vehicle, the job's times and the linked driver, with the Systemise job number as its reference.

The booking appears in Vectis straight away. Its booking detail shows a Systemise section with the job reference and company name.

In Systemise, the job shows the Vectis booking with its status and vehicle, and, once the driver checks the vehicle out and in, the actual start and end times.

Cancellation#

When a Systemise job is cancelled, the integration cancels the matching Vectis booking and the job's booking link is marked cancelled. Vectis sends a booking.cancelled webhook back to Systemise to confirm.

Trips and timesheets#

When a trip in a Vectis-booked vehicle is completed, Vectis sends a trip.completed webhook to Systemise. Systemise finds the job linked to the booking and creates a timesheet entry on the job for the job's employee, with:

• the trip's date;
• the duration, rounded up to the next quarter hour (minimum 0.25 hours);
• a Via Vectis badge, so it is identifiable as an imported entry.

If timesheets are not appearing#

• Check the driver is linked to a Systemise employee (see Employee sync).
• Check the trip is Completed in Vectis, not still active.
• Check Recent Webhook Events on the Vectis Fleet page for the trip.completed event.

Fuel and job costing#

When a fuel transaction is recorded in Vectis for a vehicle with an active job link, Vectis sends a fuel.created webhook to Systemise. Systemise finds the job linked to that vehicle's booking at that time and creates a job cost entry with:

• the fuel amount (litres);
• the cost;
• the fuel type;
• a Via Vectis badge.

No duplicates: each fuel transaction has a unique Vectis reference. If a webhook is delivered more than once, for example on a retry, Systemise skips the duplicate.

If fuel costs are not appearing#

• Check the fuel:read scope is granted on the Scopes tab of the Systemise app in Vectis (Settings → Marketplace Apps → Systemise).
• Check the fuel transaction was recorded while the vehicle had an active job link.
• Check Recent Webhook Events for the fuel.created event.

Failed inspection alerts#

When a Vectis vehicle inspection is completed with a Failed result, Systemise receives an inspection.completed webhook and adds a note to the linked job. The note gives the vehicle, the inspection time and the items that failed. The job also shows a vehicle alert, which can be dismissed.

If a field worker is already on the way to a job in a vehicle that failed its pre-start inspection, the dispatcher sees it on the job and can act — assign another vehicle, arrange a replacement or cancel the job — without checking Vectis separately.

Only failed inspections create notes.

If inspection alerts are not appearing#

• Check the inspections:read scope is granted in Vectis.
• Check the inspection result is Failed.
• Check the vehicle had an active job link at the time of the inspection.

Seeing a vehicle's location from a job#

If the vehicle has a telematics device connected to Vectis, you can see its location from the Systemise job.

On the web: open the job and, in the Vectis vehicle section, select Show Location. Systemise shows the vehicle's last known position; select Refresh to update it, or Open in Maps to see it in Google Maps.

In the mobile app: the job's navigation map shows the vehicle alongside the site.

If location is not available#

• Check the telematics:read scope is granted in Vectis.
• Check the vehicle has a telematics device connected in Vectis, reporting a recent GPS position.
• If the device is offline, its position cannot be updated until it reconnects. See Device not connecting.

The integration page#

Systemise's Vectis Fleet integration page gives administrators a view of the integration's health and activity.

Retrying failures#

A booking failed#

If a booking could not be created in Vectis when the job was scheduled (for example after a temporary network error), the job shows Booking Failed.

1. Open the job in Systemise.
2. In the Vectis booking panel, select Retry Booking.
3. If the retry succeeds, the job shows Vehicle Booked.

If it fails again, check the integration page for connection errors and check the vehicle is still free for the booking period.

A webhook event failed#

In Recent Webhook Events on the Vectis Fleet page, find the failed event and select Retry. Systemise processes it again.

Automatic retries: Vectis retries failed webhook deliveries automatically: immediately, after 1 minute and after 5 minutes. After 3 failed attempts the delivery is marked dead lettered and automatic retries stop. The Retry button in Systemise works regardless.

Common reasons for failed events:

• the linked employee has been deactivated in Systemise;
• the job linked to the booking has been deleted;
• a temporary error (retrying usually fixes it).

A duplicate fuel transaction is skipped, not treated as an error.

Notifications for field workers#

When a Vectis booking is checked out or checked in, the Systemise employee linked to the booking's driver is notified in the Systemise mobile app.

Notifications need:

• the Systemise mobile app installed and signed in;
• notifications allowed for Systemise on the device;
• the employee linked to their Vectis driver account (see Employee sync).

Troubleshooting#

Nothing arrives from Vectis#

If no timesheets, fuel costs, inspection alerts or check-out and check-in times arrive, even though the integration shows as connected, Systemise may not be subscribed to any webhook topics. In Vectis, open Settings → Marketplace Apps → Systemise and check the Webhooks tab. It should show 6 subscriptions pointing at your Systemise webhook address.

The pool selector or vehicles are not appearing on the job#

• Check the integration is connected.
• Check the job has start and end times.
• Check the vehicles:read scope is granted in Vectis.
• Check at least one pool in Vectis has active vehicles.

A booking was not created when a job was scheduled#

• If the job shows Booking Failed, select Retry Booking.
• Check the vehicle is free for the job's times in Vectis.
• Check the integration page for connection errors around the time the job was scheduled.

A timesheet entry is missing#

1. Check the trip is Completed in Vectis.
2. Check the driver is linked to a Systemise employee.
3. Check Recent Webhook Events for a trip.completed event, and retry it if it failed.
4. If there is no trip.completed event at all, check the trips:read scope is granted in Vectis.

A fuel cost is missing#

1. Check the fuel:read scope is granted in Vectis.
2. Check the fuel transaction falls within the vehicle's active booking period.
3. Check Recent Webhook Events for a fuel.created event, and retry it if it failed.

An inspection alert is missing#

1. Check the inspection result is Failed in Vectis.
2. Check the inspections:read scope is granted in Vectis.
3. Check the vehicle had a job link at the time of the inspection.

Vehicle location is missing or out of date#

1. Check the telematics:read scope is granted in Vectis.
2. In Vectis, check the vehicle has a connected device with a recent GPS position.
3. If the device is offline, its position cannot be updated until it reconnects.

Notifications are not arriving#

1. Check the field worker has allowed notifications for the Systemise app.
2. Check their Systemise employee is linked to the correct Vectis driver.
3. Check Recent Webhook Events for booking.checked_out or booking.checked_in events, and retry any that failed.

Systemise asks you to reconnect, or shows the integration as disconnected#

• If Systemise says your Vectis connection was set up with the old credential method, select Connect to Vectis to re-authorise with your Vectis account. No credentials need to be copied.
• If the Systemise app was uninstalled from Vectis, install it again (see setup), then select Connect to Vectis.
• Otherwise, check network connectivity between Systemise and Vectis with your IT team.

Webhook events reference#

Vectis sends these events to Systemise. Each is signed with HMAC-SHA256 using the installation's webhook secret, and Systemise verifies the signature before processing it.

Each event also appears in Recent Webhook Events on the integration page.