Vehicles

Part of the IP4CMS portal. ← All module guides

What it's for — Vehicles is a register of the vehicles your organisation tracks: fleet vehicles, members' cars, vehicles tied to a property in an estate, and so on. Each record holds identifying details (name/label, registration, make, model, colour, a photo) and can be linked to a member and/or a property location. When your tenant is licensed for the Vehicles module, you can also store a last-known GPS position on each vehicle so it can be shown on maps.

Where to find it — Main portal menu under Vehicles (route /app/vehicles). The list of Vehicle Types is maintained from Settings → Vehicles (the in-module "Vehicle Types" link redirects there at /app/settings/vehicles).

Before you start

• Your user needs vehicle permissions (see Permissions & access). Without vehicles:read:all you cannot open the list.
• GPS coordinates are only saved when your tenant's licence includes the Vehicles module. If it doesn't, the Coordinates section is hidden and any latitude/longitude is ignored on save.
• The Property picker only appears when your tenant has the Properties module enabled.
• The Documents section (extra files per vehicle) only appears when a Documents module is enabled and you are editing an already-saved vehicle.
• To add custom vehicle types you need the "manage types" permission.

Key tasks

Register a vehicle

1. Go to Vehicles and click Add Vehicle (visible only if you can create vehicles).
2. Fill in the form:

• Name / Label (required) — a friendly label, e.g. "Church Van 1". Max 255 characters.
• Registration — the number plate, e.g. "ABC 123 GP". Optional, but if entered it must be unique within your fleet (it is stored normalised: upper-cased, spaces removed). Saving a duplicate plate is rejected.
• Member — optional. Type 2+ characters to search members by name or email and link the vehicle to a member record.
• Property — optional, shown only with the Properties module. Search and link a property-type location. Note: if you select both a member and a property, the property must fall within that member's approved property claim, or the save is rejected.
• Vehicle Type (required) — pick from the dropdown (built-in types plus any custom types).
• Make / Model / Colour — optional free text (e.g. Toyota / Hiace / White), each max 255 characters.
• Coordinates (GPS) — optional, shown only with the Vehicles module licence (see below).
• Main photo — optional. JPEG, PNG, GIF or WebP, max 5 MB. A preview appears; use Remove photo to clear it.

1. Click Add Vehicle. The record saves; if you attached a photo, it uploads immediately after.

Your tenant may make some fields (such as member or property links) required via field policy. If a required field is missing the save is rejected with a message.

Edit or delete a vehicle

• In the list, use the Edit action on a row to reopen the form (titled "Edit Vehicle"). The full record is reloaded so member/property names, the photo and coordinates are populated. Make changes and click Save.
• Use Delete to remove a vehicle. You confirm first; the record is then soft-deleted (hidden from the list but retained for audit history). Edit and Delete only appear if you have the matching permissions.

Set or capture GPS coordinates

The Coordinates (GPS) section appears only when the Vehicles module is licensed.

1. Enter Latitude and Longitude by hand, or click Use current location to fill them from your device's browser geolocation (you may be prompted to allow location access).
2. You must provide both latitude and longitude together, or leave both empty. Saving only one is rejected.
3. When editing, Clear stored coordinates removes the saved position on the next save. A "Last updated" timestamp shows when the position was last set.

Manage vehicle types

1. Go to Settings → Vehicles (Vehicle Types).
2. Standard types (Car, Motorcycle, Van, Truck, Bus, Minibus, SUV, Bicycle, Other) are always available and are not listed here — this screen only holds your custom additions.
3. Click Add Vehicle Type, enter a Name (e.g. "Trailer", max 255 chars), optionally upload a Picture (JPEG/PNG/GIF/WebP, max 5 MB), and Save. The new type then appears in the vehicle form's Type dropdown.
4. Use Edit to rename or change the icon, and Delete to remove a custom type. Deleting a type may affect vehicles already using it, so you are warned before confirming.

Attach extra documents to a vehicle

When a Documents module is enabled, editing a saved vehicle shows a Documents section at the bottom of the form. Use it to store additional files against that vehicle (separate from the single main photo). These are stored as vehicle attachments tied to the vehicle's ID.

How the data connects

• What you enter → where it's stored. Each vehicle is a row in the tenant vehicle table (name, registration, make, model, colour, photo URL, type, optional member_id, optional property_location_id, optional tracking_latitude/tracking_longitude/tracking_updated_at). Custom types live in vehicletype. Extra files live in vehicleattachment (cascade-deleted with the vehicle). Records are tenant-scoped and soft-deleted (a deleted_at flag) rather than erased.
• Member link. Linking a vehicle to a member ties it to that member's record; the member's name is shown in the vehicle list. If a linked member is later removed, the link is cleared (set to null) rather than deleting the vehicle.
• Property link. Linking to a property-type location associates the vehicle with that property (its name shows in the list). This requires the Properties module, and when a member is also linked the property must be one the member has an approved claim on.
• Vehicle type. The Type can be a built-in value or one of your custom types; the list resolves the stored value to its display label.
• Mapping / coordinates. The stored GPS position is the vehicle's last-known location for map display. Maps use this coordinate first, then fall back to the linked property's location, then the member's base location.
• Audit. Create, update and delete are recorded in the audit log (entity type vehicle) so changes are traceable.

Permissions & access

The portal only shows Vehicles if your tenant's licence enables it, and GPS storage specifically requires the Vehicles module on the licence. Actions are gated by these permissions:

Buttons (Add, Edit, Delete) are hidden when you lack the matching permission, and the API enforces the same checks. Listing vehicles filtered by a specific property is additionally allowed for users with property/location read permissions even without vehicles:read:all.

Tips & gotchas

• Registrations are normalised and must be unique. "abc 123 gp" and "ABC123GP" are treated as the same plate; a duplicate save is rejected across the fleet.
• Both coordinates or neither. Entering only a latitude (or only a longitude) fails validation — fill both or clear both.
• GPS needs the licence. If the Vehicles module isn't on your licence, the Coordinates section won't show and coordinates won't be saved even if sent.
• Photo vs documents. The form's Main photo is a single image (max 5 MB). For more files, save the vehicle first, then reopen it and use the Documents section (only if a Documents module is enabled).
• Photo upload can fail separately. The vehicle saves first, then the photo uploads. If the photo upload fails you'll see a "Partial save" message — the vehicle is saved, but re-edit to retry the photo.
• Member + property together is restricted. You can link a property on its own, but pairing a property with a member requires that member's approved claim on that property.
• Custom types are tenant-wide. New types added under Settings appear for everyone in the vehicle dropdown; the standard nine types are always present and aren't editable.
• Deletes are recoverable in principle. Deleting hides the vehicle but keeps the row (soft delete) for audit purposes.