# Attribute Mapper - Quick Setup Guide

## Installation Steps

1. **Activate the Plugin**
   - Go to WordPress Admin → Plugins
   - Find "Attribute Mapper"
   - Click "Activate"

2. **Access the Tool**
   - Navigate to: **WooCommerce → Attribute Mapper**

3. **Verify Requirements**
   - WooCommerce must be active
   - You need `manage_woocommerce` capability
   - Server must have `mysqldump` command (for backups)

## Quick Start

### Basic Usage Flow:

```
1. Add mapping row(s)
   ↓
2. Select Current Term → New Term (shown as "Attribute: Term (ID)")
   ↓
3. Click "Dry Run" to preview changes
   ↓
4. Review products & download CSV if needed
   ↓
5. Click "Execute Mapping" (creates backup automatically)
   ↓
6. Done! Backup saved to wp-content/attribute-mapper-backups/
   Variations regenerated with prices set to 0 if not already set
```

## Example Use Case

**Scenario**: You want to replace "Red" term with "Crimson" in the Color attribute

1. Add a row
2. Current Term: `Color: Red (123)`
3. New Term: `Color: Crimson (456)`
4. Dry Run → Shows 50 products affected
5. Execute → Updates all 50 products and regenerates variations with prices set to 0

## Important Features

✅ **Multiple mappings at once** - Map several terms in one operation  
✅ **Dry run preview** - See exactly what will change  
✅ **CSV export** - Download list of affected products  
✅ **Auto backup** - Full database backup before changes  
✅ **Variation handling** - Auto-regenerates variations for variable products  
✅ **Price setting** - Sets variation prices to 0 if not already set  
✅ **Cross-taxonomy** - Can map terms between different attributes  

## Backup Location

All backups are saved to:
```
wp-content/attribute-mapper-backups/backup-YYYY-MM-DD-HH-MM-SS.sql
```

## Rollback Instructions

If something goes wrong, restore the database:

```bash
# Via command line
mysql -u username -p database_name < /path/to/backup-YYYY-MM-DD-HH-MM-SS.sql

# Or via WP-CLI
wp db import /path/to/backup-YYYY-MM-DD-HH-MM-SS.sql
```

## Testing Checklist

Before using in production:

- [ ] Test on staging environment first
- [ ] Run dry run to verify affected products
- [ ] Download CSV for your records
- [ ] Verify backup file is created (check file size > 0)
- [ ] Test with small term first (1-2 products)
- [ ] Check variable product variations are regenerated correctly
- [ ] Verify variation prices are set to 0 if they were empty
- [ ] Verify old term is removed from products
- [ ] Confirm new term appears on products

## Troubleshooting

**Issue**: Can't see the menu  
**Fix**: Ensure WooCommerce is active and you have `manage_woocommerce` capability

**Issue**: Backup fails  
**Fix**: Check `mysqldump` is available: `which mysqldump`

**Issue**: No products found  
**Fix**: Verify term is assigned to products and is from a global attribute (WooCommerce → Products → Attributes)

**Issue**: Changes too slow  
**Fix**: Large catalogs (1000+ products) may take several minutes

## Support

For detailed documentation, see [README.md](README.md)