ferrero-opentext/QUESTIONS_FOR_DAM_IT_TEAM.md

# Questions for OpenText DAM IT Team - Metadata Inheritance

**Date:** October 29, 2025
**Context:** Content Scaling Workflow - Uploading derivative assets with metadata from master assets
**Issue:** Need to copy metadata from master asset to derivative asset and update specific fields

---

## Current Situation

### What Works ✅
- **Simple Upload:** Uploading new assets with 5 basic metadata fields works perfectly
  - `FERRERO.FIELD.MKTG.ASSET TYPE`
  - `FERRERO.FIELD.FISCAL YEAR`
  - `MAIN_LANGUAGES`
  - `ARTESIA.FIELD.ASSET NAME`
  - `FERRERO.FIELD.STATE`
- **Result:** HTTP 202 Accepted, asset appears in folder, metadata applied correctly

### What Doesn't Work ❌
- **Full Metadata Upload:** When we send the complete metadata structure from a master asset (~128KB JSON)
  - **Result:** HTTP 202 Accepted, but asset does NOT appear in the folder
  - **Behavior:** Silent failure - no error message, just doesn't create the asset
  - **Metadata Size:** 128,912 bytes vs 2,000 bytes for simple structure

---

## Our Goal

We want to implement a "derivative asset" workflow:

1. **Master Asset** exists in DAM with complete metadata (16+ fields)
2. **Download** master asset and all its metadata
3. **Store** complete metadata in our database
4. **Agency** creates derivative/localized versions
5. **Upload** derivative with:
   - **All metadata from master** (inherited)
   - **Updated fields from filename** (language, country, asset name)
   - **Result:** Derivative has same metadata as master except for the fields we changed

### Example Flow
```
Master Asset: 06_RAFFAELLO_MAESTRO_SD.mp4
  - Language: EN
  - Asset Type: TVC
  - Brand: RAFFAELLO
  - Agency: XYZ Agency
  - Fiscal Year: 2025/2026
  - [12+ other fields]

Derivative File: RAF_DE_de_XMAS_TVC_001_6S_16x9.mp4
  - Language: DE ← Updated from filename
  - Asset Type: TVC (same)
  - Asset Name: RAF_DE_de_XMAS_TVC_001_6S_16x9 ← Updated
  - Brand: RAFFAELLO ← Inherited from master
  - Agency: XYZ Agency ← Inherited from master
  - Fiscal Year: 2025/2026 ← Inherited from master
  - [All other fields inherited from master]
```

---

## Questions for DAM IT Team

### Question 1: Metadata Payload Size Limits
**Q:** Is there a maximum size limit for metadata payloads when uploading assets via `POST /v6/assets`?

**Context:**
- Simple upload (5 fields): ~2KB payload → Works ✅
- Full metadata (16+ fields): ~128KB payload → Silent failure ❌
- Both return HTTP 202, but large payload doesn't create asset

**What we need to know:**
- Is 128KB too large?
- Is there a documented limit?
- Is there a timeout for large payloads?

---

### Question 2: Metadata Inheritance from Master Assets
**Q:** What's the recommended approach to copy/inherit metadata from one asset to another?

**Options we're considering:**
1. **Copy full metadata structure** - Download master metadata and send it when uploading derivative
2. **Use asset reference** - Reference the master asset ID and tell DAM to copy metadata
3. **Use template/copy API** - Is there a dedicated endpoint for copying metadata between assets?
4. **Selective field upload** - Only send the fields we want to change, DAM preserves others?

**What we need:**
- Best practice for metadata inheritance
- Any special API endpoints for this?
- Example request structure

---

### Question 3: Nested Category Structure
**Q:** When uploading metadata, do we need to preserve the categorized structure from the master asset?

**Master metadata structure we're seeing:**
```json
{
  "metadata": {
    "metadata_element_list": [
      {
        "category_id": "1",
        "metadata_element_list": [
          {"id": "FERRERO.FIELD.MKTG.ASSET TYPE", "value": "..."},
          {"id": "MAIN_LANGUAGES", "value": "..."},
          ...
        ]
      },
      {
        "category_id": "2",
        "metadata_element_list": [...]
      }
    ]
  }
}
```

**Questions:**
- Must we preserve the category structure?
- Can we flatten to a single array of fields?
- Does the API accept both formats?

---

### Question 4: Updating Specific Fields
**Q:** Can we upload an asset with partial metadata and update specific fields later?

**Scenario:**
1. Upload asset with basic metadata (5 fields) ← Works
2. Then call an UPDATE endpoint to add/modify fields ← Does this exist?

**Questions:**
- Is there a PATCH/UPDATE metadata endpoint?
- Can we update metadata after asset creation?
- What's the endpoint: `PATCH /v6/assets/{id}/metadata`?

---

### Question 5: Field Type Requirements
**Q:** Are there specific field types that are required vs optional for the ECOMMERCE metadata model?

**What we need:**
- List of required fields for ECOMMERCE model
- Can we omit optional fields vs must send them with empty/default values?
- Does omitting fields cause validation failures?

---

### Question 6: Domain Values
**Q:** Some fields have complex domain value structures with `field_value` vs simple `value`. What determines which structure to use?

**Example structures we're seeing:**
```json
// Structure A (domain value with field_value)
{
  "id": "FERRERO.MARKETING.FIELD.AGENCY NAME",
  "value": {
    "domain_value": true,
    "value": {
      "field_value": {"value": "0000000023"},
      "type": "com.artesia.metadata.DomainValue"
    }
  }
}

// Structure B (simple domain value)
{
  "id": "FERRERO.FIELD.MKTG.ASSET TYPE",
  "value": {
    "domain_value": true,
    "value": {"type": "string", "value": "heroimage"}
  }
}
```

**Questions:**
- Which structure should we use for each field?
- Is this defined in the lookup domains?
- Can we query this via API?

---

### Question 7: Tabular Fields
**Q:** How do we properly handle tabular fields like `MAIN_LANGUAGES`?

**Current structure:**
```json
{
  "id": "MAIN_LANGUAGES",
  "parent_table_id": "FERRERO.TABULAR.FIELD.MAIN LANGUAGES",
  "type": "com.artesia.metadata.MetadataTableField",
  "values": [{"cascading_domain_value": false, ...}]
}
```

**Questions:**
- Can tabular fields have multiple values?
- Do we always use `values` array (plural)?
- Is `parent_table_id` required?

---

### Question 8: Silent Failures
**Q:** Why does the API return HTTP 202 (Accepted) but not create the asset when metadata is large?

**Observations:**
- Small metadata (~2KB): HTTP 202 → Asset created ✅
- Large metadata (~128KB): HTTP 202 → Asset NOT created ❌
- No error message in either case
- Both use identical upload structure, just different metadata content

**Questions:**
- Is there async validation that can fail after 202 response?
- How can we check if validation failed?
- Is there a job status endpoint to check async upload status?
- Should we poll for the asset to verify it was created?

---

## What We've Tried

### Attempt 1: Full Metadata from Master ❌
```php
// Downloaded full master asset metadata
// Sent entire metadata_element_list structure (15 categories, 50+ fields)
// Size: 128KB
// Result: HTTP 202 but asset not created
```

### Attempt 2: Simple 5 Fields ✅
```php
// Created minimal metadata with 5 fields
// Size: 2KB
// Result: HTTP 202 and asset appears in folder
```

---

## Technical Details

### API Endpoint Used
```
POST https://ppr.dam.ferrero.com/otmmapi/v6/assets
```

### Request Structure
```
POST /v6/assets
Content-Type: multipart/form-data

Parameters:
- asset_representation: {JSON structure}
- parent_folder_id: {folder_id}
- manifest: {upload_manifest JSON}
- files: {binary file data}
```

### Authentication
```
OAuth 2.0 Bearer Token (client_credentials)
Working correctly (uploads succeed with simple metadata)
```

### Target Folder
```
Final Assets Folder ID: ea0dbf86e13e3634895746d3a986558ec2eb8be1
Permissions: Write access confirmed
```

---

## Recommended Approach (Need IT Team Guidance)

### Option 1: Copy from Master Asset (Preferred)
```
Is there an API to say "create asset X with metadata copied from asset Y"?
Then we could update just the fields we need to change.
```

### Option 2: Two-Step Process
```
Step 1: Upload with minimal metadata (5 fields) - Works
Step 2: PATCH/UPDATE to add remaining fields from master - Does this exist?
```

### Option 3: Selective Metadata
```
Send only the fields that changed from master + references to master
Does DAM support referencing master metadata?
```

### Option 4: Understand Payload Limits
```
If there's a size limit, we could:
- Send only essential fields
- Use metadata templates
- Reference external metadata
```

---

## Sample Data Available

We can provide:
- ✅ Working simple metadata JSON (2KB, 5 fields)
- ✅ Full master metadata JSON (128KB, 50+ fields)
- ✅ Successful upload request (works)
- ✅ Failed upload request (202 but no asset created)
- ✅ HTTP request/response logs

---

## Priority Questions (Most Important)

1. **What's the proper way to inherit metadata from a master asset to a derivative?**
2. **Is there a size limit on metadata payloads?**
3. **Can we update metadata after asset creation? (PATCH endpoint)**
4. **Why does HTTP 202 not always create the asset?**

---

## Contact Information

**Project:** Ferrero Content Scaling Workflow
**Developer:** Dave Porter
**Environment:** Production (ppr.dam.ferrero.com)
**Client ID:** otds-OLV

---

**Please advise on the best approach for metadata inheritance in derivative asset workflows.** 🙏