bissell-aem-connector/AEM_File_Upload_Process_Documentation.md

AEM DAM File Upload Process Documentation

Overview

This document explains how to automatically upload files with production naming conventions to the AEM DAM in their correct folder locations based on the file naming structure and BISSELL's AEM folder hierarchy.

BISSELL Naming Convention System

Production Filename Format

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

Example:

5791356_wet_wash_p3084_crosswave_imagery_hero_rgb_mambo-red.tif

DAM Filename Format (Renamed)

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

Example:

p3084_crosswave_imagery_hero_rgb_mambo-red.tif

AEM Folder Structure

Base Path

/content/dam/bissell/1-product-assets/

Folder Hierarchy

1-product-assets/
├── [product-category]/        # wet, dry, consumables, sanitaire, rug-doctor
│   ├── [product-type]/       # canister, upright, stick, robot, wash, etc.
│   │   ├── [gpd-number]/     # p2829, p3084, etc.
│   │   │   ├── [product-name]/   # crosswave, pet-hair-eraser, etc.
│   │   │   │   ├── [asset-type-a]/   # digital, imagery, logo, parts
│   │   │   │   │   ├── [asset-type-b]/   # hero, lifestyle, banner, a-plus
│   │   │   │   │   │   ├── [color-profile]/  # rgb, cmyk
│   │   │   │   │   │   │   └── [colorway]/   # mambo-red, electric-blue (NCW creates no folder)

Example Full Path

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

File Upload Process

1. Filename Analysis

The Python script will:

1. Parse production filename components using underscore delimiters
2. Extract OMG job number, product hierarchy, colorway, and custom descriptor
3. Validate filename format against expected structure
4. Handle special cases (NCW colorways, generic components)

2. Path Generation

Based on filename components:

1. Build folder path following AEM hierarchy
2. Handle NCW colorways (no colorway folder created)
3. Create missing folder structure if needed
4. Generate DAM filename by removing/reordering components

3. File Upload Steps

1. Authentication: Use Bearer token with provided API credentials
2. Path Creation: Create folder structure if it doesn't exist
3. File Rename: Generate DAM-compliant filename
4. Upload: Upload file to correct AEM DAM location
5. Metadata: Store removed components (job number, NCW, etc.) as metadata

Testing Location

For initial testing, files will be uploaded to:

https://author-p61603-e493702.adobeaemcloud.com/ui#/aem/assets.html/content/dam/zz-dam-staging-area-unpublished-assets/oliver

Python Script Functionality

Key Features

1. Filename Decoder: Parse production filenames into components
2. Path Generator: Build correct AEM folder paths
3. File Uploader: Handle AEM API authentication and upload
4. Metadata Handler: Store removed filename components as asset metadata
5. Error Handling: Validate files and handle upload failures
6. Batch Processing: Process multiple files in one operation

Component Mapping

• OMG Job Number: Moved to metadata, removed from DAM filename
• Product Category: Used for folder structure (dry/wet/etc)
• Product Type: Used for folder structure (canister/wash/etc)
• GPD Number: Kept in DAM filename and folder structure
• Product Name: Kept in DAM filename and folder structure
• Asset Types: Kept in DAM filename and folder structure
• Color Profile: Kept in DAM filename and folder structure
• Colorway:
  • Real colorways: Create folder and kept in filename
  • NCW: No folder created, removed from DAM filename
• Custom Descriptor: Moved to front of DAM filename

Special Handling

1. NCW Colorways: No colorway folder created, colorway removed from DAM filename
2. Custom Descriptors: Move to beginning of DAM filename
3. Generic Components: Handle consumables with generic GPD/product names
4. Missing Folders: Create folder structure dynamically
5. File Extensions: Preserve original file extensions

API Integration

Authentication

• API Key: 1d5f3ab6483e467298fe6e09762cc322
• Technical ID: F3D11E45623CASF40A495E77@techacct.adobe.com
• Endpoint: https://author-p61603-e493702.adobeaemcloud.com

Upload Endpoints

• Asset Upload: /api/assets/
• Folder Creation: /api/assets/
• Metadata Update: /api/assets/{path}.metadata.json

Workflow Implementation

Step 1: File Analysis

# Parse filename components
components = parse_filename(production_filename)
# Example: "5791356_wet_wash_p3084_crosswave_imagery_hero_rgb_mambo-red.tif"
# Returns: {
#   'omg_job': '5791356',
#   'category': 'wet',
#   'type': 'wash',
#   'gpd': 'p3084',
#   'product': 'crosswave',
#   'asset_a': 'imagery',
#   'asset_b': 'hero',
#   'color_profile': 'rgb',
#   'colorway': 'mambo-red',
#   'custom_descriptor': None
# }

Step 2: Path Generation

# Generate AEM folder path
folder_path = generate_folder_path(components)
# Returns: "/content/dam/bissell/1-product-assets/wet/wash/p3084/crosswave/imagery/hero/rgb/mambo-red/"

# Generate DAM filename
dam_filename = generate_dam_filename(components)
# Returns: "p3084_crosswave_imagery_hero_rgb_mambo-red.tif"

Step 3: Upload Execution

# Create folders if needed
create_folder_structure(folder_path)

# Upload file with new name
upload_file(file_path, folder_path + dam_filename)

# Update metadata with removed components
update_metadata(folder_path + dam_filename, {
    'omg_job_number': components['omg_job'],
    'original_filename': production_filename
})

Error Handling

Common Issues

1. Invalid Filename Format: Missing components or incorrect delimiters
2. Authentication Failures: Invalid or expired API tokens
3. Folder Creation Errors: Permission issues or invalid paths
4. Upload Failures: File size limits or network issues
5. Metadata Update Failures: Invalid metadata format

Recovery Strategies

1. Validation: Pre-validate all filenames before processing
2. Retry Logic: Implement exponential backoff for transient failures
3. Logging: Comprehensive logging for debugging and auditing
4. Rollback: Ability to undo uploads in case of errors
5. Progress Tracking: Track upload status for batch operations

Benefits

Automated Organization

• Files automatically placed in correct folder structure
• Consistent naming across all assets
• Metadata preserved for searchability

Reduced Manual Work

• No manual folder navigation needed
• Automatic filename standardization
• Bulk upload capabilities

Quality Assurance

• Validation ensures correct file structure
• Prevents misplaced assets
• Maintains naming convention compliance

Future Enhancements

Planned Features

1. Duplicate Detection: Check for existing files before upload
2. Version Control: Handle file versioning automatically
3. Approval Workflow: Integration with AEM approval processes
4. Batch Reporting: Generate upload reports and statistics
5. Integration: Connect with existing asset management tools