Add README

README.md

@@ -0,0 +1,61 @@
+# AMPP Folder Organizer
+
+IronPython 3.4 script for Grass Valley AMPP Framelight X Script Task brick. Automatically organizes ingested assets into nested virtual folders based on filename prefixes, using `--` as the path delimiter.
+
+## Overview
+
+This script runs as part of the FramelightX asset ingestion pipeline. It parses filenames with the format:
+
+```
+FolderName--SubFolder--Filename.ext
+```
+
+and creates the folder structure `FolderName/SubFolder/` in AMPP, linking the asset to the deepest folder.
+
+## Example
+
+| Filename | Result |
+|----------|--------|
+| `BMG--Videos--Clip1.mp4` | Creates `BMG/Videos/`, links asset there |
+| `NEWS--PKG--Story.mxf` | Creates `NEWS/PKG/`, links asset there |
+| `IMG--4709.jpg` | Creates `IMG/`, links asset there |
+| `NoPrefix.mp4` | Skipped (no `--` found) |
+
+## History
+
+- **v3.2** → v3.3: Fixed special character handling in folder names (apostrophes, ampersands, etc.) by properly URL-encoding the hierarchy lookup path.
+
+## Environment
+
+- **Runtime:** IronPython 3.4 on .NET 8
+- **Available Objects:** `httpClient` (ScriptHttpClient), `job` (ScsJob), `asset` (ScriptAsset), `logger` (ScriptLogger)
+- **HTTP Endpoint:** Relative paths to AMPP API (e.g., `api/v1/store/folder/folders`)
+
+## API Calls
+
+### Get or check folder existence
+```
+GET api/v1/store/folder/folders/hierarchy?path={encoded_path}
+```
+
+### Create folder
+```
+POST api/v1/store/folder/folders
+Body: {"name:text": "FolderName", "parentFolders:tags": ["parentFolderId"]}
+```
+
+### Link asset to folder
+```
+POST api/v1/store/folder/references
+Body: {"folder:id": "folderId", "asset:id": "assetId"}
+```
+
+## Deployment
+
+Copy the script content into a FramelightX **Script Task** brick. Place it **before** the Proxy Generator in the ingest workflow.
+
+## Notes
+
+- The script is idempotent: running it multiple times on the same asset is safe.
+- Special characters (apostrophes, ampersands, parentheses) are preserved in folder names.
+- The `--` delimiter is URL-safe and does not conflict with filesystem conventions.