# Subplaylist Feature Implementation Guide

## Overview
## Invariants: Xero Supporting Docs (Do Not Change)

- When recording "Get Support Docs" and the selected playlist's application_id is 6 (Xero), the app MUST record a subplaylist action using `xero_supporting_docs.add_subplaylist_action` instead of a generic `support_docs` trigger.
- During playback, when encountering a `support_docs` action and application_id==6, the app MUST execute the attach/files flow (via `_execute_subplaylist_action`) and MUST NOT fall back to the generic analyze-docs flow.
- Rationale: Xero requires a deterministic attach/files workflow; generic link analysis is a different process and is not a substitute.

The subplaylist feature allows you to embed one playlist within another, creating modular and reusable automation workflows. When a primary playlist encounters a subplaylist action, it will pause, execute the subplaylist completely, and then return to continue with the primary playlist.

## Database Changes
Run the `sub_playlist_updates.sql` script to add the necessary database columns and indexes:

```sql
-- Add subplaylist_id column to actions table
ALTER TABLE actions ADD COLUMN subplaylist_id INT NULL;
ALTER TABLE actions ADD FOREIGN KEY (subplaylist_id) REFERENCES playlists(id);
CREATE INDEX idx_actions_subplaylist_id ON actions(subplaylist_id);

-- Add subplaylist_id column to direct_integration_uploads table for queue management
ALTER TABLE direct_integration_uploads ADD COLUMN subplaylist_id INT NULL;
ALTER TABLE direct_integration_uploads ADD FOREIGN KEY (subplaylist_id) REFERENCES playlists(id);
CREATE INDEX idx_direct_uploads_subplaylist_id ON direct_integration_uploads(subplaylist_id);
```

## How to Use

### 1. Recording a Subplaylist Action
1. Start recording a playlist
2. Click the "Subplaylist" button (📋) in the UI
3. Select the target playlist from the dropdown
4. The subplaylist action will be recorded at the current timestamp

### 2. Playback Behavior
When a playlist encounters a subplaylist action during playback:
1. The system creates a queue entry in the `direct_integration_uploads` table
2. The subplaylist processor picks up the queue entry
3. The subplaylist is executed completely
4. The queue entry is marked as processed
5. The primary playlist continues with the next action

### 3. Nested Subplaylists
Subplaylists can contain other subplaylists, creating nested automation workflows. The system handles this recursively.

## Technical Implementation

### New Database Functions
- `save_subplaylist_action(playlist_id, subplaylist_id, timestamp, playlist_name)`
- `get_subplaylist_actions(playlist_id)`
- `get_playlist_by_id(playlist_id)`
- `create_subplaylist_queue_entry(playlist_id, subplaylist_id, playlist_name, ...)`
- `get_subplaylist_queue_entries(limit)`
- `mark_subplaylist_queue_processed(upload_id, processed, error_message)`

### New UI Components
- Subplaylist button in both compact and full UI modes
- "Check Subplaylist" button for manual queue checking
- Dialog for selecting target playlist
- Integration with existing recording workflow

### New Playback Methods
- `_execute_subplaylist_action(action)` - Creates queue entry for subplaylist processing
- `SubplaylistProcessor` - Background processor for handling subplaylist queue entries
- `_execute_actions_sequence(actions)` - Execute action sequence without full context

## Example Use Cases

### 1. Login Subplaylist
Create a reusable login playlist that can be called from multiple main playlists:
- Main playlist: "Process Invoices"
- Subplaylist: "Login to System"
- When main playlist needs to login, it calls the subplaylist

### 2. Document Processing Subplaylist
Create a subplaylist for processing specific document types:
- Main playlist: "Audit Workflow"
- Subplaylist: "Process PDF Documents"
- When main playlist encounters a PDF, it calls the subplaylist

### 3. Error Handling Subplaylist
Create a subplaylist for handling common errors:
- Main playlist: "Data Entry"
- Subplaylist: "Handle Validation Errors"
- When main playlist encounters validation errors, it calls the subplaylist

## Benefits

1. **Modularity**: Break complex workflows into reusable components
2. **Maintainability**: Update subplaylists independently
3. **Reusability**: Use the same subplaylist in multiple main playlists
4. **Organization**: Keep related actions grouped together
5. **Testing**: Test subplaylists independently before integrating

## Limitations

1. Subplaylists cannot modify the parent playlist's variable context
2. Subplaylists execute in isolation (no shared state)
3. Nested subplaylists are supported but should be used carefully to avoid infinite loops
4. Subplaylist actions are recorded with the current timestamp, not the actual execution time

## Troubleshooting

### Common Issues
1. **Subplaylist not found**: Ensure the target playlist exists in the database
2. **Infinite loops**: Avoid circular references between playlists
3. **Context loss**: Subplaylists don't share variable data with parent playlists

### Debug Tips
1. Check the logs for subplaylist execution messages
2. Verify playlist IDs in the database
3. Test subplaylists independently before integrating
4. Use descriptive names for playlists to avoid confusion

## Migration from Existing Playlists

To convert existing playlists to use subplaylists:
1. Identify common action sequences
2. Extract them into separate playlists
3. Replace the sequences with subplaylist actions
4. Test the new modular structure

## Future Enhancements

Potential improvements for future versions:
1. Variable passing between playlists
2. Conditional subplaylist execution
3. Subplaylist parameters
4. Subplaylist execution statistics
5. Visual subplaylist dependency graphs