SfSkills Domains Docs GitHub

Home / apex / fsl-custom-actions-mobile

fsl-custom-actions-mobile

Use this skill when building custom LWC actions for the FSL Mobile app: barcode scanning, GPS capture, photo/signature capture, or custom guided workflows on mobile. Trigger keywords: FSL Mobile custom action, lightning__GlobalAction FSL, barcode scanner LWC, mobileCapabilities, Nimbus plugin, FSL lightning SDK. NOT for offline priming, deep links or the legacy HTML5 toolkit — use apex/fsl-mobile-app-extensions. NOT for LWC in the standard Salesforce mobile app — use lwc/lwc-offline-and-mobile.

Open the skill folder on GitHub

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:

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:

Plugin ImportCapability
lightning/mobileCapabilitiesMeta-module — use to get specific plugins
getBarcodeScanner()Barcode and QR code scanning
getLocationService()GPS coordinates
getCameraCapture()Photo capture

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

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

SituationRecommended ApproachReason
Action from main mobile navlightning__GlobalAction + App ManagerApp-level, not tied to a record
Action on Work Order recordlightning__RecordAction + page layoutRecord-scoped
Barcode scanninggetBarcodeScanner() with isAvailable() guardNative barcode integration
GPS stampgetLocationService() with high accuracyDevice GPS vs. browser geolocation
Photo documentationgetCameraCapture() Nimbus pluginNative camera via Nimbus
Testing on desktopGuard with isAvailable() = false, show fallback UIDesktop has no Nimbus bridge

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

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

ArtifactDescription
LWC component with Nimbus integrationJavaScript + HTML + XML metadata with correct target and Nimbus availability guard
Permission set assignment checklistPermission sets required for FSL Mobile custom actions

Package files