diff --git a/README.md b/README.md index 6ecf736..37cf0e9 100644 --- a/README.md +++ b/README.md @@ -1,74 +1,42 @@ # OMG Static - H&M Agent -A comprehensive web-based tool for managing H&M documents through the One2Edit API. This application provides automated image relinking, document exporting, and image status checking capabilities. +A web-based tool for managing H&M documents through the One2Edit API. Provides automated image relinking, document exporting, and image status checking. -## 🚀 Features +## Features -### 1. **Relink Images** +### Relink Images Automatically relinks missing images in H&M documents using intelligent matching algorithms. -#### **Link by File** -- Process a single document by Document ID -- Extracts image filenames from `absolutePath` for accurate matching -- Handles H&M-specific logos with hardcoded asset identifiers -- Generic image matching through campaign folder structure +- **Link by File** — Process a single document by Document ID +- **Link by Folder** — Batch process all documents in a folder -#### **Link by Folder** -- Process multiple documents in a folder by Folder ID -- Batch processing with individual session management per document -- Comprehensive reporting across all documents +### Image Status +Check the link status of all images across multiple documents in a folder. Shows per-document and folder-level summaries of linked vs missing images. -### 2. **Image Status** -Check the link status of all images across multiple documents in a folder. - -- **Document Overview:** Shows total, linked, and missing images per document -- **Folder Summary:** Aggregated statistics across all documents -- **Link State Analysis:** Categorizes images by their current link state - -### 3. **Export INDD** +### Export INDD Bulk export InDesign documents from a folder to assets. -- Processes all documents in a specified folder -- Exports to Asset Project ID 7 with folder identifier `68cc028b0e3f4a98ed07db6c` -- Maintains original document names for assets +### Export PDF +Bulk export PDF documents with R100 filtering and name transformation (R100 → RATIOS). -### 4. **Export PDF** -Bulk export PDF documents with specific filtering and naming conventions. +### Ratio Check +Validate image aspect ratios against expected values. -- **R100 Filtering:** Only processes documents containing "R100" in the name -- **Name Transformation:** Replaces "R100" with "RATIOS" in exported asset names -- **Quality Settings:** Uses preset ID 6 with registration marks -- Exports to Asset Project ID 10 with folder identifier `686fac43868b7ed49b028bee` +## Architecture -### 5. **Ratio Check** -Validate image aspect ratios against expected values (placeholder functionality). +### Session Management +All document operations use One2Edit session management: +1. `document.session.open` — Create edit session +2. Perform operations with session ID +3. `document.session.save` — Commit changes +4. `document.session.close` — Release session -## 🏗️ Architecture +### Image Matching +1. **H&M sRGB Logo** → Hardcoded asset `68626a50da85f5bf560161ed` +2. **H&M CMYK Logo** → Hardcoded asset `68626a4a0eb4d535b80789cb` +3. **Generic Images** — Searches campaign folder structure (RGB/CMYK) with fuzzy matching -### **Session Management** -All document operations use proper One2Edit session management: - -1. **Open Session:** `document.session.open` - Creates edit session -2. **Perform Operations:** Image relinking with session ID -3. **Save Session:** `document.session.save` - Commits changes -4. **Close Session:** `document.session.close` - Releases session - -### **Image Matching Algorithm** - -#### **Filename Extraction** -- Extracts actual filenames from `absolutePath` instead of unreliable `` tags -- Handles URL encoding/decoding automatically -- Splits paths on '/' and takes the last segment - -#### **Matching Hierarchy** -1. **H&M sRGB Logo:** Hardcoded to asset `68626a50da85f5bf560161ed` -2. **H&M CMYK Logo:** Hardcoded to asset `68626a4a0eb4d535b80789cb` -3. **Generic Images:** - - Determines target folder (RGB/CMYK) based on filename patterns - - Searches campaign-specific asset structure - - Performs fuzzy matching with and without file extensions - -#### **Campaign Folder Structure** +### Campaign Folder Structure ``` Assets/ └── [Campaign Folder Name]/ @@ -77,216 +45,48 @@ Assets/ └── CMYK/ ``` -### **Error Handling & Resilience** -- **Individual Failures:** Don't stop batch operations -- **Session Cleanup:** Ensures sessions are properly closed even on errors -- **Comprehensive Logging:** Debug information for troubleshooting -- **Timeout Prevention:** 5-second delays between relink operations, 2-second delays between documents +## Usage -## 📋 API Reference - -### **Core APIs Used** - -| API Call | Purpose | Parameters | -|----------|---------|------------| -| `document.list` | Get documents in folder | `folderId`, `include=id` | -| `document.info` | Get document details | `id`, `include=folderId` | -| `document.folder.info` | Get folder information | `id`, `include=name` | -| `document.session.open` | Start edit session | `documentId` | -| `document.session.save` | Save changes | `documentId`, `editSession` | -| `document.session.close` | End session | `documentId`, `editSession` | -| `document.image.list` | Get image information | `id`, `include=linkState\|absolutePath` | -| `document.image.relink` | Relink image | `id`, `frameId`, `assetIdentifier`, `editSession` | -| `document.export.indd` | Export to InDesign | `id`, `assetProjectId`, `assetFolderIdentifier` | -| `document.export.pdf` | Export to PDF | `id`, `presetId`, `assetProjectId` | -| `asset.list` | Browse asset library | `projectId`, `folderIdentifier` | - -### **Authentication** -- **Domain:** `local` -- **Username:** `pauljohns@oliver.agency` -- **Password:** `J4ckel-4!` -- **Client ID:** `6` - -### **Asset Configuration** -- **Project ID 7:** InDesign exports and image assets -- **Project ID 10:** PDF exports -- **InDesign Folder:** `68cc028b0e3f4a98ed07db6c` -- **PDF Folder:** `686fac43868b7ed49b028bee` - -## 🎯 Usage Instructions - -### **Getting Started** 1. Open `index.html` in a web browser 2. Select an action from the dropdown 3. Fill in the required parameters 4. Click "Submit" to execute -### **Action Parameters** +### Action Parameters -#### **Relink Images** -- **Link Method:** Choose "Link by File" or "Link by Folder" -- **Document ID:** (Link by File) Single document to process -- **Folder ID:** (Link by Folder) Process all documents in folder +| Action | Parameters | +|--------|-----------| +| Relink Images | Link method (File/Folder), Document ID or Folder ID | +| Image Status | Folder ID | +| Export INDD | Folder ID | +| Export PDF | Folder ID | +| Ratio Check | Input Path, Expected Ratio, Tolerance | -#### **Image Status** -- **Folder ID:** Folder to check image status for all documents +## Configuration -#### **Export INDD** -- **Folder ID:** Folder containing documents to export +API credentials and asset configuration are loaded from `config.php` via AJAX at runtime. -#### **Export PDF** -- **Folder ID:** Folder containing R100 documents to export - -#### **Ratio Check** -- **Input Path:** Path to check ratios -- **Expected Ratio:** Target aspect ratio (e.g., "16:9") -- **Tolerance (%):** Acceptable variance percentage -- **Generate Report:** Whether to create a report - -### **Reading Results** -- **Progress Updates:** Real-time status during operations -- **Debug Logging:** Click "Show Debug Log" for detailed API information -- **Comprehensive Reports:** Final summaries with per-document breakdowns - -## 🔧 Configuration - -### **Image Processing Rules** - -#### **CMYK Detection** -Files ending with `39L_TAC330.tif` are automatically processed through the CMYK asset folder. - -#### **RGB Default** -All other images default to the RGB asset folder unless specifically detected as CMYK. - -#### **H&M Logo Handling** -- `H&M-logo_sRGB.ai` → Asset `68626a50da85f5bf560161ed` -- `H&M-logo_CMYK_coated.eps` → Asset `68626a4a0eb4d535b80789cb` - -### **Performance Settings** -- **Relink Delay:** 5 seconds between image relink operations -- **Document Delay:** 2 seconds between document processing +### Performance Settings +- **Relink Delay:** 5s between image relink operations +- **Document Delay:** 2s between document processing - **Status Check Delay:** 500ms between document status checks -## 🐛 Troubleshooting - -### **Common Issues** - -#### **"allUnlinkedImages is not defined"** -This was resolved by updating the code to only process MISSING images instead of all unlinked images. - -#### **Images showing as linked = 0** -Fixed by correcting linkState comparison from `'Normal'` to `'NORMAL'` (case sensitivity). - -#### **Timeout Errors** -Resolved by implementing proper session management and adding delays between operations. - -#### **Incorrect Image Names** -Fixed by extracting filenames from `absolutePath` instead of unreliable `` XML tags. - -### **Debug Information** -Enable debug logging to see: -- API request/response details -- Image matching logic -- Session management steps -- Error details and stack traces - -### **Session Management Issues** -If sessions are left open: -1. Operations may timeout -2. Subsequent operations may fail -3. Check debug log for session IDs -4. Sessions auto-expire after a period - -## 📊 Reporting - -### **Relink Reports** -``` -Relink Complete! - -Total Images: 25 -Missing Images: 8 -Successfully Relinked: 7 -Failed: 1 -``` - -### **Image Status Reports** -``` -Image Status Check Complete! - -Total Documents Checked: 5 -Successful Checks: 5 -Failed Checks: 0 - -Overall Totals: -- Total Images: 127 -- Linked Images (Normal): 119 -- Missing Images: 8 - -Document Details: -Document 2518: 15 linked, 2 missing (17 total) -Document 2519: 22 linked, 0 missing (22 total) -... -``` - -### **Export Reports** -``` -Export Complete! - -Total Documents: 12 -Successful: 12 -Failed: 0 -``` - -## 🔐 Security Considerations - -- **Credentials:** Hardcoded in application (consider environment variables for production) -- **CORS:** Requires proper server configuration for cross-origin requests -- **Rate Limiting:** Built-in delays prevent API abuse -- **Session Management:** Proper cleanup prevents resource leaks - -## 🚀 Future Enhancements - -### **Potential Improvements** -- **Environment Configuration:** Move credentials to config files -- **Bulk Operations UI:** Progress bars and cancel functionality -- **Asset Preview:** Show thumbnails before relinking -- **Advanced Filtering:** More sophisticated image matching rules -- **Export Presets:** Configurable export settings -- **Retry Logic:** Automatic retry for failed operations -- **Background Processing:** Queue-based operations for large batches - -### **API Extensions** -- **Batch Relink API:** Single API call for multiple images -- **Status Webhooks:** Real-time progress notifications -- **Asset Search API:** Better asset discovery and matching - -## 📁 File Structure +## File Structure ``` -Agent/ -├── index.html # Main application file -└── README.md # This documentation +├── index.html # Main application (single-page) +├── config.php # API credentials and asset configuration +├── .gitignore +└── README.md ``` -## 🤝 Contributing +## Troubleshooting -### **Code Style** -- **JavaScript:** ES6+ features with async/await -- **Error Handling:** Try-catch blocks with detailed logging -- **API Calls:** Consistent error checking and XML parsing -- **User Feedback:** Real-time progress updates - -### **Adding New Features** -1. Add action option to dropdown -2. Define parameters in `actionVariables` -3. Create handler function following existing patterns -4. Implement proper session management -5. Add comprehensive error handling -6. Update documentation +- **Enable debug logging** via "Show Debug Log" button for API request/response details +- **Session issues:** Sessions auto-expire; check debug log for session IDs if operations fail +- **CMYK detection:** Files ending with `39L_TAC330.tif` route to CMYK folder; all others default to RGB --- -**Version:** 1.0 -**Last Updated:** December 2024 -**Author:** Claude Code Assistant -**License:** Internal Use Only \ No newline at end of file +**Last Updated:** February 2025 +**License:** Internal Use Only