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)

---

## Quick Start

### 1. Setup
```bash
cd Python-Version
./setup.sh
```

This will:
- Create virtual environment
- Install dependencies
- Create .env template
- Setup directory structure

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

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

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

Should show:
```
✓ DAM connection OK
✓ Box connection OK
✓ Database connection OK
```

### 4. Run Scripts

**A1→A2 Download (Polling):**
```bash
python scripts/a1_to_a2_download.py
```

**A2→A3 Upload (Webhook):**
```bash
python scripts/a2_to_a3_upload.py
```

---

## 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