> ## Documentation Index
> Fetch the complete documentation index at: https://help.pixwel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Asset workflows

# Asset Workflow Feature

## Overview

This feature allows assets to have customizable workflows associated with them. Workflows enable assets to have statuses that reflect their stage of completeness, ordering permissions, and access controls.

## Data Structure

### Asset Workflow State

Assets now have a `workflow` object with the following structure:

```javascript theme={null}
asset.workflow = {
    id: string,         // Reference to the workflow definition
    phase: string,      // Current phase/status of the asset in the workflow
    definition: object  // Per-asset overrides (optional)
}
```

The `definition` field contains asset-level overrides to the workflow:

```javascript theme={null}
asset.workflow.definition = {
    requireGraphicsApproval: boolean,  // Approval requirement for this asset
    requireOfflineApproval: boolean,   // Approval requirement for this asset
    phases: {
        [phaseKey]: {
            groups: [{ id, dng, usages }],  // Access control for this phase
            users: [{ id, dng, usages }]    // Empty arrays = everyone has access
        }
    }
}
```

When editing an asset's workflow, the form is pre-populated with workflow defaults. The saved definition fully replaces workflow defaults for access control (empty arrays mean "everyone has access").

### Workflow Definition

Workflows are stored as separate entities with the following schema:

```javascript theme={null}
{
    _id: string,
    name: string,                    // Human-readable workflow name
    requireGraphicsApproval: boolean,
    requireOfflineApproval: boolean,
    phases: {
        [phaseKey]: {
            name: string,            // Display name for the phase
            description: string,     // Phase description
            transitions: string[],   // Allowed next phases
            access: {
                groups: [{
                    id: string,
                    dng: string[],       // Dialogue/Narration/Graphics flags
                    usages: string[],
                    deliverables: string[]
                }],
                users: [{
                    id: string,
                    dng: string[],
                    usages: string[],
                    deliverables: string[]
                }]
            }
        }
    }
}
```

## Features

### Admin Panel - Workflow Management

* Create, edit, duplicate, and delete workflows
* Configure workflow phases with names, descriptions, and allowed transitions
* Set up access controls per phase (groups and users)
* Configure DNG (Dialogue/Narration/Graphics) permissions per access entry
* Configure usage permissions per access entry

### Asset Edit Modal - Workflow Tab

* Select workflow to associate with asset
* Select current workflow phase
* Override approval requirements (Graphics/Offline) at asset level
* Configure per-asset access control overrides per phase
* Phase structure (key, name, description, transitions) inherited from workflow definition (read-only)

### Asset Display

* Workflow phase displayed as a tag in asset icon flags

### Access Control

* Workflow-based access filtering on assets
* Per-phase access restrictions based on groups and users
* Asset-level definition overrides take precedence over workflow defaults

## Shared Components

### WorkflowStructureEditor

A reusable component (`ui/3x/modules/components/workflow/workflow-structure-editor.js`) used by both:

* **Admin Workflow Form** - Full editing capabilities
* **Asset Edit Workflow Tab** - Override mode (access controls only)
* **Future: Project Workflow Settings** - Project-level overrides

Configuration props:

| Prop                    | Admin | Asset Override              | Description                                                                     |
| ----------------------- | ----- | --------------------------- | ------------------------------------------------------------------------------- |
| `showApprovalToggles`   | true  | true                        | Show Graphics/Offline approval checkboxes                                       |
| `readOnly`              | false | true                        | When true, phase structure/metadata is read-only (access lists remain editable) |
| `phaseAccessHelperText` | null  | "Leave empty to inherit..." | Helper text for access lists                                                    |

### WorkflowAccessList

Reusable component for managing groups/users access entries with DNG and usage permissions.

## Files Changed

### API

* `api/models/Assets.php` - Added workflow schema fields
* `api/models/Workflows.php` - New model for workflow definitions
* `api/controllers/Workflows.php` - New controller for workflow CRUD
* `api/extensions/security/permission/Workflow.php` - Workflow permissions
* `api/extensions/security/permission/Asset.php` - Workflow-based asset filtering
* `api/config/routes.php` - Added workflows resource

### UI

* `ui/3x/pages/asset/edit-asset.js` - Workflow tab integration
* `ui/3x/modules/components/asset/edit-asset/asset-edit-workflow.js` - Asset workflow editing component
* `ui/3x/modules/components/workflow/workflow-structure-editor.js` - **Shared** workflow editor component
* `ui/3x/modules/components/workflow/access-control/` - Access control components
* `ui/3x/modules/components/admin/workflow-form/` - Admin workflow form
* `ui/3x/modules/components/global/asset-icon-flags/index.js` - Display workflow phase
* `ui/3x/modules/components/global/contact-picker/index.js` - Added disabled prop support
* `ui/3x/modules/services/workflow-service.js` - Workflow API service
* `ui/3x/pages/admin/` - Admin panel workflow management
* `ui/3x/constants/admin.js` - Admin workflow constants

### Tests

* `ui/3x/tests/unit/services/workflow-service.spec.js` - Workflow service tests
* `ui/3x/tests/unit/components/global/asset-icon-flags.spec.js` - Updated with workflow phase tests

## TODO

* [ ] Workflow phase transition validation
* [ ] Workflow assignment at project level (with override support)
* [ ] Bulk workflow operations
* [ ] Workflow history/audit log