Fsl Custom Actions Mobile

FSL Custom Actions Mobile

This skill activates when a developer needs to build custom LWC actions that run inside the FSL Mobile app — including barcode scanning, GPS-based actions, photo capture, and guided work flows. It covers the Lightning SDK for FSL Mobile, the Nimbus plugin device API, and the critical deployment constraints that differ from standard Lightning Experience LWC development.

Before Starting

Gather this context before working on anything in this domain:

• Confirm the Enable Lightning SDK for FSL Mobile permission set is assigned to all technician users. Without it, custom LWC actions silently fail to load in FSL Mobile even if page layout configuration is correct.
• Determine the action scope: lightning__GlobalAction (available from the app-level action bar — not tied to a specific record) or lightning__RecordAction (surfaced on a specific object's record page, e.g., Work Order). The targets have different page layout configuration paths.
• Identify which device capabilities are needed. All Nimbus plugin calls must be gated with isAvailable() before invocation — calling without availability check throws on devices or simulators where the capability is absent.
• Check whether the org uses the legacy HTML5 Mobile Extension Toolkit. The LWC-based Lightning SDK model is separate and not interchangeable with the legacy toolkit.

Core Concepts

Lightning SDK for FSL Mobile

The Lightning SDK is the framework that enables custom LWC components to run natively inside the FSL Mobile app (iOS and Android). Components authored for the Lightning SDK use standard LWC syntax but gain access to device-level capabilities via Nimbus plugins — the bridge between JavaScript and native device APIs.

Critical constraint: Components with lightning__GlobalAction target render ONLY in FSL Mobile. They do not render in the standard Lightning Experience desktop, the standard Salesforce Mobile App, or Experience Cloud. Developers who test a lightning__GlobalAction LWC in the desktop browser will see it in the page layout configuration but it will not function in the mobile app without the permission set and correct app configuration.

Nimbus Plugins — Device Capability Bridge

Nimbus plugins expose native device APIs to LWC JavaScript:

Availability gate (mandatory): Every Nimbus plugin must be checked with isAvailable() before calling its methods. On desktop or when the permission set is missing, the plugin returns null and calling methods on null throws immediately.

import { getBarcodeScanner } from 'lightning/mobileCapabilities';
const scanner = getBarcodeScanner();
if (scanner == null || !scanner.isAvailable()) {
    // Show disabled state or fallback
    return;
}

Action Target Configuration

• lightning__GlobalAction: Added to the FSL Mobile app's global action set in Setup > Apps > App Manager > FSL Mobile App. Appears in the mobile app's "+" action bar.
• lightning__RecordAction: Added to the page layout of a specific object (e.g., Work Order). Appears in the record's action panel in FSL Mobile.

Both require the component to declare the correct targets in its .js-meta.xml metadata.

Common Patterns

Barcode Scan Action

When to use: Technician needs to scan a product barcode to look up a part or confirm a serial number during a work order.

How it works:

// barcodeScanAction.js
import { LightningElement } from 'lwc';
import { getBarcodeScanner } from 'lightning/mobileCapabilities';

export default class BarcodeScanAction extends LightningElement {
    scanner;
    scannedCode = '';

    connectedCallback() {
        this.scanner = getBarcodeScanner();
    }

    get isScanAvailable() {
        return this.scanner != null && this.scanner.isAvailable();
    }

    handleScan() {
        if (!this.isScanAvailable) {
            return; // show error toast in real implementation
        }
        this.scanner.beginCapture({
            barcodeTypes: [this.scanner.BARCODE_TYPE_CODE128, this.scanner.BARCODE_TYPE_QR]
        }).then(result => {
            this.scannedCode = result.value;
            this.scanner.endCapture();
        }).catch(err => {
            this.scanner.endCapture();
        });
    }
}

Why not HTML input: Camera-based HTML5 input doesn't integrate with the device's native barcode scanning engine and produces unreliable results in field conditions.

GPS Location Capture

When to use: Technician needs to stamp GPS coordinates on arrival at a job site.

How it works:

import { getLocationService } from 'lightning/mobileCapabilities';

connectedCallback() {
    const locationService = getLocationService();
    if (locationService != null && locationService.isAvailable()) {
        locationService.getCurrentPosition({
            enableHighAccuracy: true,
            timeout: 10000
        }).then(result => {
            const lat = result.coords.latitude;
            const lng = result.coords.longitude;
            // Update record via Apex or wire
        });
    }
}

Decision Guidance

Recommended Workflow

Step-by-step instructions for an AI agent or practitioner working on this task:

1. Confirm Enable Lightning SDK for FSL Mobile permission set — Assign to all FSL Mobile users before attempting any deployment or testing. Missing this causes silent failure.
2. Choose and declare action target — Set lightning__GlobalAction or lightning__RecordAction in the LWC's .js-meta.xml <targets> section.
3. Import and guard Nimbus plugins — Import the required plugin from lightning/mobileCapabilities. Check isAvailable() before any device capability call. Build a visible fallback for desktop/non-supported contexts.
4. Configure in Setup — For lightning__GlobalAction: App Manager > FSL Mobile App > Action Bar. For lightning__RecordAction: page layout editor for the target object.
5. Test on a physical FSL Mobile device — Desktop browser testing will not invoke Nimbus plugins. Use a real iOS/Android device with FSL Mobile installed and permission set assigned.
6. Handle offline behavior — Verify action behavior when the device is offline; FSL Mobile's briefcase sync controls which records are available offline, not the LWC itself.

Review Checklist

• Enable Lightning SDK for FSL Mobile permission set assigned to target users
• targets in .js-meta.xml includes the correct target type
• All Nimbus plugin calls gated with isAvailable() check
• Fallback UI implemented for non-FSL-Mobile context
• Action added to correct location in Setup
• Tested on physical device with FSL Mobile app installed
• Offline behavior understood

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. lightning__GlobalAction components do NOT render in Lightning Experience desktop or standard Salesforce Mobile App — They only appear in FSL Mobile. Testing on desktop appears to work in configuration but produces no visible component for users.
2. Missing permission set causes silent load failure — No error is displayed to the technician. The action simply does not appear. Always verify the permission set before troubleshooting component code.
3. Nimbus plugin returns null on desktop — getBarcodeScanner() returns null in standard Lightning Experience. Calling .beginCapture() on null throws immediately. The isAvailable() guard is mandatory, not optional.
4. Legacy HTML5 Mobile Extension Toolkit and LWC are not interchangeable — Components built with the old toolkit require a full rewrite to use Nimbus plugins. Do not mix configuration from both models in the same org.

Output Artifacts

Related Skills

• apex/fsl-apex-extensions — Broader FSL Apex namespace and SDK patterns
• architect/fsl-offline-architecture — Offline data priming and sync behavior affecting custom action data access