ferrero-opentext/README.md

# Ferrero OpenText Content Scaling Application

**Status:** ✅ **FULLY WORKING** - Complete workflow from campaign selection to asset download  
**Date:** September 29, 2025

## 🎯 Overview

A PHP-based web application for Ferrero's OpenText DAM system that automates the content scaling workflow:
1. **Campaign Discovery** - Find campaigns ready for content scaling
2. **Asset Identification** - Locate Master and Final asset folders  
3. **Asset Download** - Download source files for processing
4. **Metadata Extraction** - Access complete asset metadata

## 🚀 Quick Start

### **Prerequisites**
- MAMP or similar PHP server
- Internet connection to Ferrero OpenText API

### **Setup**
1. **Copy project** to MAMP htdocs directory
2. **Ensure** `Creds.txt` file is present with OAuth2 credentials
3. **Navigate to:** `http://localhost:8888/ferrero-opentext/clean_workflow.php`

### **No Configuration Required**
- ✅ OAuth2 authentication auto-configured
- ✅ API endpoints loaded from Postman collection
- ✅ Credentials loaded automatically

## 📋 Complete Workflow

### **Step 1: Campaign Selection**
1. **Click "Load '3 - Production & execution' Campaigns"**
2. **Select desired campaign** from the grid (look for campaigns with both Master and Final folders)
3. **Click "Proceed to Step 2"**

### **Step 2: Asset Discovery & Download**
1. **Click "Get Campaign Folders"** to discover folder structure
2. **Two possible outcomes**:
   - **✅ Multiple folders found** - Campaign has proper Master/Final structure
   - **⚠️ Only Final Assets folder** - Campaign needs different organization

3. **Explore folders** to find assets:
   - **"🔍 Explore All X Folders"** - Compare all folders side by side
   - **Individual folder exploration** - Examine specific folders

4. **Download assets**:
   - **📥 Download** - Individual file download
   - **📥 Download All X Files** - Bulk folder download
   - **📋 Metadata** - View complete asset metadata

## 🔧 Technical Details

### **Authentication**
- **OAuth2 Client Credentials Flow**
- **Client ID:** `otds-OLV`
- **Token URL:** `https://ppr.dam.ferrero.com/otdsws/oauth2/token`
- **Automatic token refresh** and expiration handling

### **API Endpoints Used**
```
# Campaign Discovery
GET /v6/search/text?load_type=metadata&search_config_id=18&search_condition_list=...

# Folder Structure
GET /v6/folders/{campaign_id}/children?load_type=metadata&metadata_to_return=INER_NAME_GENERIC&level_of_detail=slim

# Asset Listing  
GET /v6/folders/{folder_id}/children

# Asset Download
GET /v6/assets/{asset_id}/contents
```

### **File Organization**
```
downloads/
├── [folder_name]/          # Bulk downloads organized by folder
│   ├── asset1.jpg
│   └── asset2.jpg
└── individual_file.jpg     # Individual downloads
```

## 📊 Current Campaign Data

### **Available Campaigns**
- **12 campaigns** in "3 - Production & execution" stage
- **Brands:** KINDER SURPRISE, KINDER BUENO, KINDER CHOCOLATE, etc.
- **Markets:** DE (Germany), FR (France), GB (UK), DZ (Algeria)

### **Verified Working Campaign**
- **Name:** "LOCAL CAMPAIGN"
- **Campaign ID:** C000000212
- **Brand:** KINDER SOFTY/BUENO EGGS
- **Folder Structure:**
  ```
  LOCAL CAMPAIGN
  ├── 00. Master Assets (Empty - workflow organization)
  └── 01. Final Assets (Contains 2 JPEG source files)
  ```

### **Asset Metadata Available**
For each asset, the system provides:
- **📋 Basic Info:** Asset ID, filename, file type, size, creation dates
- **🖼️ Content Info:** Dimensions, checksums, encoding, content URLs
- **🏷️ Custom Fields:** Campaign data, brand info, project details
- **🔐 Permissions:** Download, edit, export rights
- **🎨 Renditions:** Thumbnails, previews, different sizes

## 🐍 Python Migration Ready

### **Documented API Patterns**
- **Authentication flow** with OAuth2 client credentials
- **Request/response structures** captured and tested
- **Asset download endpoints** verified and working
- **Metadata extraction** patterns established

### **Planned Python Script Structure**
```python
# Future implementation
python3 download-script.py --campaign C000000212
python3 download-script.py --campaign C000000212 --folder-type master
python3 download-script.py --list-campaigns --stage "3 - Production & execution"
```

### **Required Campaign Structure**
For automated workflow, campaigns should have:
- **Master Assets folder** with source files for processing
- **Final Assets folder** (empty) for processed outputs
- **Proper metadata** with campaign and brand information

## ⚠️ Current Limitations

### **Campaign Structure Variance**
- **Most campaigns** only have "01. Final Assets" folders
- **Source assets** currently located in Final Assets folders (naming inconsistent)
- **Need properly configured campaigns** with assets in Master Assets folders

### **Workflow Requirements**
For optimal automation, need campaigns where:
- **Source files** are in "00. Master Assets" folder
- **"01. Final Assets"** folder is empty/ready for processed outputs
- **Multiple asset types** for comprehensive testing

## 🔑 File Structure

### **Main Application**
```
├── clean_workflow.php      # ✅ Main working interface
├── Creds.txt              # OAuth2 credentials (auto-loaded)
├── Content Scaling Flow.postman_collection_Oliver(New).json
├── src/
│   ├── TestRunner.php      # API orchestration
│   ├── CampaignFormatter.php # Response parsing
│   ├── AssetDownloader.php # Asset download functionality
│   ├── MetadataExtractor.php # Metadata parsing and display
│   ├── OAuth2Handler.php   # Authentication
│   └── ApiClient.php       # HTTP client
├── downloads/             # Downloaded assets storage
└── logs/                  # Operation logs
```

### **Supporting Files**
```
├── workflow.php           # Alternative interface (more complex)
├── simple_test.php        # Single endpoint testing
├── index.php             # Full testing suite
└── PROJECT_STATUS.md     # Detailed project status
```

## 🎯 Usage Examples

### **Content Scaling Workflow**
1. **Campaign Selection:**
   - Load production campaigns
   - Identify campaigns with proper folder structure
   - Select campaign for processing

2. **Asset Discovery:**
   - Explore Master Assets folder for source files
   - Verify Final Assets folder for output destination
   - Review asset metadata and permissions

3. **Asset Download:**
   - Download individual source files for processing
   - Bulk download entire Master Assets folder
   - Organize files locally for content scaling operations

4. **Processing (External):**
   - Process downloaded assets (scaling, adaptation, localization)
   - Prepare processed files for upload

5. **Upload (Future):**
   - Upload processed assets to Final Assets folder
   - Update metadata as needed

## 🚀 MAMP Access

- **Main Interface:** `http://localhost:8888/ferrero-opentext/clean_workflow.php`
- **Authentication:** Automatic OAuth2 setup
- **Session Management:** Maintains workflow state
- **Reset:** Click "🔄 Reset Session" to start fresh

## 📝 Next Development Phase

### **Python Script Development**
- **Command-line interface** for automated workflow
- **Campaign-based processing** using documented API patterns
- **Bulk operations** for multiple campaigns
- **Integration ready** once properly structured campaigns are available

---

**Ready for production use with current campaign structure. Optimized for campaigns with proper Master/Final folder organization.**