@fleetbase/fleetops-engine 0.6.69 → 0.6.71

package/RELEASE.md

@@ -1,25 +1,32 @@
-> v0.6.69 ~ "Fleet-Ops tools for Fleetbase AI"
+> v0.6.71 ~ "Extensible tables and panels, configured order lifecycles and order presentation profiles"
 
 ---
-## What's New
-- **Fleet-Ops works with Fleetbase AI tool calling.** Creating orders from the AI prompt works again with the tool-calling assistant, and the assistant can also propose an optimized waypoint sequence for an order and explain what an order or resource import needs. Every change is a preview card the user confirms.
-- **Fleet-Ops console actions.** The assistant can offer to open Fleet-Ops pages and dialogs, such as **Operations › Orders** and **New Order**, as confirmation cards.
-- **Resource search for the assistant.** A `fleetops_search` tool finds orders, vehicles, drivers, work orders, maintenances, devices, sensors and telematics records by id, name, plate, VIN, email or phone.
+## Highlights
 
----
-## Fixes
-- AI resource search no longer fails on every call with `Unknown column 'sensor_type'`, and database errors are no longer passed to the model.
+- **Resource view registries.** Extensions can add the following through `fleet-ops:<resource>:table:<slot>` and `fleet-ops:<resource>:details:<slot>`:
+  - columns, row actions, bulk actions and toolbar buttons on every top-level Fleet-Ops table;
+  - header buttons and "…" menu items on its details panels and side panels.
 
----
-## Dependencies
-- `@fleetbase/fleetops-data` upgraded to `^0.2.2`, which adds the read-only login state (`is_staff_linked`, `login_status`) to the driver and contact models.
-- `@fleetbase/ember-ui` upgraded to `^0.4.3`, which provides the `btn-auth` style the Track Order button on the login page uses.
+  Built-in items carry stable ids, so registered items can be placed before or after them.
+- **Configured order lifecycles.** An order config can define its own lifecycle in `meta.lifecycle`: `initial`, `completed`, `canceled` and `terminal` activities, `dispatch: false` and `strict_transitions`. The internal API starts orders at the initial activity, refuses to dispatch when dispatch is off, accepts only the flow's transitions when strict, and cancels to the configured activity. Configs without a lifecycle behave as before.
+  - **Lifecycle tab** in Order Configuration, to view and edit a config's lifecycle.
+  - **The board** shows a configured lifecycle's activities as its columns.
+  - **The activity flow editor** roots at the configured initial activity, and handles flows with cycles.
+- **Order presentation profiles.** An extension can give its order type its own order form sections, extra and hidden fields, details view sections and hidden actions, registered in `fleet-ops:order-presentation`. **Edit details** opens the profiled form. Other order types are unchanged.
+- **The Order Configuration manager lists every config**, including configs created while the console is open.
+- **An order's activity timeline follows status changes made on the server.**
+- **Fix: the Activity Flow crashed on a flow with a cycle.**
+- **Fix: order details now load the assigned vehicle with the order.**
+- **Fix: the order form failed when its custom fields couldn't load.**
+- **Fix: registered details tabs.** Opening a driver, vehicle or trailer side panel removed the route from tabs other extensions had registered, which broke them in the full details view. Side panels also left out the tabs they could render.
+- **Fix: the sensor details view showed the tabs registered for places.**
 
 ---
-## Testing
-- Unit tests cover the new AI tools and console commands, and the AI capability registration.
+## Upgrading
+Needs fleetbase/ember-core v0.3.25 and fleetbase/ember-ui v0.4.5.
 
 ---
 ## Need help?
 - [GitHub Discussions](https://github.com/fleetbase/fleetbase/discussions)
 - [Discord](https://discord.gg/HnTqQ6zAVn)
+---

package/addon/components/admin/telematics-settings.hbs

@@ -0,0 +1,143 @@
+<div class="space-y-6">
+    <InfoBlock @type="info" @icon="circle-info" class="mb-4">
+        Configure telematics retention policy and activity logging for all organizations. Organizations can choose device event and position history retention within these limits from Fleet-Ops &rsaquo; Settings &rsaquo; Telematics.
+        A maximum takes precedence over organization preferences, inherited defaults and requests to keep history forever. Reducing a maximum can delete existing history at the next cleanup.
+    </InfoBlock>
+
+    <ContentPanel @title="System Device Events Retention Policy" @open={{true}} @wrapperClass="bordered-classic">
+        <div class="grid grid-cols-1 md:grid-cols-2 gap-4">
+            <InputGroup @name="Default Device Event Retention (days)" @helpText="Retention for organizations that inherit the system default. 0 keeps history forever, subject to the maximum below.">
+                <Input @type="number" @value={{this.eventRetentionDays}} min="0" max="3650" class="form-input w-full" />
+            </InputGroup>
+            <InputGroup @name="Maximum Device Event Retention (days)" @helpText="The longest any organization can keep device events. 0 sets no maximum and allows organizations to keep history forever.">
+                <Input @type="number" @value={{this.maxEventRetentionDays}} min="0" max="3650" class="form-input w-full" />
+            </InputGroup>
+        </div>
+    </ContentPanel>
+
+    <ContentPanel @title="System Position History Retention Policy" @open={{true}} @wrapperClass="bordered-classic">
+        <div class="grid grid-cols-1 md:grid-cols-2 gap-4">
+            <InputGroup @name="Default Position History Retention (days)" @helpText="Retention for organizations that inherit the system default. 0 keeps history forever, subject to the maximum below.">
+                <Input @type="number" @value={{this.positionRetentionDays}} min="0" max="3650" class="form-input w-full" />
+            </InputGroup>
+            <InputGroup @name="Maximum Position History Retention (days)" @helpText="The longest any organization can keep vehicle and trailer positions. 0 sets no maximum and allows organizations to keep history forever.">
+                <Input @type="number" @value={{this.maxPositionRetentionDays}} min="0" max="3650" class="form-input w-full" />
+            </InputGroup>
+        </div>
+    </ContentPanel>
+
+    <ContentPanel @title="System Device Event Raw Payload Retention" @open={{true}} @wrapperClass="bordered-classic">
+        <InputGroup @name="Device Event Raw Payload Retention (days)" @helpText="Remove raw provider payloads from retained device events across all organizations after this many days. 0 disables compaction. This does not change how long the event history itself is kept.">
+            <Input @type="number" @value={{this.eventCompactAfterDays}} min="0" max="3650" class="form-input w-full" />
+        </InputGroup>
+    </ContentPanel>
+
+    <ContentPanel @title="System Delivery Inbox and Sync Run Retention Policy" @open={{true}} @wrapperClass="bordered-classic">
+        <div class="grid grid-cols-1 md:grid-cols-2 gap-4">
+            <InputGroup @name="Processed Delivery Retention (hours)" @helpText="Delete processed delivery envelopes across all organizations after this many hours. 0 keeps them forever.">
+                <Input @type="number" @value={{this.processedRetentionHours}} min="0" max="720" class="form-input w-full" />
+            </InputGroup>
+            <InputGroup @name="Quarantined Delivery Retention (days)" @helpText="Delete quarantined delivery envelopes across all organizations after this many days. 0 keeps them forever.">
+                <Input @type="number" @value={{this.quarantineRetentionDays}} min="0" max="365" class="form-input w-full" />
+            </InputGroup>
+            <InputGroup @name="Sync Run Diagnostics Retention (days)" @helpText="Delete finished sync run diagnostics across all organizations after this many days. 0 keeps them forever.">
+                <Input @type="number" @value={{this.syncRunRetentionDays}} min="0" max="365" class="form-input w-full" />
+            </InputGroup>
+        </div>
+    </ContentPanel>
+
+    <ContentPanel @title="System Telemetry Activity Logging" @open={{true}} @wrapperClass="bordered-classic">
+        <Toggle
+            @label="Log Telemetry Activity"
+            @helpText="Write telemetry-driven device, event and vehicle saves to the activity log for all organizations. Every poll can add several activity rows per device."
+            @isToggled={{this.logTelemetryActivity}}
+            @onToggle={{fn (mut this.logTelemetryActivity)}}
+        />
+    </ContentPanel>
+
+    <div class="flex justify-end">
+        <Button
+            @type="primary"
+            @size="sm"
+            @icon="save"
+            @text="Save System Policy"
+            @onClick={{perform this.saveSettings}}
+            @disabled={{or this.saveSettings.isRunning this.loadSettings.isRunning (not this.settingsLoaded)}}
+            @isLoading={{or this.saveSettings.isRunning this.loadSettings.isRunning}}
+        />
+    </div>
+
+    <ContentPanel @title={{t "settings.telematics.storage-usage"}} @open={{true}} @wrapperClass="bordered-classic">
+        <p class="mb-3 text-sm text-gray-600 dark:text-gray-300">
+            Storage usage includes telematics data across all organizations. Cleanup applies system-wide, using the saved system policy and each organization's history preferences within that policy.
+        </p>
+        <div class="flex items-center justify-end gap-2 mb-3">
+            <Button
+                @size="xs"
+                @icon="rotate"
+                @text={{t "settings.telematics.refresh"}}
+                @onClick={{perform this.loadUsage}}
+                @disabled={{this.loadUsage.isRunning}}
+                @isLoading={{this.loadUsage.isRunning}}
+            />
+            <Button
+                @type="danger"
+                @size="xs"
+                @icon="broom"
+                @text={{t "settings.telematics.run-cleanup"}}
+                @onClick={{this.confirmRunCleanup}}
+                @disabled={{or this.runCleanup.isRunning this.loadSettings.isRunning this.saveSettings.isRunning (not this.settingsLoaded)}}
+                @isLoading={{this.runCleanup.isRunning}}
+            />
+        </div>
+        {{#if this.usageRows.length}}
+            <div class="overflow-x-auto">
+                <table class="w-full text-sm">
+                    <thead>
+                        <tr class="text-left text-xs uppercase text-gray-500 dark:text-gray-400">
+                            <th class="py-2 pr-3">{{t "settings.telematics.table"}}</th>
+                            <th class="py-2 pr-3 text-right">{{t "settings.telematics.rows"}}</th>
+                            <th class="py-2 pr-3 text-right">{{t "settings.telematics.estimated-size"}}</th>
+                            <th class="py-2 pl-6 text-right whitespace-nowrap">{{t "settings.telematics.oldest"}}</th>
+                        </tr>
+                    </thead>
+                    <tbody class="divide-y divide-gray-100 dark:divide-gray-700">
+                        {{#each this.usageRows as |row|}}
+                            <tr class="text-gray-800 dark:text-gray-100">
+                                <td class="py-2 pr-3">
+                                    <div class="font-medium">{{row.label}}</div>
+                                    {{#if row.raw_payload_rows}}
+                                        <div class="text-xs text-gray-500 dark:text-gray-400">
+                                            {{t "settings.telematics.raw-payload-rows" count=(format-number row.raw_payload_rows) compactable=(format-number row.compactable_rows)}}
+                                        </div>
+                                    {{/if}}
+                                </td>
+                                <td class="py-2 pr-3 text-right">
+                                    {{#if (eq row.rows null)}}
+                                        {{t "settings.telematics.not-available"}}
+                                    {{else if row.rows_estimated}}
+                                        {{t "settings.telematics.estimated-rows" count=(format-number row.rows)}}
+                                    {{else}}
+                                        {{format-number row.rows}}
+                                    {{/if}}
+                                </td>
+                                <td class="py-2 pr-3 text-right">{{#if (or row.estimated_bytes (eq row.estimated_bytes 0))}}{{format-bytes row.estimated_bytes}}{{else}}{{t "settings.telematics.not-available"}}{{/if}}</td>
+                                <td class="py-2 pl-6 text-right text-xs whitespace-nowrap">{{#if row.oldest}}{{row.oldest}}{{else}}{{t "settings.telematics.not-available"}}{{/if}}</td>
+                            </tr>
+                        {{/each}}
+                    </tbody>
+                </table>
+            </div>
+            <p class="mt-3 text-xs text-gray-500 dark:text-gray-400">{{t "settings.telematics.space-reclaim-note"}}</p>
+        {{else if this.loadUsage.isRunning}}
+            <div class="flex items-center justify-center py-8">
+                <Spinner />
+            </div>
+        {{else}}
+            <div class="text-center py-8 text-sm text-gray-400 dark:text-gray-500">
+                {{t "settings.telematics.usage-unavailable"}}
+            </div>
+        {{/if}}
+    </ContentPanel>
+    <Spacer @height="200px" />
+</div>

package/addon/components/admin/telematics-settings.js

@@ -0,0 +1,145 @@
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { inject as service } from '@ember/service';
+import { action } from '@ember/object';
+import { task, timeout } from 'ember-concurrency';
+
+/**
+ * System-wide telematics policy, storage diagnostics and operational controls.
+ */
+export default class AdminTelematicsSettingsComponent extends Component {
+    @service fetch;
+    @service notifications;
+    @service intl;
+    @service modalsManager;
+    @tracked eventRetentionDays = 30;
+    @tracked maxEventRetentionDays = 0;
+    @tracked eventCompactAfterDays = 7;
+    @tracked positionRetentionDays = 90;
+    @tracked maxPositionRetentionDays = 0;
+    @tracked processedRetentionHours = 24;
+    @tracked quarantineRetentionDays = 7;
+    @tracked syncRunRetentionDays = 7;
+    @tracked logTelemetryActivity = false;
+    @tracked settingsLoaded = false;
+    @tracked usage = null;
+
+    constructor() {
+        super(...arguments);
+        this.loadSettings.perform();
+        this.loadUsage.perform();
+    }
+
+    @task({ drop: true }) *loadSettings() {
+        try {
+            const settings = yield this.fetch.get('fleet-ops/settings/admin-telematics-settings');
+            this.applySettings(settings);
+            this.settingsLoaded = true;
+        } catch (error) {
+            this.notifications.serverError(error);
+        }
+    }
+
+    @task({ drop: true }) *saveSettings() {
+        if (!this.settingsLoaded) {
+            return;
+        }
+
+        try {
+            const settings = yield this.fetch.post('fleet-ops/settings/admin-telematics-settings', this.settingsPayload);
+            this.applySettings(settings);
+            this.notifications.success('System telematics settings saved.');
+        } catch (error) {
+            this.notifications.serverError(error);
+        }
+    }
+
+    /** Load system-wide storage usage across all organizations. */
+    @task({ drop: true }) *loadUsage() {
+        const abortController = new AbortController();
+        const requestTimeout = setTimeout(() => abortController.abort(), 30000);
+
+        try {
+            // Pass the signal as request data; fetch.get options do not forward it.
+            const usage = yield this.fetch.request('fleet-ops/settings/telematics-storage-usage?include_payload_counts=0', 'GET', { signal: abortController.signal });
+            if (usage?.scope !== 'system') {
+                throw new Error(this.intl.t('settings.telematics.usage-unavailable'));
+            }
+            this.usage = usage;
+        } catch (error) {
+            this.notifications.serverError(abortController.signal.aborted ? new Error(this.intl.t('settings.telematics.usage-unavailable')) : error);
+        } finally {
+            clearTimeout(requestTimeout);
+            abortController.abort();
+        }
+    }
+
+    /** Queue cleanup for all organizations using the saved policy. */
+    @task({ drop: true }) *runCleanup() {
+        try {
+            const cleanup = yield this.fetch.post('fleet-ops/settings/telematics-retention/run');
+            if (cleanup?.scope !== 'system') {
+                throw new Error(this.intl.t('settings.telematics.cleanup-unavailable'));
+            }
+            this.notifications.success(this.intl.t('settings.telematics.cleanup-queued'));
+            yield timeout(5000);
+            yield this.loadUsage.perform();
+        } catch (error) {
+            this.notifications.serverError(error);
+        }
+    }
+
+    @action confirmRunCleanup() {
+        return this.modalsManager.confirm({
+            title: this.intl.t('settings.telematics.run-cleanup'),
+            body: this.intl.t('settings.telematics.run-cleanup-confirm'),
+            acceptButtonText: this.intl.t('settings.telematics.run-cleanup'),
+            acceptButtonIcon: 'broom',
+            onConfirm: () => this.runCleanup.perform(),
+        });
+    }
+
+    get usageRows() {
+        const tables = this.usage?.tables ?? {};
+
+        return ['device_events', 'positions', 'telematic_deliveries', 'telematic_sync_runs']
+            .filter((table) => tables[table])
+            .map((table) => ({ table, label: this.intl.t(`settings.telematics.tables.${table}`), ...tables[table] }));
+    }
+
+    get settingsPayload() {
+        return {
+            event_retention_days: this.toInteger(this.eventRetentionDays),
+            max_event_retention_days: this.maxEventRetentionDays,
+            event_compact_after_days: this.toInteger(this.eventCompactAfterDays),
+            position_retention_days: this.toInteger(this.positionRetentionDays),
+            max_position_retention_days: this.maxPositionRetentionDays,
+            processed_retention_hours: this.toInteger(this.processedRetentionHours),
+            quarantine_retention_days: this.toInteger(this.quarantineRetentionDays),
+            sync_run_retention_days: this.toInteger(this.syncRunRetentionDays),
+            log_telemetry_activity: Boolean(this.logTelemetryActivity),
+        };
+    }
+
+    applySettings(settings = {}) {
+        if (!Object.prototype.hasOwnProperty.call(settings ?? {}, 'max_event_retention_days') || !Object.prototype.hasOwnProperty.call(settings ?? {}, 'max_position_retention_days')) {
+            throw new Error(this.intl.t('settings.telematics.settings-unavailable'));
+        }
+
+        this.eventRetentionDays = settings.event_retention_days ?? this.eventRetentionDays;
+        this.maxEventRetentionDays = settings.max_event_retention_days ?? this.maxEventRetentionDays;
+        this.eventCompactAfterDays = settings.event_compact_after_days ?? this.eventCompactAfterDays;
+        this.positionRetentionDays = settings.position_retention_days ?? this.positionRetentionDays;
+        this.maxPositionRetentionDays = settings.max_position_retention_days ?? this.maxPositionRetentionDays;
+        this.processedRetentionHours = settings.processed_retention_hours ?? this.processedRetentionHours;
+        this.quarantineRetentionDays = settings.quarantine_retention_days ?? this.quarantineRetentionDays;
+        this.syncRunRetentionDays = settings.sync_run_retention_days ?? this.syncRunRetentionDays;
+        this.logTelemetryActivity = settings.log_telemetry_activity ?? this.logTelemetryActivity;
+    }
+
+    toInteger(value) {
+        const number = parseInt(value, 10);
+
+        return Number.isFinite(number) && number > 0 ? number : 0;
+    }
+}

package/addon/components/fuel-integration/hub.hbs

@@ -17,7 +17,7 @@
                 </div>
                 <div class="flex flex-shrink-0 items-center gap-2 whitespace-nowrap">
                     <Button @icon="refresh" @size="sm" @helpText={{t "common.reload"}} @onClick={{@onRefresh}} />
-                    <Button @icon="plus" @text="Connect Integration" @type="primary" @size="sm" @onClick={{this.createIntegration}} />
+                    <Button @icon="plus" @text="Connect Integration" @type="primary" @size="sm" @permission="fleet-ops create fuel-provider-connection" @onClick={{this.createIntegration}} />
                 </div>
             </div>
         </section>

package/addon/components/layout/fleet-ops-sidebar.js

@@ -151,14 +151,14 @@ export default class LayoutFleetOpsSidebarComponent extends Component {
             this.createItem('menu.contacts', 'address-book', 'management.contacts', 'fleet-ops list contact', 'fleet-ops see contact'),
             this.createItem('menu.places', 'location-dot', 'management.places', 'fleet-ops list place', 'fleet-ops see place'),
             this.createItem('menu.fuel-reports', 'gas-pump', 'management.fuel-reports', 'fleet-ops list fuel-report', 'fleet-ops see fuel-report'),
-            this.createItem('menu.fuel-transactions', 'credit-card', 'management.fuel-transactions', 'fleet-ops list fuel-report', 'fleet-ops see fuel-report'),
+            this.createItem('menu.fuel-transactions', 'credit-card', 'management.fuel-transactions', 'fleet-ops list fuel-provider-transaction', 'fleet-ops see fuel-provider-transaction'),
             this.createItem('menu.issues', 'triangle-exclamation', 'management.issues', 'fleet-ops list issue', 'fleet-ops see issue'),
         ]);
     }
 
     get maintenanceItems() {
         return this.withRegistryItems('maintenance', [
-            this.createHubItem('Maintenance Hub', 'wrench', 'maintenance.index', 'fleet-ops list maintenance-schedule', 'fleet-ops see maintenance-schedule', [
+            this.createHubItem('Maintenance Hub', 'wrench', 'maintenance.index', 'fleet-ops list work-order', 'fleet-ops see work-order', [
                 'maintenance hub',
                 'service readiness',
                 'maintenance control panel',
@@ -182,7 +182,9 @@ export default class LayoutFleetOpsSidebarComponent extends Component {
     get connectivityItems() {
         return this.withRegistryItems('connectivity', [
             this.createHubItem(this.intl.t('menu.telematics'), 'satellite-dish', 'connectivity.telematics', 'fleet-ops list telematic', 'fleet-ops see telematic', ['connectivity hub']),
-            this.createItem('menu.fuel-providers', 'gas-pump', 'connectivity.fuel-providers', 'fleet-ops list fuel-report', 'fleet-ops see fuel-report', ['fuel integrations']),
+            this.createItem('menu.fuel-providers', 'gas-pump', 'connectivity.fuel-providers', 'fleet-ops list fuel-provider-connection', 'fleet-ops see fuel-provider-connection', [
+                'fuel integrations',
+            ]),
             this.createItem('menu.devices', 'hard-drive', 'connectivity.devices', 'fleet-ops list device', 'fleet-ops see device'),
             this.createItem('menu.sensors', 'temperature-full', 'connectivity.sensors', 'fleet-ops list sensor', 'fleet-ops see sensor'),
             this.createItem('menu.events', 'stream', 'connectivity.events', 'fleet-ops list device-event', 'fleet-ops see device-event'),
@@ -191,18 +193,14 @@ export default class LayoutFleetOpsSidebarComponent extends Component {
 
     get analyticsItems() {
         return this.withRegistryItems('analytics', [
-            this.createHubItem('Dashboard', 'chart-line', 'analytics.index', 'iam list report', 'fleet-ops see report', ['dashboard', 'fleetops dashboard', 'metrics']),
-            this.createItem('menu.reports', 'file-import', 'analytics.reports', 'iam list report', 'fleet-ops see report'),
+            this.createHubItem('Dashboard', 'chart-line', 'analytics.index', 'fleet-ops view analytics', 'fleet-ops see analytics', ['dashboard', 'fleetops dashboard', 'metrics']),
+            this.createItem('menu.reports', 'file-import', 'analytics.reports', 'iam list report', 'iam see report'),
         ]);
     }
 
     get settingsItems() {
         return this.withRegistryItems('settings', [
-            this.createHubItem('Settings Hub', 'sliders', 'settings.index', 'fleet-ops view navigator-settings', 'fleet-ops see navigator-settings', [
-                'settings hub',
-                'configuration dashboard',
-                'setup focus',
-            ]),
+            this.createHubItem('Settings Hub', 'sliders', 'settings.index', null, null, ['settings hub', 'configuration dashboard', 'setup focus']),
             this.createItem('menu.navigator-app', 'location-arrow', 'settings.navigator-app', 'fleet-ops view navigator-settings', 'fleet-ops see navigator-settings'),
             this.createItem('menu.map', 'map', 'settings.map', 'fleet-ops view map-settings', 'fleet-ops see map-settings'),
             this.createItem('menu.payments', 'cash-register', 'settings.payments', 'fleet-ops view payments', 'fleet-ops see payments'),
@@ -210,8 +208,9 @@ export default class LayoutFleetOpsSidebarComponent extends Component {
             this.createItem('menu.routing', 'route', 'settings.routing', 'fleet-ops view routing-settings', 'fleet-ops see routing-settings'),
             this.createItem('menu.orchestrator', 'circle-nodes', 'settings.orchestrator', 'fleet-ops view routing-settings', 'fleet-ops see routing-settings'),
             this.createItem('menu.scheduling', 'calendar-days', 'settings.scheduling', 'fleet-ops view scheduling-settings', 'fleet-ops see scheduling-settings'),
-            this.createItem('menu.custom-fields', 'pen-to-square', 'settings.custom-fields', 'fleet-ops view custom-field', 'fleet-ops see custom-field'),
-            this.createItem('menu.avatars', 'icons', 'settings.avatars', 'fleet-ops view avatar', 'fleet-ops see avatar'),
+            this.createItem('menu.telematics-settings', 'satellite-dish', 'settings.telematics', 'fleet-ops view telematics-settings', 'fleet-ops see telematics-settings'),
+            this.createItem('menu.custom-fields', 'pen-to-square', 'settings.custom-fields', 'fleet-ops list custom-field', 'fleet-ops see custom-field'),
+            this.createItem('menu.avatars', 'icons', 'settings.avatars', 'fleet-ops list avatar', 'fleet-ops see avatar'),
         ]);
     }
 
@@ -265,18 +264,36 @@ export default class LayoutFleetOpsSidebarComponent extends Component {
     }
 
     createBranch({ id, label, icon, route, defaultRoute, requiresVisibleChildren = false, children, keywords = [] }) {
+        const visibleChildren = children.filter((item) => item.visible !== false);
+
         return {
             id,
             label,
             icon,
             route: this.fullRoute(route),
-            defaultRoute: this.fullRoute(defaultRoute),
+            defaultRoute: this.resolveDefaultRoute(this.fullRoute(defaultRoute), visibleChildren),
             requiresVisibleChildren,
-            children: children.filter((item) => item.visible !== false),
+            children: visibleChildren,
             keywords,
         };
     }
 
+    /**
+     * Keep the branch's default route when the user may open it; otherwise fall back to the
+     * first child route they are permitted to open, so clicking the branch does not land on a
+     * route guard that bounces them back out.
+     */
+    resolveDefaultRoute(defaultRoute, children = []) {
+        const permitted = (item) => [item.visiblePermission, item.permission].every((permission) => !permission || this.abilities.can(permission));
+        const defaultChild = children.find((item) => item.route === defaultRoute);
+
+        if (!defaultChild || permitted(defaultChild)) {
+            return defaultRoute;
+        }
+
+        return children.find((item) => item.route && permitted(item))?.route ?? defaultRoute;
+    }
+
     createItem(intl, icon, route, permission, ability, keywords = []) {
         return {
             priority: this.defaultPriorityForRoute(route),
@@ -290,7 +307,7 @@ export default class LayoutFleetOpsSidebarComponent extends Component {
         };
     }
 
-    createHubItem(label, icon, route, _permission, _ability, keywords = []) {
+    createHubItem(label, icon, route, permission, ability, keywords = []) {
         return {
             pinnedFirst: true,
             priority: this.defaultPriorityForRoute(route),
@@ -298,6 +315,8 @@ export default class LayoutFleetOpsSidebarComponent extends Component {
             description: label,
             icon,
             route: this.fullRoute(route),
+            permission,
+            visiblePermission: ability,
             isNavigationHub: true,
             keywords: [label, route, ...keywords].filter(Boolean),
         };
@@ -387,8 +406,9 @@ export default class LayoutFleetOpsSidebarComponent extends Component {
             'settings.routing': 5,
             'settings.orchestrator': 6,
             'settings.scheduling': 7,
-            'settings.custom-fields': 8,
-            'settings.avatars': 9,
+            'settings.telematics': 8,
+            'settings.custom-fields': 9,
+            'settings.avatars': 10,
         };
 
         return priorities[route] ?? 0;