Oliver/creative-x-ferrero
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
No description
7 commits 1 branch 0 tags 176 KiB
Find a file
DJP 78e19ca82d Add error status handling and detailed error logging 
Changes:
- Detect 'error' status from API
- Mark upload as failed when error status received
- Display full error response for debugging
- Log error details to help diagnose issues
2026-01-09 14:50:36 -05:00
core Fix: Correct preflight payload structure 2026-01-09 14:46:41 -05:00
scripts Add error status handling and detailed error logging 2026-01-09 14:50:36 -05:00
utils Fix: Update preflight payload to match API requirements 2026-01-09 14:45:26 -05:00
.env.template Initial commit: CreativeX API integration for Ferrero assets 2026-01-09 14:33:00 -05:00
.gitignore Initial commit: CreativeX API integration for Ferrero assets 2026-01-09 14:33:00 -05:00
config.py Initial commit: CreativeX API integration for Ferrero assets 2026-01-09 14:33:00 -05:00
data.json Initial commit: CreativeX API integration for Ferrero assets 2026-01-09 14:33:00 -05:00
README.md Initial commit: CreativeX API integration for Ferrero assets 2026-01-09 14:33:00 -05:00
requirements.txt Update requirements.txt: Remove pandas/openpyxl for Python 3.14 compatibility 2026-01-09 14:34:56 -05:00

README.md

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! 🚀