first commit

docs/librenms_import/background_jobs.md

@@ -0,0 +1,76 @@
+# Background Jobs & Caching
+
+The Device Import feature uses background job processing and intelligent caching for both searching and importing devices. Background jobs are enabled by default for both operations to handle large device sets efficiently.
+
+## Background Jobs
+
+Background jobs run asynchronously in NetBox's job system for both device searches and import operations.
+
+### Background Job Processing
+
+Both device searches and import operations can run as background jobs (default) or synchronously. Background jobs are recommended for:
+
+- Large device sets (especially searches with more than 50 devices)
+- Operations with Virtual Chassis detection enabled
+- Import operations of any size
+
+**Benefits of background jobs:**
+- Avoid browser timeouts on long-running operations
+- Cancel operations in progress if needed
+- Continue using NetBox while the job runs
+- Review detailed logs and results after completion
+
+
+### Viewing Job Status
+
+All background jobs appear in NetBox's **Jobs** interface, where you can view status, start time, duration, and results.
+
+## Caching
+
+The import table caches data for 5 minutes to reduce load times and minimize API calls to LibreNMS. Cache keys are unique per filter combination.
+
+### What Gets Cached
+
+The cache includes both LibreNMS device data AND NetBox reference data used in the import table:
+
+**From LibreNMS:**
+- Device lists matching your search filters
+- Device details (hostname, sysName, location, hardware, etc.)
+- Virtual chassis detection results
+
+**From NetBox:**
+- Available device roles (for the role dropdown in each row)
+- Available VM clusters (for VM imports)
+- Available racks for each site (filtered by the device's matched site)
+
+This means if you add a new role, create a new rack, or add a new cluster in NetBox, those changes won't appear in the import table dropdowns until you clear the cache or wait for it to expire (5 minutes).
+
+### Controlling Cache
+
+The search form includes a "Clear cache before search" checkbox:
+
+| Setting | Behavior |
+|---------|----------|
+| Unchecked (default) | Uses cached data if available. Fastest results. |
+| Checked | Forces fresh data retrieval from both LibreNMS and NetBox. |
+
+**When to clear cache:**
+- After adding or updating devices in LibreNMS
+- After adding new roles, racks, or clusters in NetBox that should appear in import dropdowns
+- When troubleshooting import issues
+- When you need to verify current state
+
+**When to keep cache enabled:**
+- Normal operations and when refining search filters
+- When repeatedly working with the same set of devices
+- When NetBox reference data hasn't changed
+
+### Active Cached Searches
+
+The import page displays all your recent searches at the top, showing which filter combinations, that are still found in the cache. Each cached search shows the filters used, device count, and time remaining before expiration.
+
+Click any cached search to instantly reload those results without re-running filters or Virtual Chassis detection. This is particularly useful when switching between different filter combinations.
+
+Cached searches expire after 5 minutes of inactivity (or what you set as the cache timeout). The countdown timer shows how long each search remains available.
+
+The "Clear cache before search" option only clears the cache for the specific filter combination you're searching—other cached searches remain available.

docs/librenms_import/import_settings.md

@@ -0,0 +1,71 @@
+# Import Settings
+
+Configure how devices are named and what data is imported from LibreNMS to NetBox.
+
+## Setting Defaults
+
+To configure global defaults for all imports:
+
+1. Navigate to **Plugins → LibreNMS Plugin → Settings**
+2. Click **Plugin Settings**
+3. Configure Use sysName and Strip Domain to your preferred defaults
+4. Save changes
+
+These defaults apply to all future imports unless overridden during the import process.
+
+## User Preferences and Defaults
+
+The plugin uses a two-tier preference system for the **Use sysName** and **Strip Domain** toggles:
+
+1. **Plugin defaults** (set by admins on the Settings page) apply to all users who have not yet changed their own toggle settings.
+2. **Per-user preferences** are saved automatically when a user changes a toggle on the import page. Once saved, the user's preference takes priority over the plugin default.
+
+**Important notes:**
+
+- Changing the plugin defaults does **not** override existing user preferences. Users who have previously changed a toggle keep their personal setting.
+- When an admin saves import settings, only the admin's own preferences are updated to match the new defaults. Other users are unaffected.
+- There is no "reset to defaults" for individual users. To revert to the plugin default, a user simply needs to toggle the setting to match.
+
+## Device Naming Options
+
+The plugin provides two settings that control how device names are created in NetBox. Both are configured in Plugin Settings under **Plugins → LibreNMS Plugin → Settings → Plugin Settings** and can be overridden on the LibreNMS import page.
+
+### Use sysName
+
+Controls which field from LibreNMS becomes the device name in NetBox.
+
+- **Enabled** (default): Uses the SNMP sysName, falling back to LibreNMS hostname if sysName is not available
+- **Disabled**: Uses the LibreNMS hostname field
+
+### Strip Domain
+
+Removes domain suffixes from device names to create shorter, cleaner names.
+
+- **Enabled**: Removes domain suffixes (e.g., "router.example.com" becomes "router"). IP addresses are preserved without modification
+- **Disabled**: Keeps the full name as-is
+
+### Naming Examples
+
+```
+LibreNMS sysName: router-core-01.example.com
+LibreNMS hostname: 10.0.0.1
+
+Use sysName + Strip domain → "router-core-01"
+Use sysName + Keep domain → "router-core-01.example.com"
+Use hostname + Strip domain → "10.0.0.1" (IP preserved)
+Use hostname + Keep domain → "10.0.0.1"
+```
+
+If neither sysName nor hostname exists, the plugin generates a name as `device-{librenms_id}`.
+
+
+
+## Per-Import Overrides
+
+On the import page, the **Use sysName** and **Strip Domain** toggles are pre-populated from your saved preference (or the plugin default if you haven't set one). Changing a toggle immediately saves your preference for next time and applies to the current import.
+
+This allows you to:
+
+- Import some devices with sysName and others with hostname
+- Apply domain stripping selectively based on device type or location
+- Test different naming conventions — your last choice is remembered automatically

docs/librenms_import/overview.md

@@ -0,0 +1,71 @@
+# Device Import Overview
+
+The Device Import feature allows you to discover and import devices from LibreNMS into NetBox. This streamlines the process of populating NetBox with devices that are already monitored in LibreNMS, while giving you full control over how devices are imported.
+
+
+The import page should be clear and intuitive to use, but this overview provides additional context and details.
+
+## How It Works
+
+The import workflow consists of three main steps:
+
+1. **[Search & Filter](search.md)** - Find devices in LibreNMS using flexible filter criteria
+2. **[Review & Validate](validation.md)** - Validate import readiness and configure missing NetBox objects
+3. **[Import](import_settings.md)** - Configure import settings and create devices in NetBox
+
+The plugin validates all required NetBox objects (Site, Device Type, Device Role) before allowing import.
+
+## Key Features
+
+**Flexible Filtering**
+: Search by location, type, operating system, hostname, system name, or hardware model. Combine filters for precise device selection.
+
+**Smart Validation**
+: Automatic matching for Sites, Device Types, and Platforms based on LibreNMS data. Clear indicators for what's missing.
+
+**Device or VM**
+: Import as physical Devices (requires Site, Device Type, Role) or Virtual Machines (requires Cluster).
+
+**Virtual Chassis Support**
+: Automatic detection and creation of Virtual Chassis objects for stackable switches.
+
+**Background Processing**
+: Large device sets can be processed using NetBox background jobs with progress tracking and cancellation.
+
+## Accessing the Feature
+
+Navigate to the import interface through the NetBox menu:
+
+**Plugins → LibreNMS Plugin → Import → LibreNMS Import**
+
+This opens the device import page where you can search for and import devices from your LibreNMS instance.
+
+## What Gets Created
+
+When a device is imported, the plugin creates:
+
+**Device or VirtualMachine Object**
+: With all validated attributes (name, site, device type, role, platform, serial, rack, etc.). Note that rack assignment places the device in the rack without setting a specific rack unit (U) position—devices appear in the "Non racked" section and require manual U assignment.
+
+**LibreNMS ID Custom Field**
+: Automatically set to link the NetBox object to the LibreNMS device. This enables all other plugin features (interface sync, cable sync, etc.)
+
+**Virtual Chassis** (if detected)
+: For stackable devices, creates the Virtual Chassis object and assigns member positions based on detected inventory data.
+
+After import, devices appear in NetBox with a comment indicating they were imported by the plugin, including the import timestamp.
+
+## Multi-Server Support
+
+If your NetBox installation is configured with multiple LibreNMS servers, the import feature automatically uses the currently selected server from Plugin Settings.
+
+All imported devices are linked to the server used during import, allowing you to maintain devices from multiple LibreNMS instances in a single NetBox installation.
+
+## Next Steps
+
+Explore each step of the import workflow:
+
+- [Search for Devices](search.md) - Learn about filters, matching rules, and search options
+- [Validation & Configuration](validation.md) - Understand validation status and resolve issues
+- [Import Settings](import_settings.md) - Configure device naming and import options
+- [Background Jobs & Caching](background_jobs.md) - Job processing and performance optimization

docs/librenms_import/search.md

@@ -0,0 +1,98 @@
+The import feature requires at least one filter to search for devices. This prevents accidentally loading thousands of devices and helps you work with focused device sets.
+
+## Available Filters
+
+LibreNMS Location
+: Exact match by LibreNMS location ID. The dropdown shows all locations from your LibreNMS instance with their names and IDs.
+
+LibreNMS Type
+: Exact match by device type (network, server, storage, wireless, firewall, power, appliance, printer, loadbalancer, other).
+
+Operating System
+: Partial match by OS name. For example, "ios" matches "cisco-ios", "ios-xe", "cisco-ios-xr".
+
+LibreNMS Hostname
+: Partial match by the hostname or IP address used to add the device to LibreNMS.
+
+LibreNMS System Name
+: When used alone, performs an exact match on the SNMP sysName. When combined with other filters, performs a partial match.
+
+Hardware
+: Partial match by LibreNMS hardware model. For example, "C9300" matches devices with hardware like "Cisco C9300-48P".
+
+## Additional Search Options
+
+Include Disabled Devices
+: When checked, includes devices marked as disabled in LibreNMS. By default, only active devices are shown.
+
+Include Virtual Chassis Detection
+: When checked, analyzes device inventory to detect stackable switches and chassis. This adds processing time but provides helpful information about multi-member devices. See [Virtual Chassis](../usage_tips/virtual_chassis.md) for details.
+
+Clear cache before search
+: Forces the plugin to fetch fresh data from LibreNMS instead of using cached results. LibreNMS data is normally cached for 5 minutes to improve performance.
+
+Exclude Existing Devices
+: When checked, hides devices that already exist in NetBox. By default, all devices are shown including those already imported.
+
+## Filter Matching Rules
+
+Understanding how filters work helps you get the right results:
+
+Exact Match Filters
+: Location, Type, and OS (when used alone) must match exactly as shown in LibreNMS.
+
+Partial Match Filters
+: Hostname, OS (with other filters), and System Name (with other filters) find devices containing your search text.
+
+Multiple Filters
+: All filters must match for a device to appear in results. Start with Location or Type to narrow results, then refine with additional filters.
+
+### Filter Examples
+
+**Find all network devices in New York**
+```
+Location: New York
+Type: network
+```
+
+**Find Cisco devices**
+```
+Type: network
+OS: ios
+```
+
+**Find specific hardware model at New York**
+```
+Location: New York
+Hardware: C9300
+Type: network
+```
+
+**Find a specific device by name**
+```
+System Name: router-core-01.example.com
+```
+
+**Find devices with "F" in hostname at New York with device type firewall**
+```
+Hostname: F
+Location: New York
+Type: firewall
+```
+
+## Search Options
+
+Run as background job
+: Enabled by default. Runs searches asynchronously, allowing you to track progress and cancel operations. Recommended for most use cases, especially with Virtual Chassis detection or large device sets. See [Background Jobs & Caching](background_jobs.md) for details.
+
+Clear cache before search
+: Forces fresh data from LibreNMS instead of using cached results. LibreNMS data is normally cached for 5 minutes to improve performance. See [Background Jobs & Caching](background_jobs.md) for caching details.
+
+## Saved Cached Searches
+The import page displays all your recent searches at the top, showing which filter combinations, that are still found in the cache. Each cached search shows the filters used, device count, and time remaining before expiration.  Click any cached search to instantly reload those results without re-running filters. This is particularly useful when switching between different filter combinations.
+
+## Next Steps
+
+After searching, proceed to:
+- [Validation & Configuration](validation.md) - Review and configure devices for import
+- [Background Jobs & Caching](background_jobs.md) - Understand job processing and performance optimization

docs/librenms_import/validation.md

@@ -0,0 +1,51 @@
+# Validation & Configuration
+
+After searching, the import table displays devices with action buttons that reflect their validation status.
+
+## Validation States
+
+Import Button (Green)
+: Device is ready to import. All required fields are matched or configured.
+
+Disabled Import Button + Details Button (Gray/Red)
+: Device has missing required fields. Click Details to configure.
+
+Link to Existing Device
+: Device already exists in NetBox. Link navigates to the existing device.
+
+## Required Fields
+
+NetBox requires three fields before importing a device: **Site**, **Device Type**, and **Device Role**. The plugin attempts to match Site and Device Type automatically by comparing LibreNMS data to existing NetBox objects. Device Role must always be selected manually.
+
+Click the validation details button to review what's missing and select values from the dropdowns. The validation status updates immediately.
+
+### Import as Device
+
+- **Site** (required) - Auto-matched from LibreNMS location
+- **Device Type** (required) - Auto-matched from LibreNMS hardware string
+- **Device Role** (required) - Must be selected manually
+- **Platform** (optional) - Auto-matched from LibreNMS OS
+- **Rack** (optional) - Available if Site has racks
+
+### Import as Virtual Machine
+
+- **Cluster** (required) - Must be selected manually
+- **Platform** (optional) - Auto-matched from LibreNMS OS
+
+## Virtual Chassis Detection
+
+When Virtual Chassis Detection is enabled during search, the validation details show detected stack members with their positions, serials, and suggested names. The plugin automatically creates the Virtual Chassis object during import. See [Virtual Chassis](../usage_tips/virtual_chassis.md) for details.
+
+## Duplicate Detection
+
+The plugin checks for existing devices using:
+
+1. **LibreNMS ID custom field** (most reliable) - If set, device is marked "Already Exists"
+2. **Hostname match** - Exact name match against Devices and VMs
+3. **Primary IP address** (weak match) - If IP is already assigned to a device
+
+If both a VM and Device with the same hostname exist, the plugin cannot determine which to match and allows import. Set the `librenms_id` custom field on the correct existing object to clarify the match.
+
+## Next Steps
+
+- [Import Settings](import_settings.md) - Configure device naming and import options