Asset Upload

Omnium supports multiple methods for uploading assets. This page covers the upload mechanisms and best practices.

Upload Methods

Omnium provides two ways to upload assets via the public API:

External URL Upload

The most common upload method. Omnium downloads the file from an external URL and stores it internally.

How It Works

1. Provide an asset with ExternalUrl set
2. Omnium downloads the file from the URL
3. File is stored in Omnium's asset storage
4. Asset's Url property is updated with the internal URL

Example

Input:

{
  "assets": [
    {
      "externalUrl": "https://supplier.com/images/product.jpg",
      "fileName": "product.jpg"
    }
  ]
}

After Processing:

{
  "assets": [
    {
      "externalUrl": "https://supplier.com/images/product.jpg",
      "url": "https://cdn.example.com/products/shirt-001/product.jpg",
      "fileName": "product.jpg",
      "contentType": "image/jpeg",
      "length": 245678,
      "created": "2024-01-15T10:30:00Z",
      "modified": "2024-01-15T10:30:00Z"
    }
  ]
}

File Name Handling

The upload process determines the file name using this priority:

1. asset.FileName if provided
2. Extracted from the URL path
3. With content type extension added if missing

Binary Stream Upload

Upload a single file directly as raw binary data. Useful for programmatic uploads or files generated in code.

API Usage

The request body is the raw file content. The file name (including extension) is supplied as a query string parameter (?fileName=...) so Omnium can determine the MIME type.

POST /api/products/Assets/AddAsset/{productId}?fileName=product-image.jpg
Content-Type: application/octet-stream
 
[binary file data]

When to Use

• Generating files programmatically (PDFs, images)
• Processing binary data from external systems
• Converting between formats

Response

Returns the created asset with populated metadata:

{
  "assetId": "product-image-001",
  "name": "product-image.jpg",
  "fileName": "product-image.jpg",
  "url": "https://cdn.example.com/products/product-image.jpg",
  "contentType": "image/jpeg",
  "length": 245678,
  "created": "2024-01-15T10:30:00Z",
  "modified": "2024-01-15T10:30:00Z"
}

Metadata Populated

Storage Containers

Assets are automatically organized into containers based on context:

Container assignment is handled automatically by Omnium based on the upload context.

Virtual Folders

Assets are organized using virtual folder paths within containers:

products/
├── shirt-001/
│   ├── front.jpg
│   ├── back.jpg
│   └── detail.jpg
└── pants-002/
    └── main.jpg

Folder Naming

For product assets, the virtual folder name is:

• Product.ProductId if available
• Product.Id as fallback

Upload Behavior

Automatic Metadata

During upload, the following properties are automatically set:

CDN URL Conversion

When a CDN is configured for your tenant, internal asset URLs are automatically converted to CDN URLs for faster delivery. This conversion happens in the mapping layer when returning assets via the API.

Error Handling

Upload operations may fail for several reasons:

Best Practices

File Names

• Always include file extensions (.jpg, .png, .pdf)
• Use URL-safe characters (alphanumeric, hyphens, underscores)
• Avoid spaces and special characters

External URLs

• Use HTTPS URLs when possible
• Ensure URLs are publicly accessible (no authentication required)
• Verify URLs are stable (not temporary/signed)

Performance

• Use batch operations for multiple assets
• Take advantage of deduplication for shared images
• Consider CDN for production deployments

File Types

Common supported file types: