# Acquia DAM - Enhanced Integration Links

## Overview

This submodule extends the base Acquia DAM module by providing **comprehensive tracking** of DAM asset usage across your Drupal site. While the parent module's `IntegrationLinkRegister` handles basic media entity tracking, this submodule adds **deep discovery** capabilities to detect DAM assets embedded in entity reference fields, paragraphs, and text fields with entity embeds.

---

## What This Submodule Does

Automatically detects Acquia DAM assets used in:
- **Media reference fields** - Entity reference fields pointing to media entities
- **Paragraph fields** - Recursive detection through nested paragraph entities
- **Text fields with Entity Embed** - Assets embedded in WYSIWYG editors
- **All content entity types** - Nodes, taxonomy terms, custom entities, etc.

When content is created, updated, or deleted:
- Scans all fields for DAM asset references
- Registers/updates integration links with Acquia DAM API
- Removes outdated integration links automatically
- Handles title changes by re-registering with updated descriptions

---

## Parent Module vs Submodule

| Aspect        | Parent Module          | This Submodule                             |
|---------------|------------------------|--------------------------------------------|
| **Tracks**    | Media entities only    | All content entities with DAM references   |
| **Detection** | Direct media hooks     | Multi-field, multi-type scanning           |
| **Supports**  | Media entities         | Entity references, paragraphs, text embeds |
| **Use Case**  | Simple media galleries | Complex nested content structures          |
| **Required**  |Always                  | Optional for complex sites                 |

### Parent Module Example
```
Media Entity → DAM Asset → Creates integration link
```

### Submodule Example
```
Article Node
  → Hero Image (entity reference) → Media → DAM Asset
  → Body (entity embed) → Media → DAM Asset
  → Layout (paragraphs) → Media → DAM Asset
  → All tracked with parent entity context
```

---

## When to Enable

### ✅ **Enable if you have:**
- Paragraphs with media references
- Entity Embed in text fields (WYSIWYG)
- Complex nested content structures
- Need accurate usage tracking across all content

### ❌ **Skip if you have:**
- Only direct media entity usage
- Simple content structures (no paragraphs/embeds)
- Performance-critical requirements

---

## How It Works

```
Entity Save → Check Eligibility → Run Asset Detectors → Find Assets
  ↓
Compare Old vs New → Calculate Changes
  ↓
Queue Registration → Queue Removal → Parent Module Processes
```

**Key Point:** This submodule **discovers** assets, then delegates to the parent module's `IntegrationLinkRegister` for actual API communication and database operations.

---

## Installation

```bash
drush en acquia_dam_integration_links -y
drush cr
```

No UI configuration needed - works automatically once enabled.

---

## Performance

**Impact:** Adds processing overhead on entity save (field scanning, recursive detection, database queries).

**Optimization:**
- Only processes eligible content entities
- Skips media/paragraph entities (handled by parent)
- Uses async queue for API operations
- Deduplicates assets before processing

**For high-volume sites:**
- Monitor entity save performance
- Process queue during off-peak: `drush queue:run acquia_dam_integration_links`
- Consider selective enablement if needed

---

## Troubleshooting

**Integration links not created?**
- Check: `drush queue:list`
- Process manually: `drush queue:run acquia_dam_integration_links`
- Verify parent module is configured

**Performance issues?**
- Monitor queue processing frequency
- Check entity save operation timing
- Review eligible entity types in `isEntityEligible()`

---

## Technical Details

**Entity Hooks:**
```php
hook_entity_insert()  → trackAssetUsage()
hook_entity_update()  → trackAssetUsage()
hook_entity_delete()  → removeAssetUsage()
```

**Services:**
```php
// Track assets (automatic on entity save)
\Drupal::service('acquia_dam_integration_links.enhanced_register')->trackAssetUsage($entity);

// Remove assets (automatic on entity delete)
\Drupal::service('acquia_dam_integration_links.enhanced_register')->removeAssetUsage($entity);
```

**Excluded Entities:**
- Media entities (handled by parent module)
- Paragraph entities (tracked via parent entity)
- Non-content entities

**In short:** The parent module provides the **foundation** (API, database, queuing), while this submodule provides **intelligence** (discovering assets in complex structures).
