NetAlertX/docs/QUICK_REFERENCE_FIELD_LOCK.md

Quick Reference Guide - Device Field Lock/Unlock System

One-Minute Overview

The device field lock/unlock system allows you to protect specific device fields from being automatically overwritten by scanning plugins. When you lock a field, NetAlertX remembers your choice and prevents plugins from changing that value until you unlock it.

Use case: You've manually corrected a device name or port number and want to keep it that way, even when plugins discover different values.

Tracked Fields (10 Total)

These are the ONLY fields that can be locked:

1. devMac - Device MAC address
2. devName - Device hostname/alias
3. devLastIP - Last known IP address
4. devVendor - Device manufacturer
5. devFQDN - Fully qualified domain name
6. devSSID - WiFi network name
7. devParentMAC - Parent/gateway MAC
8. devParentPort - Parent device port
9. devParentRelType - Relationship type (e.g., "gateway")
10. devVlan - VLAN identifier

Source Values Explained

Each locked field has a "source" indicator that shows you why the value is protected:

Indicator	Meaning	Can It Change?
🔒 LOCKED (red badge)	You locked this field	No, until you unlock it
✏️ USER (orange badge)	You edited this field	No, plugins can't overwrite
📡 NEWDEV (gray badge)	Default/unset value	Yes, plugins can update
📡 Plugin name (gray badge)	Last updated by a plugin (e.g., UNIFIAPI)	Yes, plugins can update

How to Use

Lock a Field (Prevent Plugin Changes)

1. Navigate to Device Details for the device
2. Find the field you want to protect (e.g., device name)
3. Click the lock button (🔒) next to the field
4. The button changes to unlock (🔓) and turns red
5. That field is now protected

Unlock a Field (Allow Plugin Updates)

1. Go to Device Details
2. Find the locked field (shows 🔓 in red)
3. Click the unlock button (🔓)
4. The button changes back to lock (🔒) and turns gray
5. Plugins can now update that field again

Common Scenarios

Scenario 1: You've Named Your Device and Want to Keep the Name

1. You manually edit device name to "Living Room Smart TV"
2. A scanning plugin later discovers it as "Unknown Device" or "DEVICE-ABC123"
3. Solution: Lock the device name field
4. Your custom name is preserved even after future scans

Scenario 2: You Lock a Field, But It Still Changes

This means the field source is USER or LOCKED (protected). Check:

• Is it showing the lock icon? (If yes, it's protected)
• Wait a moment—sometimes changes take a few seconds to display
• Try refreshing the page

Scenario 3: You Want to Let Plugins Update Again

1. Find the device with locked fields
2. Click the unlock button (🔓) next to each field
3. Refresh the page
4. Next time a plugin runs, it can update that field

What Happens When You Lock a Field

• ✅ Your custom value is kept
• ✅ Future plugin scans won't overwrite it
• ✅ You can still manually edit it anytime
• ✅ Lock persists across plugin runs
• ✅ Other users can see it's locked (red indicator)

What Happens When You Unlock a Field

• ✅ Plugins can update it again on next scan
• ✅ If a plugin has a new value, it will be applied
• ✅ You can lock it again anytime
• ✅ Your manual edits are still saved in the database

Error Messages & Solutions

Message	What It Means	What to Do
"Field cannot be locked"	You tried to lock a field that doesn't support locking	Only lock the 10 fields listed above
"Device not found"	The device MAC address doesn't exist	Verify the device hasn't been deleted
Lock button doesn't work	Network or permission issue	Refresh the page and try again
Unexpected field changed	Field might have been unlocked	Check if field shows unlock icon (🔓)

Quick Tips

• Lock names and IPs you manually corrected to keep them stable
• Leave discovery fields (vendor, FQDN) unlocked for automatic updates
• Use locks sparingly—they prevent automatic data enrichment
• Check the source indicator (colored badge) to understand field origin
• Lock buttons only appear for devices that are saved (not for new devices being created)

When to Lock vs. When NOT to Lock

✅ Good reasons to lock:

• You've customized the device name and it's correct
• You've set a static IP and it shouldn't change
• You've configured VLAN information
• You know the parent device and don't want it auto-corrected

❌ Bad reasons to lock:

• The value seems wrong—edit it first, then lock
• You want to prevent data from another source—use field lock, not to hide problems
• You're trying to force a value the system disagrees with

Troubleshooting

Lock button not appearing:

• Confirm the field is one of the 10 tracked fields (see list above)
• Confirm the device is already saved (new devices don't show lock buttons)
• Refresh the page

Lock button is there but click doesn't work:

• Check your internet connection
• Check you have permission to edit devices
• Look at browser console (F12 > Console tab) for error messages
• Try again in a few seconds

Field still changes after locking:

• Double-check the lock icon shows (red indicator)
• Reload the page—the change might be a display issue
• Check if you accidentally unlocked it
• Contact support if it persists

For More Information

• Technical details: See API_DEVICE_FIELD_LOCK.md
• Plugin configuration: See PLUGINS_DEV_CONFIG.md
• Admin guide: See DEVICE_MANAGEMENT.md

---

Quick Start: Find a device field you want to protect → Click the lock icon → That's it! The field won't change until you unlock it.