ferrero-opentext/Python-Version/README.md

# Ferrero Content Scaling - Python Automation

**Automated workflow for Content Scaling (A1→A2→A3)**

Compatible with Python 3.6+ (server) and Python 3.10+ (local development)

**Status:** ✅ Production Ready & Tested

---

## 📚 Documentation

- **DEPLOYMENT.md** - Complete production server deployment guide
- **PYTHON_AUTOMATION_PLAN.md** - Architecture and design
- **README.md** - This file (quick reference)

---

## Quick Start (Local Testing)

### 1. Setup
```bash
cd Python-Version

# Create virtual environment and install dependencies
./setup.sh
```

### 2. Configure
```bash
# Edit .env with your credentials
nano .env

# Verify configuration
nano config/config.yaml
```

**Important:**
- Set correct Box folders in .env:
  - `BOX_ROOT_FOLDER_A1_A2=348304357505` (master downloads)
  - `BOX_ROOT_FOLDER_A2_A3=348526703108` (agency uploads)
- Update webhook URL: Make.com or your endpoint
- Configure email recipients

### 3. Test Connections
```bash
source venv/bin/activate
python scripts/test_connection.py
```

Expected output:
```
✓ DAM connection OK
✓ Box connection OK
✓ Database connection OK
```

### 4. Test A1→A2 Script
```bash
python scripts/a1_to_a2_download.py
```

**What happens:**
- Searches for campaigns with status A1
- Processes FIRST campaign only
- Downloads all master assets from DAM
- Uploads to Box (folder: 348304357505)
- Creates folder: C000000078-Campaign_Name
- Stores in PostgreSQL with full metadata
- Updates status A1 → A2 (if all successful)
- Sends webhook to Make.com
- Sends email notification
- Exits

**If no A1 campaigns:**
```
No A1 campaigns found - exiting
```

---

## 🚀 Production Deployment

**See DEPLOYMENT.md for complete server deployment guide**

Quick steps:
1. Upload files to server
2. Run `./setup.sh`
3. Edit `.env` with production credentials
4. Test: `python scripts/test_connection.py`
5. Setup cron:
   ```bash
   */5 * * * * cd ~/ferrero-automation/Python-Version && venv/bin/python scripts/a1_to_a2_download.py >> logs/cron.log 2>&1
   ```

---

## Features

### A1→A2 Master Asset Downloader
- Polls DAM every 5 minutes for campaigns with status A1
- Downloads all master assets
- Uploads to Box with tracking IDs
- Stores complete metadata in PostgreSQL
- **Only updates status A1→A2 when ALL assets processed successfully**
- Sends webhook notification with campaign ID and number
- Email notifications on success/failure

### A2→A3 Upload Handler
- Receives webhooks from Box when files uploaded
- Parses V2 filenames
- Loads master metadata from database
- Extracts 27-28 MVP fields
- Updates fields from filename (Description, State, Language)
- Uploads to DAM with clean filename
- **Only updates status A2→A3 when ALL campaign assets uploaded**
- Sends webhook notification
- Email notifications

---

## Configuration

### Easy Field Updates
Edit `config/field_mappings.yaml`:
```yaml
mvp_fields:
  - FERRERO.FIELD.MKTG.ASSET TYPE
  - NEW.FIELD.ID.HERE  # Just add new field IDs!
```

### Environment Switching
```bash
# Staging
export ENV=staging

# Production
export ENV=production
```

### Change Webhook URL
```yaml
# config/config.yaml
webhooks:
  campaign_status_update:
    url: https://your-new-url.com/api  # Just change URL!
```

### Change Email Recipients
```yaml
# config/config.yaml
notifications:
  recipients:
    success:
      - newperson@ferrero.com  # Just add to list!
```

---

## Deployment

### Local Testing
```bash
source venv/bin/activate
python scripts/a1_to_a2_download.py
```

### Production (Cron)
```bash
# Add to crontab
crontab -e

# Run every 5 minutes
*/5 * * * * cd ~/ferrero-automation/Python-Version && venv/bin/python scripts/a1_to_a2_download.py >> logs/cron.log 2>&1
```

### Webhook Server (Background)
```bash
cd Python-Version
source venv/bin/activate
nohup python scripts/a2_to_a3_upload.py > logs/webhook.log 2>&1 &
echo $! > webhook.pid
```

---

## Monitoring

### Check Logs
```bash
tail -f logs/a1_to_a2.log
tail -f logs/a2_to_a3.log
tail -f logs/errors.log
```

### Check Database
```bash
psql -h localhost -p 5433 -U ferrero_user -d ferrero_tracking

# Check recent uploads
SELECT tracking_id, original_filename, created_at
FROM master_assets
ORDER BY created_at DESC LIMIT 10;
```

---

## Troubleshooting

### Connection Issues
```bash
python scripts/test_connection.py
```

### Invalid Filename
```bash
# Test filename parsing
python -c "from scripts.shared.filename_parser import FilenameParser; p=FilenameParser(); print(p.parse_filename('your_filename.mp4'))"
```

### Email Not Sending
- Check Mailgun API key in .env
- Check recipient emails in config
- Check logs: `grep -i mailgun logs/*.log`

### Webhook Not Receiving
- Check webhook server running: `ps aux | grep a2_to_a3`
- Check port accessible: `netstat -an | grep 5000`
- Check Box webhook configuration

---

## File Structure

```
Python-Version/
├── venv/                   # Virtual environment
├── scripts/
│   ├── a1_to_a2_download.py        # A1→A2 poller
│   ├── a2_to_a3_upload.py          # A2→A3 webhook
│   ├── test_connection.py          # Connection tester
│   └── shared/
│       ├── config_loader.py        # Config management
│       ├── dam_client.py           # DAM API
│       ├── box_client.py           # Box API
│       ├── database.py             # PostgreSQL
│       ├── notifier.py             # Email + webhooks
│       ├── filename_parser.py      # V2 naming parser
│       └── metadata_extractor_mvp.py
├── config/
│   ├── config.yaml                 # Main config
│   ├── field_mappings.yaml         # MVP fields (easy to edit!)
│   └── environments/
│       ├── staging.yaml
│       └── production.yaml
├── logs/
├── temp/downloads/
└── .env                            # Environment variables
```

---

## Support

For issues:
1. Check logs in `logs/` directory
2. Run `python scripts/test_connection.py`
3. Review configuration in `config/config.yaml`
4. Check `.env` has all required variables

---

**Version:** 1.0.0
**Compatible:** Python 3.6+ (server) and Python 3.10+ (local)
**Status:** Ready for testing