BISSELL AEM DAM Naming Tool 3.0 🚀

A comprehensive file naming and digital asset management system for BISSELL's Adobe Experience Manager (AEM) workflow, generating standardized filenames and folder structures for product assets.

🎯 What This Tool Does

The BISSELL AEM DAM Naming Tool is a web-based application that:

• Generates Standardized Filenames - Creates consistent naming for BISSELL product assets
• Dual Output System - Produces both production filenames AND DAM-ready filenames
• Smart Folder Paths - Automatically generates proper AEM folder structure paths
• Product Hierarchy Navigation - Guided 8-step wizard through BISSELL's complete product catalog
• Metadata Preservation - Tracks information removed from DAM filenames for asset metadata
• Custom Descriptors - Supports additional descriptive text like "250x250banner1", "EcomAsset1"

🌟 Version 3.0 Key Features

MAJOR UPDATE: This version introduces DAM-specific filename generation and metadata handling:

• ✅ Dual Filename Generation - Creates both production and DAM-ready filenames
• ✅ Custom Descriptors - Support for free text like "250x250banner1", "300x300", "EcomAsset1"
• ✅ Smart DAM Renaming - Automatically reformats filenames for DAM upload
• ✅ Metadata Preservation - Tracks removed information (job numbers, NCW colorways)
• ✅ Enhanced Folder Logic - NCW colorways don't create unnecessary folders
• ✅ Streamlined Interface - Removed live preview for focused workflow

How It Works

1. User Input - Navigate through product categories, types, GPDs, and asset details
2. Custom Descriptors - Add optional descriptive text for asset variants
3. Dual Generation - Tool creates both production and DAM filenames automatically
4. Folder Path - Generates complete AEM folder structure path
5. Metadata Output - Shows preserved information for DAM asset properties

📦 Project Structure

BISSELL_AEM-STRUCTURE-TOOL-3.0/
├── 🔧 MAIN APPLICATION
│   ├── index.html                      # Version 3.0 web application (deployment ready)
│   └── bissell-product-data.json       # Product hierarchy data (auto-loaded)
│
├── 🔄 DATA MANAGEMENT
│   ├── excel-to-json-converter.py      # Converts Excel to JSON
│   ├── BISSELL_AEM_Folder_Master.xlsx  # Master Excel file (standardized name)
│   └── excel_env/                      # Python virtual environment
│
├── 📚 DOCUMENTATION
│   ├── README.md                       # This comprehensive guide
│   ├── AEM-DAM-NAMING-GUIDE.md        # Detailed naming conventions
│   └── CHANGE_MANAGEMENT_DOCUMENT.md   # Version history
│
└── 📜 LEGACY/BACKUP FILES  
    └── OLD/                            # Deprecated files and legacy versions

🚀 Quick Start Guide

For End Users (Using the Tool)

1. Open the Tool

   # Simply open in any modern web browser
   open index.html
   

2. Use the 8-Step Wizard

   • Step 1-2: Select product category and type
   • Step 3: Choose GPD number
   • Step 4: Select specific product
   • Step 5: Pick product color/variant
   • Step 6-8: Choose asset types and color profile
   • Step 9: Add custom descriptor (optional)

3. Get Results

   • Production Filename: For internal workflow and job tracking
   • DAM Filename: Clean filename ready for AEM upload
   • Folder Path: Complete AEM directory structure
   • Metadata: Information to preserve in DAM asset properties

For Administrators (Updating Data)

1. Update Product Data

   # Replace the master Excel file
   cp "new-hierarchy-file.xlsx" "BISSELL_AEM_Folder_Master.xlsx"
   
   # Activate Python environment
   source excel_env/bin/activate
   
   # Convert to JSON
   python excel-to-json-converter.py
   

2. Verify Changes

   • Open index.html in browser
   • Test new products/categories appear correctly
   • Verify folder paths generate properly

📊 Naming Convention Details

Dual Filename System

Version 3.0 generates TWO filenames for each asset:

Production Filename (Internal Workflow)

[OMG-JOB-NUMBER]_[category]_[type]_[gpd]_[product]_[assetA]_[assetB]_[colorProfile]_[colorway]_[customDescriptor].ext

DAM Filename (Upload Ready)

[customDescriptor]_[gpd]_[product]_[assetA]_[assetB]_[colorProfile]_[colorway].ext

Real Examples

Input:

• Job Number: 12345678
• Category: dry → robot
• GPD: p2990
• Product: crosswave-robot
• Asset: imagery → hero
• Color Profile: rgb
• Colorway: NCW (No Colorway)
• Custom Descriptor: 250x250banner1

Output:

• Production: 12345678_dry_robot_p2990_crosswave-robot_imagery_hero_rgb_NCW_250x250banner1.ext
• DAM: 250x250banner1_p2990_crosswave-robot_imagery_hero_rgb.ext
• Folder: /content/dam/bissell/1-product-assets/dry/robot/p2990/crosswave-robot/imagery/hero/rgb/
• Metadata: Job Number: 12345678, Original Categories: "dry robot", NCW Colorway (folder omitted)

Folder Structure Logic

With Regular Colorway:

/content/dam/bissell/1-product-assets/wet/wash/p3084/crosswave/imagery/hero/rgb/mambo-red/

With NCW (No Colorway):

/content/dam/bissell/1-product-assets/dry/robot/p2990/crosswave-robot/imagery/hero/rgb/

(Note: No "NCW" folder created)

🔄 Data Update Process

Understanding the System

• Excel File: BISSELL_AEM_Folder_Master.xlsx contains the complete product hierarchy
• JSON File: bissell-product-data.json is the processed data the web tool uses
• Converter: excel-to-json-converter.py transforms Excel → JSON

When to Update

• New products added to BISSELL catalog
• Product names or GPD numbers change
• New colorways or variants introduced
• Asset type categories modified

Step-by-Step Update Process

1. Receive New Excel Data

   # Replace the master file (keep standard name)
   cp "BISSELL-Updated-Hierarchy.xlsx" "BISSELL_AEM_Folder_Master.xlsx"
   

2. Activate Python Environment

   source excel_env/bin/activate
   

3. Convert Excel to JSON

   python excel-to-json-converter.py
   

4. Verify Conversion

   • Check console output for success message
   • Note number of products processed
   • Look for any error messages

5. Test the Tool

   • Open index.html
   • Navigate through product hierarchy
   • Verify new products appear
   • Test filename generation

6. Backup and Version Control

   git add .
   git commit -m "Update product hierarchy with new data"
   git push
   

🛠️ Technical Details

System Requirements

• Modern Web Browser (Chrome, Firefox, Safari, Edge)
• Python 3.7+ (for data updates)
• No server required - runs entirely in browser

Dependencies (Data Updates Only)

pip install pandas openpyxl

File Dependencies

The web tool requires both files in the same directory:

• index.html (the application)
• bissell-product-data.json (the data)

Browser Compatibility

• ✅ Chrome 80+
• ✅ Firefox 75+
• ✅ Safari 13+
• ✅ Edge 80+
• ❌ Internet Explorer (not supported)

🎨 User Interface Features

8-Step Wizard

1. Asset Category - Top-level classification (consumables, dry, wet, etc.)
2. Product Category - Subcategory (canister, robot, wash, etc.)
3. Product Type - Specific GPD numbers
4. Product Name - Individual product variants
5. Product Color/Size - Color options and sizes
6. Asset Type A - Primary asset classification (imagery, digital, print)
7. Asset Type B - Secondary classification (hero, banner, video)
8. Color Profile - RGB or CMYK

Additional Features

• Custom Descriptor Field - Free text for asset variants
• Copy Buttons - One-click copy for production, DAM, and folder paths
• Reset Function - Clear all selections and start over
• Help Documentation - Built-in guide with examples
• Responsive Design - Works on desktop, tablet, and mobile

🔍 Decoder Feature

The tool includes a filename decoder that can:

• Parse existing BISSELL filenames
• Extract individual components
• Show folder path structure
• Identify custom descriptors vs standard colorways
• Handle both V2.0 and V3.0 filename formats

📋 Custom Descriptor Guidelines

Allowed Characters

• Letters: a-z, A-Z
• Numbers: 0-9
• Hyphens: - (preferred separator)

Not Allowed

• Underscores: _ (conflicts with filename structure)
• Spaces: (use hyphens instead)
• Special Characters: @, #, $, %, etc.

Best Practices

• Descriptive: "250x250banner1", "hero-main", "lifestyle1"
• Concise: Keep under 20 characters when possible
• Consistent: Use similar patterns across campaigns
• Version-Aware: "v1", "v2updated", "final"

Examples

• ✅ "250x250banner1"
• ✅ "EcomAsset1"
• ✅ "hero-main"
• ✅ "lifestyle-shot"
• ✅ "amazonplus"
• ❌ "250x250_banner_1" (underscores)
• ❌ "Ecom Asset #1" (spaces, special chars)

🚀 Workflow Integration

Production Workflow

1. Asset Creation - Use production filename during design/photography
2. Job Tracking - Job numbers help link files to projects
3. Review Process - Descriptive elements aid in asset identification
4. File Organization - Consistent naming improves file management

DAM Upload Workflow

1. File Preparation - Rename files using DAM filename format
2. Folder Navigation - Use generated folder path in AEM
3. Metadata Entry - Apply preserved metadata to asset properties
4. Asset Tagging - Use component information for DAM tags

Team Communication

• Designers - Use production filename during creation
• Project Managers - Track assets via job numbers
• DAM Administrators - Use clean DAM filenames and folder paths
• Marketing Teams - Reference assets by GPD and descriptor

🔧 Troubleshooting

Common Issues

Tool won't load / shows errors

• Ensure both HTML and JSON files are in same directory
• Check browser console for error messages
• Try refreshing the page
• Verify JSON file is valid (not corrupted)

Missing products in dropdowns

• Check if JSON file is up to date
• Verify Excel conversion completed successfully
• Look for console errors during data loading

Filename generation errors

• Ensure all required fields are selected
• Check custom descriptor format (no underscores)
• Verify colorway selection is appropriate for product

Python conversion fails

• Activate virtual environment: source excel_env/bin/activate
• Check Excel file exists and has correct name
• Verify Python dependencies installed: pip install pandas openpyxl

Getting Help

• Check browser developer console for errors
• Review Excel file structure matches expected format
• Verify file permissions allow reading/writing
• Test with fresh browser session (clear cache)

📈 Version History

Version 3.0 (Current)

• Dual filename generation (Production + DAM)
• Custom descriptor support
• Enhanced metadata preservation
• NCW folder logic improvements
• Streamlined interface
• Standardized Excel filename (BISSELL_AEM_Folder_Master.xlsx)

Version 2.0 (Legacy)

• Single filename output
• 4 different naming conventions
• Live preview functionality
• Date-based Excel naming

Version 1.0 (Legacy)

• Basic filename generation
• Limited product hierarchy
• Manual data entry

🤝 Contributing

Updating Product Data

1. Maintain Excel structure with proper tier columns
2. Follow existing naming patterns for consistency
3. Test conversion after major changes
4. Update version control with descriptive commit messages

Reporting Issues

• Document steps to reproduce problems
• Include browser information and error messages
• Test with latest version before reporting
• Provide example inputs that cause issues

---

Version: 3.0
Last Updated: January 2025
Maintainer: BISSELL Creative Operations Team
Repository: git@bitbucket.org:zlalani/bissell-naming-tool.git

🎯 Quick Reference

Essential Files

• index.html - The web application (deployment ready)
• bissell-product-data.json - Product data (auto-loaded)
• BISSELL_AEM_Folder_Master.xlsx - Source Excel file

Key Commands

# Update product data
source excel_env/bin/activate
python excel-to-json-converter.py

# Open tool
open index.html

File Naming Pattern

Production: [job]_[category]_[type]_[gpd]_[product]_[asset]_[color]_[colorway]_[descriptor].ext
DAM: [descriptor]_[gpd]_[product]_[asset]_[color]_[colorway].ext