BISSELL AEM File Upload Connector 🚀

A Flask-based web application that serves as a backend connector for uploading files to Adobe Experience Manager (AEM) with proper BISSELL naming conventions and folder structure mapping.

📋 Project Overview

This tool bridges the gap between BISSELL's production file naming system and AEM DAM requirements by:

• Analyzing production filenames using BISSELL naming conventions
• Renaming files for AEM DAM compliance
• Mapping files to correct AEM folder structures
• Uploading files to AEM staging areas for testing
• Preserving metadata removed during filename transformation

🎯 Current Status

✅ COMPLETED

• Flask Web Interface - Complete drag & drop upload system
• File Analysis Engine - Parses BISSELL production filenames
• Dual Filename Generation - Production vs DAM-ready names
• AEM Path Mapping - Generates correct folder structures
• Token Management - Interface for AEM access token configuration
• Metadata Preservation - Tracks removed filename components
• Upload Framework - Ready to send files to AEM staging

❌ CURRENT ISSUE

• AEM Access Token - New token lacks proper AEM Assets API scopes
• Token validation fails with 401 authentication errors
• Need to regenerate token with correct technical account credentials

🔄 NEXT STEPS

1. Generate Proper AEM Token using Adobe Developer Console
2. Test File Uploads to AEM staging environment
3. Validate Folder Creation and metadata preservation
4. Production Deployment configuration

🏗️ Architecture

Backend (Flask)

app.py                 # Main Flask application
├── File upload handling
├── Filename parsing (BISSELL conventions)
├── AEM path generation
├── Token validation
└── AEM API integration

Frontend (HTML/JavaScript)

templates/upload.html  # Web interface
├── Drag & drop file upload
├── Token configuration
├── File analysis preview
├── Upload progress tracking
└── Results display

Integration Logic

• Uses naming conventions from BISSELL_AEM-STRUCTURE-TOOL-3.0
• Implements exact filename parsing logic from reference tool
• Maps to AEM folder structures per BISSELL hierarchy

🚀 Getting Started

Prerequisites

• Python 3.7+
• Flask 2.3.0+
• Valid AEM access token with Assets API permissions

Installation

# Clone repository
git clone git@bitbucket.org:zlalani/bissell-aem-connector.git
cd bissell-aem-connector

# Activate virtual environment
source bissell-aem/bin/activate

# Install dependencies
pip install -r requirements.txt

# Start application
python app.py

Access Interface

Open your browser to: http://localhost:5001

🔧 Configuration

AEM Settings

# AEM Configuration (app.py)
AEM_HOST = "https://author-p61603-e493702.adobeaemcloud.com"
API_KEY = "1d5f3ab6483e467298fe6e09762cc322"
TESTING_BASE_PATH = "/content/dam/zz-dam-staging-area-unpublished-assets/oliver"
PRODUCTION_BASE_PATH = "/content/dam/bissell"

Working Credentials (Reference)

From previously working setup:

Technical ID: F3D11E45623CASF40A495E77@techacct.adobe.com
API Key: 1d5f3ab6483e467298fe6e09762cc322
Email: 815acefd-eb61-4828-9195-19ec3b737bfb@techacct.adobe.com

📁 File Structure

bissell-aem-connector/
├── 🔧 MAIN APPLICATION
│   ├── app.py                          # Flask backend application
│   ├── templates/upload.html           # Web interface
│   └── requirements.txt                # Python dependencies
│
├── 🧪 TESTING & VALIDATION  
│   ├── test_new_token.py               # Token validation script
│   ├── debug_new_token.py              # Token analysis tools
│   ├── test_with_working_config.py     # Working setup comparison
│   └── *.jpg                           # Sample test files
│
├── 📚 DOCUMENTATION
│   ├── README.md                       # This comprehensive guide
│   └── *.md                           # Additional documentation
│
└── 🗂️ RUNTIME
    ├── uploads/                        # Temporary file storage
    ├── bissell-aem/                    # Python virtual environment  
    └── *.log                           # Application logs

🎨 How It Works

1. File Upload & Analysis

Original: 12345678_dry_robot_p2990_crosswave-robot_imagery_hero_rgb_NCW_250x250banner1.jpg

2. Filename Transformation

DAM Ready: 250x250banner1_p2990_crosswave-robot_imagery_hero_rgb.jpg

3. Path Mapping

Production:  /content/dam/bissell/1-product-assets/dry/robot/p2990/crosswave-robot/imagery/hero/rgb/
Staging:     /content/dam/zz-dam-staging-area-unpublished-assets/oliver/1-product-assets/dry/robot/p2990/crosswave-robot/imagery/hero/rgb/
Final:       /content/dam/zz-dam-staging-area-unpublished-assets/oliver/1-product-assets/dry/robot/p2990/crosswave-robot/imagery/hero/rgb/250x250banner1_p2990_crosswave-robot_imagery_hero_rgb.jpg

4. Metadata Preservation

- Original Job Number: 12345678
- Removed from filename: dry robot  
- Colorway: NCW (No Colorway) - removed from DAM filename

🔑 Token Issue Resolution

Problem

The current token is a generic Adobe IMS token (dev-console-prod) missing AEM-specific scopes:

{
  "client_id": "dev-console-prod",
  "scope": "AdobeID,openid,read_organizations,additional_info.projectedProductContext,additional_info.roles"
}

Solution Required

Generate new token with proper technical account credentials:

1. Adobe Developer Console → https://console.adobe.io/
2. BISSELL Project → Find integration with Technical ID: F3D11E45623CASF40A495E77@techacct.adobe.com
3. Generate Token → JWT or OAuth Server-to-Server
4. Enable AEM Assets API → Ensure proper scopes are included

Test Token

Use these scripts to validate new tokens:

python test_with_working_config.py    # Compare against working setup
python debug_new_token.py             # Analyze token structure  
python test_new_token.py              # Basic validation

🧪 Testing

Manual Testing

1. Start application: python app.py
2. Open: http://localhost:5001
3. Configure valid AEM token
4. Upload file with BISSELL naming format
5. Review transformation and path mapping
6. Test upload to AEM staging

Sample Test Files

Use files with this naming pattern:

[JOB]_[category]_[type]_[gpd]_[product]_[assetA]_[assetB]_[color]_[colorway]_[descriptor].ext

Examples:
12345678_dry_robot_p2990_crosswave-robot_imagery_hero_rgb_NCW_250x250banner1.jpg  
98765432_wet_wash_p3084_crosswave_digital_banner_cmyk_red_hero1.png

📊 API Endpoints

Frontend Interface

• GET / - Main upload interface

Backend API

• POST /api/analyze - Analyze uploaded file and generate transformation preview
• POST /api/upload - Upload file to AEM with metadata
• POST /api/token - Configure and validate AEM access token
• GET /api/token/status - Check current token status

🔧 Development

Local Development

# Start development server
python app.py

# Debug mode enabled by default
# Access at http://localhost:5001

Environment Variables

# Optional: Set token via environment
export AEM_ACCESS_TOKEN="your_token_here"

Logging

Application logs are written to console and files for debugging upload issues.

🚀 Deployment Notes

Production Considerations

• Replace Flask dev server with production WSGI server (Gunicorn, uWSGI)
• Configure proper SSL/TLS certificates
• Set up reverse proxy (Nginx, Apache)
• Enable production logging and monitoring
• Configure proper file upload limits and security

Security

• Validate file types and sizes
• Sanitize uploaded filenames
• Secure token storage and transmission
• Implement authentication/authorization if needed

📋 Dependencies

Python Packages

Flask>=2.3.0           # Web framework
requests>=2.31.0       # HTTP client for AEM API
Werkzeug>=2.3.0        # Flask utilities
pathlib                # File path handling
mimetypes              # File type detection
urllib3>=1.26.0        # HTTP library

External Integration

• AEM Assets HTTP API - For file uploads and folder management
• BISSELL Naming Tool 3.0 - Reference for naming conventions and product data
• Adobe IMS - Identity Management Service for authentication

🤝 Contributing

Development Workflow

1. Create feature branch from main
2. Make changes and test thoroughly
3. Update documentation as needed
4. Submit pull request with detailed description

Code Standards

• Follow PEP 8 Python style guidelines
• Add docstrings for functions and classes
• Include error handling and logging
• Write tests for new functionality

📞 Support & Contact

Technical Issues

• Check logs for error details
• Validate AEM token permissions
• Test with sample files first
• Review Adobe Developer Console configuration

Project Maintainer

• Repository: https://bitbucket.org/zlalani/bissell-aem-connector
• Created: September 2025
• Version: 1.0.0

📈 Version History

Version 1.0.0 (Current - September 2025)

• ✅ Complete Flask web interface
• ✅ BISSELL filename parsing and transformation
• ✅ AEM folder path generation
• ✅ Token management system
• ✅ File upload framework
• ❌ Token authentication issues (needs resolution)

Previous Versions

• V0.x - Command-line tools and experimentation
• Reference - BISSELL AEM Structure Tool 3.0 integration

🎯 Roadmap

Immediate (Q4 2025)

• ✅ Resolve AEM token authentication
• ✅ Complete end-to-end upload testing
• ✅ Production deployment setup

Future Enhancements

• 📁 Batch file processing
• 🔄 Automated folder structure validation
• 📊 Upload progress tracking and resumption
• 🎨 Enhanced UI/UX improvements
• 📱 Mobile-responsive interface
• 🔐 Advanced authentication and authorization

---

🎯 Ready to use once AEM access token is properly configured!

Last Updated: September 15, 2025