Asset Upload

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

Upload Methods

Omnium provides three ways to upload assets:

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

Form File Upload

Upload files directly from HTTP form submissions (browser uploads).

API Usage

POST /api/products/{productId}/assets
Content-Type: multipart/form-data
 
[binary file data]

Response

Returns the created asset with populated metadata:

{
  "assetId": "product-image-001",
  "name": "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

Stream Upload

Upload binary data directly from code, useful for programmatic file creation.

When to Use

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

Example Flow

1. Obtain binary stream
2. Call upload service with stream, container, filename, and MIME type
3. Receive asset with blob URL

Response Structure

{
  "assetId": "product-image-002",
  "url": "https://cdn.example.com/container/guid/filename.ext",
  "fileName": "filename.ext",
  "name": "filename.ext",
  "contentType": "image/jpeg",
  "length": 12345,
  "created": "2024-01-15T10:30:00Z",
  "modified": "2024-01-15T10:30:00Z"
}

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:

Base64 Upload

For small files, you can upload using Base64-encoded content:

{
  "assets": [
    {
      "fileName": "icon.png",
      "contentType": "image/png",
      "base64EncodedContent": "/9j/4AAQSkZJRgABAQEASABIAAD..."
    }
  ]
}