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](API_DEVICE_FIELD_LOCK.md)
- **Plugin configuration:** See [PLUGINS_DEV_CONFIG.md](PLUGINS_DEV_CONFIG.md)
- **Admin guide:** See [DEVICE_MANAGEMENT.md](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.