CreativeX API Integration for Ferrero Assets

Automated upload and testing of Ferrero-branded creative assets via the CreativeX Content API. This tool parses Ferrero filename conventions, uploads files to CreativeX for 24-hour processing, and retrieves analysis results.

Overview

This Python application automates the workflow of:

1. Parsing Ferrero filenames to extract metadata (Brand, Market, Channel)
2. Uploading creative assets (videos/images) to CreativeX API
3. Tracking upload status through 24-hour processing window
4. Retrieving analysis results and scores

Key Features:

• Robust filename parsing using Ferrero naming convention (NEW format)
• State persistence with resume capability
• Comprehensive error handling and retry logic
• Dry-run mode for validation before upload
• Batch upload support
• Continuous status polling

---

Table of Contents

1. Installation
2. Configuration
3. Ferrero Filename Format
4. Usage
5. Workflow
6. Examples
7. Troubleshooting
8. Project Structure

---

Installation

Prerequisites

• Python 3.8 or higher
• pip (Python package manager)
• Access to CreativeX API (staging environment)
• Access to Ferrero naming convention data.json

Step 1: Clone Repository

git clone git@bitbucket.org:zlalani/creative-x-ferrero.git
cd creative-x-ferrero

Step 2: Setup Virtual Environment

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
# On macOS/Linux:
source venv/bin/activate

# On Windows:
venv\Scripts\activate

Step 3: Install Dependencies

pip install -r requirements.txt

Step 4: Configure Environment

# Copy template
cp .env.template .env

# Edit .env file with your credentials
nano .env  # or use your preferred editor

Required environment variables in .env:

• CREATIVEX_ACCESS_TOKEN - Your CreativeX API token
• DATA_JSON_PATH - Path to Ferrero naming convention data.json

Step 5: Verify Setup

# Run validation (coming soon)
python validate_setup.py

---

Configuration

Environment Variables (.env)

# CreativeX API Configuration
CREATIVEX_API_BASE_URL=https://staging-api.creativex.com/api/v3
CREATIVEX_ACCESS_TOKEN=your_token_here

# Data Source
DATA_JSON_PATH=/path/to/Ferrero-naming-convention/backend/data.json

# API Settings
API_TIMEOUT=30
API_MAX_RETRIES=3

# Upload Settings
MAX_FILE_SIZE_MB=500
CHUNK_SIZE_MB=5

# Polling Settings
POLL_INTERVAL_MINUTES=30
MAX_WAIT_HOURS=48

# Logging
LOG_LEVEL=INFO

Supported File Formats

• Videos: .mp4, .mov
• Images: .jpg, .jpeg, .png

---

Ferrero Filename Format

NEW Format (Current)

[JOB]_[BRAND]_[SUBJECT]_[ASSET]_[DURATION]_[RATIO]_[SPOT]_[COUNTRY]_[LANGUAGE]_[SOCIAL]_[TRACKING]

Example: 1234567_RAF_ME-MOMENT_OLV_6S_1x1_REF_GL_it_IGF_pOiJ9s.mp4

Field Positions

Position	Field	Required	Format	Example
1	Job Number	Optional	7-10 digits	1234567
2	Brand Code	Required	2-5 chars	RAF (Raffaello)
3	Subject Title	Required	1-15 chars	ME-MOMENT
4	Asset Type	Required	3 chars	OLV (Online Video)
5	Duration	Optional	e.g., 6S, 30S	6S
6	Aspect Ratio	Required	e.g., 1x1, 16x9	1x1
7	Spot Version	Optional	MST or REF	REF
8	Country Code	Required	2 chars	GL (Global)
9	Language Code	Required	2-3 chars	it (Italian)
10	Social Media	Optional	3 chars	IGF (Instagram Feed)
11	Tracking ID	Optional	6 alphanumeric	pOiJ9s

Mapping to CreativeX Parameters

CreativeX Param	Source	Example
brand	Brand Code → Resolved Name	RAF → "RAFFAELLO"
market	Country Code → Resolved Name	GL → "GLOBAL"
channel	Social Media OR Asset Type	IGF → "IG - Feed" OR OLV
asset_id	Full filename with extension	1234567_RAF_ME-MOMENT_OLV_6S_1x1_REF_GL_it_IGF_pOiJ9s.mp4
name	Full filename with extension	Same as asset_id

---

Usage

Upload Script

Upload files to CreativeX for testing.

# Single file
python scripts/upload.py /path/to/file.mp4

# Multiple files
python scripts/upload.py /path/to/file1.mp4 /path/to/file2.jpg

# Directory (all supported files)
python scripts/upload.py --dir /path/to/videos/

# Dry run (validate only, no upload)
python scripts/upload.py --dry-run /path/to/file.mp4

# Skip already uploaded files
python scripts/upload.py --skip-existing /path/to/files/

Options:

• --dir PATH - Upload all supported files from directory
• --dry-run - Validate filenames and files without uploading
• --skip-existing - Skip files already in uploads_state.json

Check Status Script

Monitor upload progress and retrieve results.

# Check all processing uploads
python scripts/check_status.py

# Show summary only
python scripts/check_status.py --summary

# Check specific file
python scripts/check_status.py --file filename.mp4

# Continuous polling (every 30 min)
python scripts/check_status.py --poll --interval 30

Options:

• --summary - Show upload status summary
• --file FILENAME - Check specific file
• --poll - Continuously poll until complete
• --interval N - Polling interval in minutes (default: 30)

---

Workflow

Complete Workflow Diagram

┌──────────────────┐
│  Upload Script   │
└────────┬─────────┘
         │
         ├─► 1. Parse Filename (extract Brand, Market, Channel)
         │
         ├─► 2. Validate File (exists, format, size)
         │
         ├─► 3. Validate Metadata (all required fields present)
         │
         ├─► 4. GET /presigned_url (get S3 upload URL)
         │
         ├─► 5. Upload File to S3 (PUT request)
         │
         ├─► 6. POST /preflights (create preflight with metadata)
         │
         └─► 7. Save State (persist request_id, status)

┌──────────────────┐
│ Status Checker   │
└────────┬─────────┘
         │
         ├─► 1. Load State (read uploads_state.json)
         │
         ├─► 2. GET /preflights/{id} (check status)
         │
         ├─► 3. Update State (save current status)
         │
         └─► 4. Retrieve Results (when status = completed)

         ⏱️  Processing Time: Up to 24 hours

State Management

The tool tracks all uploads in data/uploads_state.json:

Status Values:

• pending - Not yet started
• uploading - Getting URL or uploading to S3
• preflight_created - Preflight created, awaiting processing
• processing - Being analyzed by CreativeX
• completed - Analysis complete, results available
• failed - Error occurred

Resume Capability: If the script crashes or is interrupted, it can resume from the saved state without re-uploading files.

---

Examples

Example 1: Test Single File

# Step 1: Validate filename (dry run)
python scripts/upload.py --dry-run 1234567_RAF_ME-MOMENT_OLV_6S_1x1_REF_GL_it_IGF_pOiJ9s.mp4

# Step 2: Upload
python scripts/upload.py 1234567_RAF_ME-MOMENT_OLV_6S_1x1_REF_GL_it_IGF_pOiJ9s.mp4

# Step 3: Check status immediately
python scripts/check_status.py --summary

# Step 4: Monitor continuously
python scripts/check_status.py --poll --interval 30

Example 2: Batch Upload

# Upload all videos from directory
python scripts/upload.py --dir /Users/dave/ferrero_assets/

# Check progress
python scripts/check_status.py --summary

# After 24 hours, check final results
python scripts/check_status.py

Example 3: Handle Errors

# Upload returns errors
python scripts/upload.py /path/to/files/*.mp4

# Check which failed
python scripts/check_status.py --summary

# Review logs
tail -f data/logs/creativex_*.log

---

Troubleshooting

Common Issues

1. Invalid Filename Format

Error: ValueError: Invalid filename format: too few components

Solution: Ensure filename follows Ferrero naming convention:

[JOB]_[BRAND]_[SUBJECT]_[ASSET]_[DURATION]_[RATIO]_[SPOT]_[COUNTRY]_[LANGUAGE]_[SOCIAL]_[TRACKING]

At minimum, must have:

[BRAND]_[SUBJECT]_[ASSET]_[RATIO]_[COUNTRY]_[LANGUAGE]

2. Unknown Brand Code

Error: ValueError: Invalid brand code: 'XYZ'. Did you mean: RAF, ROC, NUT?

Solution: Check data.json for valid brand codes. The error will suggest similar codes.

3. File Too Large

Error: File too large: 550.25MB (max: 500MB)

Solution: Compress or resize the file. Configure MAX_FILE_SIZE_MB in .env if needed.

4. API Connection Failed

Error: APIError: Connection error: ...

Solution:

• Check internet connection
• Verify API token in .env
• Confirm API base URL is correct
• Check firewall/proxy settings

5. Missing data.json

Error: FileNotFoundError: data.json not found at: ...

Solution:

cp /Users/daveporter/Python-Enviroments/Ferrero-naming-convention/backend/data.json ./data.json

Viewing Logs

Detailed logs are saved to data/logs/:

# View latest log
ls -lt data/logs/creativex_*.log | head -1 | xargs cat

# Follow log in real-time
tail -f data/logs/creativex_*.log

# Search for errors
grep "ERROR" data/logs/creativex_*.log

State File Issues

If data/uploads_state.json becomes corrupted:

# Backup is created automatically as uploads_state.json.backup
mv data/uploads_state.json data/uploads_state.json.old
# Tool will create new state file on next run

---

Project Structure

creative-x-ferrero/
├── config.py                    # Configuration loader
├── requirements.txt             # Python dependencies
├── .env                        # Environment variables (not in git)
├── .env.template               # Template for .env
├── data.json                   # Ferrero naming convention mappings
│
├── core/
│   ├── filename_parser.py      # Parse Ferrero filenames
│   ├── api_client.py           # CreativeX API client
│   ├── data_loader.py          # Load/query data.json
│   └── validators.py           # Pre-upload validation
│
├── utils/
│   ├── logger.py               # Logging configuration
│   ├── file_handler.py         # File utilities
│   └── state_manager.py        # JSON state persistence
│
├── scripts/
│   ├── upload.py               # Main upload script
│   └── check_status.py         # Status checking script
│
└── data/
    ├── uploads_state.json      # Persistent upload tracking
    ├── results/                # Downloaded results (future)
    └── logs/                   # Execution logs

---

API Reference

CreativeX API Endpoints Used

1. GET /presigned_url - Get S3 upload URL
2. POST /preflights - Create preflight request
3. GET /preflights/{id} - Check preflight status

Authentication

Token passed as query parameter:

GET https://staging-api.creativex.com/api/v3/presigned_url?access_token=XXX

---

Development

Running Tests

# Install test dependencies
pip install pytest pytest-mock responses

# Run tests
pytest tests/

# With coverage
pytest --cov=core --cov=utils tests/

Code Style

# Install formatting tools
pip install black flake8

# Format code
black .

# Lint code
flake8 core utils scripts

---

Support

For issues or questions:

• Check Troubleshooting section
• Review logs in data/logs/
• Contact: Dave Porter

---

Version History

• v1.0.0 (2026-01-09) - Initial release
  • Ferrero filename parsing (NEW format)
  • Upload to CreativeX API
  • Status checking and polling
  • State persistence with resume capability

---

License

© 2026 Ferrero. All rights reserved.

---

Quick Start Checklist

• Clone repository
• Create virtual environment
• Install dependencies (pip install -r requirements.txt)
• Copy and configure .env file
• Copy data.json from Ferrero naming project
• Test with dry run (python scripts/upload.py --dry-run test_file.mp4)
• Upload test file
• Monitor status (python scripts/check_status.py --summary)
• Review logs if issues occur

---

Ready to upload your first file?

source venv/bin/activate
python scripts/upload.py --dry-run /path/to/your/file.mp4
python scripts/upload.py /path/to/your/file.mp4
python scripts/check_status.py --summary

Good luck! 🚀