# Workflow Actions RBAC Integration Concept

## Übersicht

Dieses Dokument beschreibt das Konzept für die Umstrukturierung der Workflow Actions, um:
1. **RBAC-Integration** zu ermöglichen (Schutz von Actions über RESOURCE-Context)
2. **Strukturierte Parameter-Definitionen** statt Docstrings zu verwenden
3. **UI-Rendering-Typen** für Parameter zu definieren
4. **Keine Duplikation** von Parameter-Definitionen zu haben
5. **Plug-and-Play** Funktionalität beizubehalten

**WICHTIG**: 
- Alle Actions MÜSSEN in `_actions` Dictionary definiert sein
- Keine Backward Compatibility - Actions ohne `_actions` Definition sind nicht verfügbar
- RBAC-Service ist REQUIRED (kein Fallback ohne RBAC)

## Architektur-Konzept

### Grundprinzip: Deklarative Action-Definition mit Refactored Structure

Nach dem Refactoring sind Actions in separaten Dateien in `actions/` Ordnern organisiert. Die Action-Definitionen werden deklarativ in der Hauptklasse definiert und referenzieren die Execute-Funktionen aus den separaten Action-Dateien.

**Neue Ordnerstruktur** (nach Refactoring):
```
methodOutlook/
├── __init__.py
├── methodOutlook.py (Hauptklasse mit Action-Definitionen)
├── helpers/
│   ├── connection.py
│   ├── emailProcessing.py
│   └── folderManagement.py
└── actions/
    ├── readEmails.py (Execute-Funktion)
    ├── searchEmails.py
    └── ...
```

**Action-Definition in Hauptklasse** (`methodOutlook/methodOutlook.py`):
```python
from modules.datamodels.datamodelWorkflowActions import WorkflowActionDefinition, WorkflowActionParameter
from modules.shared.frontendTypes import FrontendType
from .actions.readEmails import readEmails  # Execute-Funktion importieren

class MethodOutlook(MethodBase):
    def __init__(self, services):
        super().__init__(services)
        self.name = "outlook"
        self.description = "Handle Microsoft Outlook email operations"
        
        # Initialize helper modules
        self.connection = ConnectionHelper(self)
        self.emailProcessing = EmailProcessingHelper(self)
        self.folderManagement = FolderManagementHelper(self)
        
        # Actions werden deklarativ definiert
        # Execute-Funktionen werden aus separaten Action-Dateien importiert
        self._actions = {
            "readEmails": WorkflowActionDefinition(
                actionId="outlook.readEmails",  # Für RBAC: RESOURCE context
                description="Read emails and metadata from a mailbox folder",
                parameters={
                    "connectionReference": WorkflowActionParameter(
                        name="connectionReference",
                        type="str",
                        frontendType=FrontendType.USER_CONNECTION,
                        required=True,
                        description="Microsoft connection label"
                    ),
                    "folder": WorkflowActionParameter(
                        name="folder",
                        type="str",
                        frontendType=FrontendType.SELECT,
                        frontendOptions="outlook.folder",
                        required=False,
                        default="Inbox",
                        description="Folder to read from"
                    ),
                    "limit": WorkflowActionParameter(
                        name="limit",
                        type="int",
                        frontendType=FrontendType.NUMBER,
                        required=False,
                        default=10,
                        description="Maximum items to return",
                        validation={"min": 1, "max": 1000}
                    ),
                    "filter": WorkflowActionParameter(
                        name="filter",
                        type="str",
                        frontendType=FrontendType.TEXT,
                        required=False,
                        description="Sender, query operators, or subject text"
                    ),
                    "outputMimeType": WorkflowActionParameter(
                        name="outputMimeType",
                        type="str",
                        frontendType=FrontendType.SELECT,
                        frontendOptions=["application/json", "text/plain", "text/csv"],
                        required=False,
                        default="application/json",
                        description="MIME type for output file"
                    )
                },
                execute=readEmails.__get__(self, self.__class__)  # Referenz auf Execute-Funktion
            ),
            "searchEmails": WorkflowActionDefinition(
                actionId="outlook.searchEmails",
                description="Search emails by query and return matching items",
                parameters={...},
                execute=searchEmails.__get__(self, self.__class__)
            )
        }
        
        # Register actions as methods (optional, für direkten Zugriff)
        # MethodBase lädt Actions primär aus _actions Dictionary
        self.readEmails = readEmails.__get__(self, self.__class__)
        self.searchEmails = searchEmails.__get__(self, self.__class__)
```

**Execute-Funktion in separater Datei** (`methodOutlook/actions/readEmails.py`):
```python
from modules.workflows.methods.methodBase import action
from modules.datamodels.datamodelChat import ActionResult

@action
async def readEmails(self, parameters: Dict[str, Any]) -> ActionResult:
    """
    Execute function - Parameter-Definition ist jetzt in WorkflowActionDefinition.
    Diese Funktion enthält nur noch die Implementierung.
    """
    # Implementation bleibt gleich...
    connectionReference = parameters.get("connectionReference")
    folder = parameters.get("folder", "Inbox")
    # ... rest of implementation
```

## Globale Frontend-Type-Definition

**WICHTIG**: Frontend-Types werden zentral in `modules/shared/frontendTypes.py` definiert, nicht redundant pro Action.

Die globale `FrontendType` Enum enthält:
- **Standard Types**: `text`, `textarea`, `number`, `select`, `multiselect`, `checkbox`, `date`, `datetime`, `email`, `timestamp`, `json`, `multilingual`, `file`
- **Custom Types für Actions**: `userConnection`, `documentReference`, `workflowAction`

Custom-Types unterstützen dynamische Option-Listen über API-Endpoints:
- `userConnection` → `/api/options/user.connection` (Connections des aktuellen Users)
- `documentReference` → `/api/options/workflow.documentReference` (Document-Referenzen aus Workflow-Context)
- `workflowAction` → `/api/options/workflow.action` (Verfügbare Actions aus Workflow-Context)

## Datenmodelle

### WorkflowActionParameter

**WICHTIG**: 
- Frontend-Types werden global definiert in `modules/shared/frontendTypes.py` und nicht redundant in Actions
- Diese Klasse heißt `WorkflowActionParameter` (nicht `ActionParameter`) um Konflikte mit `ActionParameters` aus `datamodelChat.py` zu vermeiden

```python
from typing import Optional, Any, Union, List, Dict
from pydantic import BaseModel, Field
from modules.shared.frontendTypes import FrontendType  # Globale Definition

class WorkflowActionParameter(BaseModel):
    """
    Parameter schema definition for a workflow action.
    
    This defines the structure and UI rendering for a single action parameter,
    NOT the actual parameter values (those are in ActionDefinition.parameters).
    """
    name: str = Field(description="Parameter name")
    type: str = Field(description="Python type as string (e.g., 'str', 'int', 'bool', 'List[str]')")
    frontendType: FrontendType = Field(description="UI rendering type (from global FrontendType enum)")
    frontendOptions: Optional[Union[str, List[Dict[str, Any]]]] = Field(
        None,
        description="Options for select/multiselect/custom types. String reference (e.g., 'user.connection') or static list. For custom types like userConnection, this is automatically set to the API endpoint."
    )
    required: bool = Field(False, description="Whether parameter is required")
    default: Optional[Any] = Field(None, description="Default value")
    description: str = Field("", description="Parameter description")
    validation: Optional[Dict[str, Any]] = Field(
        None,
        description="Validation rules (e.g., {'min': 1, 'max': 100})"
    )
```

**Custom Frontend Types**:
- `FrontendType.USER_CONNECTION`: User connection selector - dynamische Options von `/api/options/user.connection`
- `FrontendType.DOCUMENT_REFERENCE`: Document reference selector - dynamische Options aus Workflow-Context
- `FrontendType.WORKFLOW_ACTION`: Workflow action selector - dynamische Options aus verfügbaren Actions

Für Custom-Types wird `frontendOptions` automatisch auf den entsprechenden API-Endpoint gesetzt (z.B. `"user.connection"`).

### WorkflowActionDefinition

**WICHTIG**: Diese Klasse heißt `WorkflowActionDefinition` (nicht `ActionDefinition`) um Konflikte mit der bestehenden `ActionDefinition` aus `datamodelWorkflow.py` zu vermeiden:
- **Bestehende `ActionDefinition`**: Für Workflow-Execution-Planning (enthält konkrete Werte: `action`, `actionObjective`, `parameters` mit Werten)
- **Neue `WorkflowActionDefinition`**: Für Action-Schema-Definitionen (enthält Metadaten: `actionId`, `description`, `parameters` als Schemas)

```python
from typing import Dict, Callable, Awaitable, Optional, List
from pydantic import BaseModel, Field
from modules.datamodels.datamodelChat import ActionResult

class WorkflowActionDefinition(BaseModel):
    """
    Complete schema definition of a workflow action.
    
    This defines the metadata, parameters, and execution function for an action.
    This is different from datamodelWorkflow.ActionDefinition which contains
    actual execution values (action, actionObjective, parameters with values).
    
    This class defines the ACTION SCHEMA, not the execution plan.
    """
    actionId: str = Field(
        description="Unique action identifier for RBAC (format: 'module.actionName', e.g., 'outlook.readEmails')"
    )
    description: str = Field(description="Action description")
    parameters: Dict[str, WorkflowActionParameter] = Field(
        default_factory=dict,
        description="Parameter schema definitions"
    )
    execute: Optional[Callable[[Dict[str, Any]], Awaitable[ActionResult]]] = Field(
        None,
        description="Execution function - async function that takes parameters dict and returns ActionResult. Set dynamically."
    )
    category: Optional[str] = Field(None, description="Action category for grouping")
    tags: List[str] = Field(default_factory=list, description="Tags for search/filtering")
```

## Integration mit Refactored Structure

### Kompatibilität mit Folder-basierter Struktur

Nach dem Refactoring sind alle Methods in Folder-Strukturen organisiert:
- Actions in `actions/` Unterordnern
- Helper-Funktionen in `helpers/` Unterordnern
- Hauptklasse minimal gehalten

**RBAC-Integration funktioniert nahtlos mit dieser Struktur**:

1. **Action-Definitionen** werden in der **Hauptklasse** (`methodOutlook.py`) im `_actions` Dictionary definiert
2. **Execute-Funktionen** bleiben in **separaten Action-Dateien** (`actions/readEmails.py`)
3. **Helper-Klassen** werden in der Hauptklasse initialisiert und von Actions verwendet

**Vorteile**:
- Zentrale Verwaltung aller Action-Definitionen (inkl. RBAC-IDs)
- Actions bleiben modular und testbar
- Helper-Funktionen bleiben wiederverwendbar
- Einfache Migration: Schrittweise `_actions` Dictionary hinzufügen

### Beispiel: Vollständige Integration

**Struktur**:
```
methodOutlook/
├── __init__.py
├── methodOutlook.py (Hauptklasse mit _actions Dictionary)
├── helpers/
│   ├── connection.py
│   ├── emailProcessing.py
│   └── folderManagement.py
└── actions/
    ├── readEmails.py (Execute-Funktion)
    ├── searchEmails.py
    └── ...
```

**Hauptklasse** (`methodOutlook/methodOutlook.py`):
```python
class MethodOutlook(MethodBase):
    def __init__(self, services):
        super().__init__(services)
        self.name = "outlook"
        self.description = "Handle Microsoft Outlook email operations"
        
        # Initialize helper modules
        self.connection = ConnectionHelper(self)
        self.emailProcessing = EmailProcessingHelper(self)
        self.folderManagement = FolderManagementHelper(self)
        
        # RBAC-Integration: Action-Definitionen mit actionId
        self._actions = {
            "readEmails": WorkflowActionDefinition(
                actionId="outlook.readEmails",  # RBAC-ID
                description="Read emails and metadata from a mailbox folder",
                parameters={...},
                execute=readEmails.__get__(self, self.__class__)
            ),
            # ... weitere Actions
        }
        
        # Actions als Methoden registrieren (optional, für direkten Zugriff)
        self.readEmails = readEmails.__get__(self, self.__class__)
```

**Action-Datei** (`methodOutlook/actions/readEmails.py`):
```python
@action
async def readEmails(self, parameters: Dict[str, Any]) -> ActionResult:
    """Execute function - verwendet Helper-Klassen"""
    connection = self.connection.getMicrosoftConnection(...)
    params = self.emailProcessing.buildSearchParameters(...)
    # ... implementation
```

## MethodBase Erweiterung

### Neue MethodBase Struktur

```python
class MethodBase:
    """Base class for all methods"""
    
    def __init__(self, services: Any):
        self.services = services
        self.name: str
        self.description: str
        self.logger = logging.getLogger(f"{__name__}.{self.__class__.__name__}")
        
        # Actions MÜSSEN als Dictionary definiert sein
        # Jede Method-Klasse muss _actions Dictionary in __init__ definieren
        self._actions: Dict[str, WorkflowActionDefinition] = {}
        
        # Nach Initialisierung: Actions validieren
        self._validateActions()
    
    def _validateActions(self):
        """Validate that _actions dictionary is properly defined"""
        if not hasattr(self, '_actions') or not isinstance(self._actions, dict):
            raise ValueError(f"Method {self.name} must define _actions dictionary in __init__")
        
        for actionName, actionDef in self._actions.items():
            if not isinstance(actionDef, WorkflowActionDefinition):
                raise ValueError(f"Action '{actionName}' in {self.name} must be WorkflowActionDefinition instance")
            
            if not actionDef.actionId:
                raise ValueError(f"Action '{actionName}' in {self.name} must have actionId")
            
            if not actionDef.execute:
                raise ValueError(f"Action '{actionName}' in {self.name} must have execute function")
    
    @property
    def actions(self) -> Dict[str, Dict[str, Any]]:
        """
        Dynamically collect all actions from _actions dictionary.
        Returns format for API/UI consumption.
        
        REQUIREMENT: Alle Actions müssen in _actions Dictionary definiert sein.
        Actions ohne _actions Definition sind nicht verfügbar.
        """
        result = {}
        
        # Actions müssen in _actions Dictionary definiert sein
        if not hasattr(self, '_actions') or not self._actions:
            logger.error(f"Method {self.name} has no _actions dictionary defined. Actions will not be available.")
            return result
        
        for actionName, actionDef in self._actions.items():
            # RBAC-Check: Prüfe ob Action für aktuellen User verfügbar ist
            if not self._checkActionPermission(actionDef.actionId):
                continue  # Skip if user doesn't have permission
            
            # Konvertiere WorkflowActionDefinition zu System-Format
            result[actionName] = {
                'description': actionDef.description,
                'parameters': self._convertParametersToSystemFormat(actionDef.parameters),
                'method': self._createActionWrapper(actionDef)
            }
        
        return result
    
    def _checkActionPermission(self, actionId: str) -> bool:
        """
        Check if current user has permission to execute this action.
        Uses RBAC RESOURCE context.
        
        REQUIREMENT: RBAC-Service muss verfügbar sein.
        """
        if not hasattr(self.services, 'rbac') or not self.services.rbac:
            logger.error(f"RBAC service not available. Action {actionId} will be denied.")
            return False
        
        currentUser = self.services.chat.getCurrentUser()
        if not currentUser:
            logger.warning(f"No current user found. Action {actionId} will be denied.")
            return False
        
        # RBAC-Check: RESOURCE context, item = actionId
        permissions = self.services.rbac.getUserPermissions(
            user=currentUser,
            context=AccessRuleContext.RESOURCE,
            item=actionId
        )
        
        return permissions.view
    
    def _convertParametersToSystemFormat(self, parameters: Dict[str, WorkflowActionParameter]) -> Dict[str, Dict[str, Any]]:
        """Convert WorkflowActionParameter dict to system format for API/UI consumption"""
        result = {}
        for paramName, param in parameters.items():
            result[paramName] = {
                'type': param.type,
                'required': param.required,
                'description': param.description,
                'default': param.default,
                'frontendType': param.frontendType.value,
                'frontendOptions': param.frontendOptions,
                'validation': param.validation
            }
        return result
    
    def _createActionWrapper(self, actionDef: WorkflowActionDefinition):
        """Create wrapper function for action execution with parameter validation"""
        async def wrapper(parameters: Dict[str, Any], *args, **kwargs):
            # Parameter-Validierung basierend auf WorkflowActionParameter definitions
            validatedParams = self._validateParameters(parameters, actionDef.parameters)
            
            # Execute action
            return await actionDef.execute(validatedParams, *args, **kwargs)
        
        wrapper.is_action = True
        return wrapper
    
    def _validateParameters(self, parameters: Dict[str, Any], paramDefs: Dict[str, WorkflowActionParameter]) -> Dict[str, Any]:
        """Validate parameters against definitions"""
        validated = {}
        
        for paramName, paramDef in paramDefs.items():
            value = parameters.get(paramName)
            
            # Check required
            if paramDef.required and value is None:
                raise ValueError(f"Required parameter '{paramName}' is missing")
            
            # Use default if not provided
            if value is None and paramDef.default is not None:
                value = paramDef.default
            
            # Type validation
            if value is not None:
                value = self._validateType(value, paramDef.type)
            
            # Custom validation rules
            if paramDef.validation and value is not None:
                self._applyValidationRules(value, paramDef.validation)
            
            validated[paramName] = value
        
        return validated
    
    def _validateType(self, value: Any, expectedType: type) -> Any:
        """Validate and convert value to expected type"""
        # Type validation logic...
        if expectedType == int:
            return int(value)
        elif expectedType == str:
            return str(value)
        # ... weitere Typen
        return value
    
    def _applyValidationRules(self, value: Any, rules: Dict[str, Any]):
        """Apply custom validation rules"""
        if 'min' in rules and value < rules['min']:
            raise ValueError(f"Value must be >= {rules['min']}")
        if 'max' in rules and value > rules['max']:
            raise ValueError(f"Value must be <= {rules['max']}")
        # ... weitere Validierungsregeln
```

## Migrationsstrategie

### Schritt 1: Neue Datenmodelle erstellen

**WICHTIG**: Die bestehenden Klassen `ActionDefinition` (in `datamodelWorkflow.py`) und `ActionParameters` (in `datamodelChat.py`) haben einen anderen Zweck:
- `ActionDefinition` (existing): Für Workflow-Execution-Planning (enthält konkrete Werte)
- `ActionParameters` (existing): Einfacher Parameter-Wrapper

**Lösung**: Neue Klassen mit klaren Namen für Action-Schema-Definitionen erstellen.

**Datei**: `gateway/modules/datamodels/datamodelWorkflowActions.py`

```python
from typing import Optional, Any, Union, List, Dict, Callable, Awaitable
from pydantic import BaseModel, Field
from modules.datamodels.datamodelChat import ActionResult
from modules.shared.frontendTypes import FrontendType  # Globale Definition verwenden
from modules.shared.attributeUtils import registerModelLabels

class WorkflowActionParameter(BaseModel):
    """
    Parameter schema definition for a workflow action.
    
    This defines the structure and UI rendering for a single action parameter,
    NOT the actual parameter values (those are in ActionDefinition.parameters).
    """
    name: str = Field(description="Parameter name")
    type: str = Field(description="Python type as string: 'str', 'int', 'bool', 'List[str]', etc.")
    frontendType: FrontendType = Field(description="UI rendering type (from global FrontendType enum)")
    frontendOptions: Optional[Union[str, List[Dict[str, Any]]]] = Field(
        None,
        description="Options for select/multiselect/custom types. String reference (e.g., 'user.connection') or static list. For custom types, this is automatically set to the API endpoint."
    )
    required: bool = Field(False, description="Whether parameter is required")
    default: Optional[Any] = Field(None, description="Default value")
    description: str = Field("", description="Parameter description")
    validation: Optional[Dict[str, Any]] = Field(
        None,
        description="Validation rules (e.g., {'min': 1, 'max': 100})"
    )

class WorkflowActionDefinition(BaseModel):
    """
    Complete schema definition of a workflow action.
    
    This defines the metadata, parameters, and execution function for an action.
    This is different from datamodelWorkflow.ActionDefinition which contains
    actual execution values (action, actionObjective, parameters with values).
    
    This class defines the ACTION SCHEMA, not the execution plan.
    """
    actionId: str = Field(
        description="Unique action identifier for RBAC (format: 'module.actionName', e.g., 'outlook.readEmails')"
    )
    description: str = Field(description="Action description")
    parameters: Dict[str, WorkflowActionParameter] = Field(
        default_factory=dict,
        description="Parameter schema definitions"
    )
    execute: Optional[Callable] = Field(
        None,
        description="Execution function - async function that takes parameters dict and returns ActionResult. Set dynamically."
    )
    category: Optional[str] = Field(None, description="Action category for grouping")
    tags: List[str] = Field(default_factory=list, description="Tags for search/filtering")

# Register model labels for UI
registerModelLabels(
    "WorkflowActionDefinition",
    {"en": "Workflow Action Definition", "fr": "Définition d'action de workflow"},
    {
        "actionId": {"en": "Action ID", "fr": "ID d'action"},
        "description": {"en": "Description", "fr": "Description"},
        "parameters": {"en": "Parameters", "fr": "Paramètres"},
        "category": {"en": "Category", "fr": "Catégorie"},
        "tags": {"en": "Tags", "fr": "Étiquettes"},
    },
)

registerModelLabels(
    "WorkflowActionParameter",
    {"en": "Workflow Action Parameter", "fr": "Paramètre d'action de workflow"},
    {
        "name": {"en": "Name", "fr": "Nom"},
        "type": {"en": "Type", "fr": "Type"},
        "frontendType": {"en": "Frontend Type", "fr": "Type frontend"},
        "frontendOptions": {"en": "Frontend Options", "fr": "Options frontend"},
        "required": {"en": "Required", "fr": "Requis"},
        "default": {"en": "Default", "fr": "Par défaut"},
        "description": {"en": "Description", "fr": "Description"},
        "validation": {"en": "Validation", "fr": "Validation"},
    },
)
```

### Schritt 2: MethodBase erweitern

**Datei**: `gateway/modules/workflows/methods/methodBase.py`

- Neue `_actions` Dictionary Property (REQUIRED)
- RBAC-Check Integration (REQUIRED)
- Parameter-Validierung
- Unterstützung für Refactored Structure (Actions in separaten Dateien)

**WICHTIG**: 
- MethodBase unterstützt NUR noch die `_actions` Dictionary-Struktur
- Alle Actions MÜSSEN in `_actions` Dictionary definiert sein
- RBAC-Service ist REQUIRED (kein Fallback ohne RBAC)
- `@action` Decorator wird weiterhin verwendet, aber nur für Execute-Funktionen (nicht für Discovery)

### Schritt 3: Beispiel-Migration mit Refactored Structure

**Vorher** (monolithische `methodOutlook.py`):
```python
@action
async def readEmails(self, parameters: Dict[str, Any]) -> ActionResult:
    """
    GENERAL:
    - Purpose: Read emails from Outlook mailbox
    
    Parameters:
    - connectionReference (str, required): Microsoft connection label.
    - query (str, optional): Search query for emails.
    - folder (str, optional): Folder name.
    - limit (int, optional): Maximum number of emails. Default: 50.
    """
    # Implementation...
```

**Nachher** (Refactored Structure):

**1. Hauptklasse** (`methodOutlook/methodOutlook.py`):
```python
from modules.datamodels.datamodelWorkflowActions import WorkflowActionDefinition, WorkflowActionParameter
from modules.shared.frontendTypes import FrontendType
from .actions.readEmails import readEmails
from .helpers.connection import ConnectionHelper
from .helpers.emailProcessing import EmailProcessingHelper
from .helpers.folderManagement import FolderManagementHelper

class MethodOutlook(MethodBase):
    def __init__(self, services):
        super().__init__(services)
        self.name = "outlook"
        self.description = "Handle Microsoft Outlook email operations"
        
        # Initialize helper modules
        self.connection = ConnectionHelper(self)
        self.emailProcessing = EmailProcessingHelper(self)
        self.folderManagement = FolderManagementHelper(self)
        
        # Actions werden deklarativ definiert
        self._actions = {
            "readEmails": WorkflowActionDefinition(
                actionId="outlook.readEmails",
                description="Read emails and metadata from a mailbox folder",
                parameters={
                    "connectionReference": WorkflowActionParameter(
                        name="connectionReference",
                        type="str",
                        frontendType=FrontendType.USER_CONNECTION,
                        required=True,
                        description="Microsoft connection label"
                    ),
                    "folder": WorkflowActionParameter(
                        name="folder",
                        type="str",
                        frontendType=FrontendType.SELECT,
                        frontendOptions="outlook.folder",
                        required=False,
                        default="Inbox",
                        description="Folder to read from"
                    ),
                    "limit": WorkflowActionParameter(
                        name="limit",
                        type="int",
                        frontendType=FrontendType.NUMBER,
                        required=False,
                        default=10,
                        description="Maximum items to return",
                        validation={"min": 1, "max": 1000}
                    ),
                    "filter": WorkflowActionParameter(
                        name="filter",
                        type="str",
                        frontendType=FrontendType.TEXT,
                        required=False,
                        description="Sender, query operators, or subject text"
                    ),
                    "outputMimeType": WorkflowActionParameter(
                        name="outputMimeType",
                        type="str",
                        frontendType=FrontendType.SELECT,
                        frontendOptions=["application/json", "text/plain", "text/csv"],
                        required=False,
                        default="application/json",
                        description="MIME type for output file"
                    )
                },
                execute=readEmails.__get__(self, self.__class__)  # Referenz auf Execute-Funktion
            )
        }
        
        # Register actions as methods (optional, für direkten Zugriff)
        self.readEmails = readEmails.__get__(self, self.__class__)
```

**2. Action-Datei** (`methodOutlook/actions/readEmails.py`):
```python
from modules.workflows.methods.methodBase import action
from modules.datamodels.datamodelChat import ActionResult

@action
async def readEmails(self, parameters: Dict[str, Any]) -> ActionResult:
    """
    Execute function - Parameter-Definition ist jetzt in WorkflowActionDefinition.
    Diese Funktion enthält nur noch die Implementierung.
    """
    # Implementation bleibt gleich...
    connectionReference = parameters.get("connectionReference")
    folder = parameters.get("folder", "Inbox")
    # ... rest of implementation using self.connection, self.emailProcessing, etc.
```

## RBAC-Integration

### Action-IDs Format

Actions werden im RBAC-System als RESOURCE-Context Items behandelt:

- **Format**: `{moduleName}.{actionName}`
- **Beispiele**:
  - `outlook.readEmails`
  - `outlook.sendEmail`
  - `sharepoint.uploadDocument`
  - `ai.process`

### RBAC-Regeln für Actions

```json
{
  "roleLabel": "user",
  "context": "RESOURCE",
  "item": "outlook.readEmails",
  "view": true
}
```

```json
{
  "roleLabel": "admin",
  "context": "RESOURCE",
  "item": "outlook",
  "view": true
}
```

**Hierarchie**: Spezifische Action-Regeln überschreiben generische Module-Regeln.

### Bootstrap: Default RBAC Rules für Actions

In `interfaceBootstrap.py`:

```python
def initRbacRules(db: DatabaseConnector) -> None:
    # ... existing rules ...
    
    # Action Rules (RESOURCE context)
    createActionRules(db)

def createActionRules(db: DatabaseConnector):
    """Create default RBAC rules for workflow actions"""
    
    # SysAdmin: Access to all actions
    db.recordCreate(AccessRule(
        roleLabel="sysadmin",
        context=AccessRuleContext.RESOURCE,
        item=None,  # All resources
        view=True
    ))
    
    # Admin: Access to all actions
    db.recordCreate(AccessRule(
        roleLabel="admin",
        context=AccessRuleContext.RESOURCE,
        item=None,
        view=True
    ))
    
    # User: Access to specific actions only
    userActions = [
        "outlook.readEmails",
        "outlook.sendEmail",
        "sharepoint.readDocuments",
        "ai.process"
    ]
    
    for actionId in userActions:
        db.recordCreate(AccessRule(
            roleLabel="user",
            context=AccessRuleContext.RESOURCE,
            item=actionId,
            view=True
        ))
    
    # Viewer: Read-only actions
    viewerActions = [
        "outlook.readEmails",
        "sharepoint.readDocuments"
    ]
    
    for actionId in viewerActions:
        db.recordCreate(AccessRule(
            roleLabel="viewer",
            context=AccessRuleContext.RESOURCE,
            item=actionId,
            view=True
        ))
```

## Organisation der Action-Definitionen

### Zentrale Definition in Hauptklasse

**Prinzip**: Alle Action-Definitionen werden zentral in der Hauptklasse (`methodOutlook.py`) im `_actions` Dictionary definiert.

**Vorteile**:
- Übersichtliche Verwaltung aller Actions einer Method
- Einfache RBAC-Integration (alle Action-IDs an einem Ort)
- Einfache API-Discovery (MethodBase kann alle Actions sammeln)
- Type-Safety durch Pydantic Models

### Execute-Funktionen bleiben in separaten Dateien

**Prinzip**: Die Execute-Funktionen bleiben in den separaten Action-Dateien (`actions/readEmails.py`).

**Vorteile**:
- Modulare Struktur (eine Datei pro Action)
- Einfache Wartung und Tests
- Parallele Entwicklung möglich
- Helper-Klassen bleiben zugänglich über `self`

### Beispiel-Struktur

```
methodOutlook/
├── methodOutlook.py
│   └── _actions = {
│       "readEmails": WorkflowActionDefinition(...),
│       "searchEmails": WorkflowActionDefinition(...)
│   }
└── actions/
    ├── readEmails.py
    │   └── async def readEmails(self, parameters) -> ActionResult
    └── searchEmails.py
        └── async def searchEmails(self, parameters) -> ActionResult
```

### Migration-Strategie

1. **Schritt 1**: Action-Definitionen in `_actions` Dictionary hinzufügen
2. **Schritt 2**: Execute-Funktionen aus Action-Dateien referenzieren
3. **Schritt 3**: RBAC-Regeln in Bootstrap erstellen
4. **Schritt 4**: Tests und Validierung

**Wichtig**: Execute-Funktionen müssen nicht geändert werden - sie bleiben identisch!

## Vorteile

### 1. Keine Duplikation
- Parameter werden nur einmal definiert (in `WorkflowActionDefinition`)
- Keine Docstring-Parsing mehr nötig
- Type-Safety durch Pydantic Models
- Zentrale Verwaltung in Hauptklasse

### 2. RBAC-Integration
- Jede Action hat eine eindeutige ID für RBAC
- Granulare Kontrolle pro Action möglich
- Hierarchische Regeln (Module → Action)
- Action-IDs zentral in `_actions` Dictionary verwaltet

### 3. UI-Rendering
- Frontend-Typen explizit definiert
- Options-Referenzen für dynamische Optionen
- Validierung auf Backend-Ebene
- Strukturierte Parameter-Definitionen für Frontend

### 4. Plug-and-Play
- Actions bleiben als separate Method-Klassen
- Einfache Erweiterung durch neue Method-Klassen
- Refactored Structure bleibt erhalten
- Klare Anforderungen: Alle Actions müssen `_actions` Dictionary haben

### 5. Type Safety
- Pydantic Models für Validierung
- Type-Hints für bessere IDE-Unterstützung
- Runtime-Validierung
- Zentrale Definitionen für bessere Wartbarkeit

### 6. Refactored Structure Kompatibilität
- Funktioniert nahtlos mit Folder-basierter Struktur
- Execute-Funktionen bleiben in separaten Dateien
- Helper-Klassen bleiben wiederverwendbar
- Einfache Migration ohne Code-Änderungen in Action-Dateien

## Migration Timeline

### Phase 1: Foundation (Woche 1)
- ✅ Datenmodelle erstellen (`datamodelWorkflowActions.py`)
- ✅ MethodBase erweitern
- ✅ RBAC-Integration in MethodBase
- ✅ Refactoring aller Methods abgeschlossen (Ordnerstruktur)

### Phase 2: Beispiel-Migration (Woche 2)
- 📝 Ein Method-Beispiel migrieren (z.B. `methodOutlook` mit RBAC-Definitionen)
- 📝 Action-Definitionen in Hauptklasse (`_actions` Dictionary) hinzufügen
- 📝 Execute-Funktionen in Action-Dateien bleiben unverändert
- 📝 Tests schreiben
- 📝 Dokumentation aktualisieren

**Hinweis**: Da alle Methods bereits refactored sind (Actions in separaten Dateien), ist die Migration einfacher: Nur `_actions` Dictionary in Hauptklasse hinzufügen, Execute-Funktionen bleiben unverändert.

### Phase 3: Vollständige Migration (Woche 3-4)
- 📝 Alle Methods migrieren (Action-Definitionen hinzufügen)
- 📝 RBAC-Regeln in Bootstrap erstellen
- 📝 Frontend-Integration
- 📝 API-Endpunkte für Action-Discovery implementieren

### Phase 4: Testing & Cleanup (Woche 5)
- 📝 Unit Tests
- 📝 Integration Tests
- 📝 Performance Tests
- 📝 Alte Docstring-Parsing-Logik entfernen (nicht mehr benötigt)
- 📝 Sicherstellen, dass alle Methods `_actions` Dictionary haben

## Praktische Umsetzung

### Schritt-für-Schritt: Action-Definition hinzufügen

**Voraussetzung**: Method ist bereits refactored (Actions in separaten Dateien).

**Schritt 1**: Importiere benötigte Klassen in Hauptklasse
```python
# In methodOutlook/methodOutlook.py
from modules.datamodels.datamodelWorkflowActions import WorkflowActionDefinition, WorkflowActionParameter
from modules.shared.frontendTypes import FrontendType
```

**Schritt 2**: Erstelle `_actions` Dictionary in `__init__`
```python
def __init__(self, services):
    super().__init__(services)
    # ... existing code ...
    
    # RBAC-Integration: Action-Definitionen
    self._actions = {
        "readEmails": WorkflowActionDefinition(
            actionId="outlook.readEmails",
            description="Read emails and metadata from a mailbox folder",
            parameters={
                "connectionReference": WorkflowActionParameter(
                    name="connectionReference",
                    type="str",
                    frontendType=FrontendType.USER_CONNECTION,
                    required=True,
                    description="Microsoft connection label"
                ),
                # ... weitere Parameter
            },
            execute=readEmails.__get__(self, self.__class__)
        )
    }
```

**Schritt 3**: Execute-Funktion bleibt unverändert
```python
# In methodOutlook/actions/readEmails.py
# Keine Änderungen nötig - Funktion bleibt identisch
@action
async def readEmails(self, parameters: Dict[str, Any]) -> ActionResult:
    # Implementation bleibt gleich...
```

**Schritt 4**: RBAC-Regel in Bootstrap hinzufügen
```python
# In interfaceBootstrap.py
db.recordCreate(AccessRule(
    roleLabel="user",
    context=AccessRuleContext.RESOURCE,
    item="outlook.readEmails",
    view=True
))
```

### Migration-Checkliste pro Method

- [ ] `_actions` Dictionary in Hauptklasse erstellen
- [ ] Alle Actions mit `WorkflowActionDefinition` definieren
- [ ] Parameter mit `WorkflowActionParameter` definieren
- [ ] Frontend-Types aus globaler `FrontendType` Enum verwenden
- [ ] Execute-Funktionen aus Action-Dateien referenzieren
- [ ] RBAC-Regeln in Bootstrap hinzufügen
- [ ] Tests durchführen

## Offene Fragen

1. **Backward Compatibility**: Werden alte Actions ohne `_actions` Dictionary unterstützt?
   - **Antwort**: Nein. Alle Actions MÜSSEN in `_actions` Dictionary definiert sein. Es gibt keinen Fallback auf `@action` Decorator. Actions ohne `_actions` Definition sind nicht verfügbar.

2. **Parameter-Validierung**: Soll Validierung strikt sein oder tolerant?
   - **Antwort**: Konfigurierbar pro Action

3. **Action-Discovery**: Sollen Actions zur Laufzeit registriert werden können?
   - **Antwort**: Ja, über `_registerActions()` Methode

4. **Frontend-Integration**: Wie werden Actions im Frontend angezeigt?
   - **Antwort**: API-Endpoint `/api/workflows/actions` liefert strukturierte Action-Definitionen aus `_actions` Dictionary (gefiltert nach RBAC)

5. **Action-Definitionen in separaten Dateien**: Sollen Action-Definitionen auch in den Action-Dateien stehen?
   - **Antwort**: Nein, Action-Definitionen bleiben in der Hauptklasse (`_actions` Dictionary). Die Action-Dateien enthalten nur die Execute-Funktionen. Dies ermöglicht zentrale Verwaltung und einfache RBAC-Integration.

6. **Migration-Reihenfolge**: Sollen alle Actions einer Method gleichzeitig migriert werden?
   - **Antwort**: Empfohlen: Schrittweise pro Action, um Risiko zu minimieren. Aber auch vollständige Migration pro Method ist möglich.

## API-Endpunkte

**WICHTIG**: Diese API-Endpunkte beziehen sich auf **Action-Definitionen** (Schema), nicht auf ausführbare Workflows oder Templates.

### GET /api/workflows/actions
Liefert alle verfügbaren Actions für den aktuellen User (gefiltert nach RBAC):

**Zweck**: Action-Discovery für Workflow-Editor und dynamische Workflows
**Verwendung**: 
- Workflow-Editor: Zeigt verfügbare Actions in Toolbox
- Dynamic Workflows: Zeigt verfügbare Actions für AI-Auswahl

```json
{
  "actions": [
    {
      "module": "outlook",
      "actionId": "outlook.readEmails",
      "name": "readEmails",
      "description": "Read emails from Outlook mailbox",
      "parameters": {
        "connectionReference": {
          "type": "str",
          "frontendType": "userConnection",
          "frontendOptions": "user.connection",  # Automatisch für Custom-Types
          "required": true,
          "description": "Microsoft connection label"
        },
        "documentList": {
          "type": "List[str]",
          "frontendType": "documentReference",
          "frontendOptions": "workflow.documentReference",  # Automatisch für Custom-Types
          "required": false,
          "description": "Document list reference(s) from previous actions"
        },
        ...
      }
    },
    ...
  ]
}
```

### GET /api/workflows/actions/{module}
Liefert Actions für ein spezifisches Modul.

### POST /api/workflows/actions/{module}/{action}/execute
Führt eine Action aus (mit RBAC-Check).

## Custom Frontend Types für Actions

### Verfügbare Custom Types

1. **`FrontendType.USER_CONNECTION`**
   - **API-Endpoint**: `/api/options/user.connection`
   - **Beschreibung**: Zeigt alle aktiven Connections des aktuellen Users
   - **Verwendung**: Für Parameter wie `connectionReference` in Outlook/SharePoint Actions
   - **Beispiel**:
     ```python
     WorkflowActionParameter(
         name="connectionReference",
         type="str",
         frontendType=FrontendType.USER_CONNECTION,
         required=True,
         description="Microsoft connection label"
     )
     ```

2. **`FrontendType.DOCUMENT_REFERENCE`**
   - **API-Endpoint**: `/api/options/workflow.documentReference` (zu implementieren)
   - **Beschreibung**: Zeigt verfügbare Document-Referenzen aus dem aktuellen Workflow-Context
   - **Verwendung**: Für Parameter wie `documentList` in Actions, die auf vorherige Action-Ergebnisse verweisen
   - **Beispiel**:
     ```python
     WorkflowActionParameter(
         name="documentList",
         type="List[str]",
         frontendType=FrontendType.DOCUMENT_REFERENCE,
         required=False,
         description="Document list reference(s) from previous actions"
     )
     ```

3. **`FrontendType.WORKFLOW_ACTION`**
   - **API-Endpoint**: `/api/options/workflow.action` (zu implementieren)
   - **Beschreibung**: Zeigt verfügbare Actions aus dem Workflow-Context
   - **Verwendung**: Für Parameter, die auf andere Actions verweisen

### Custom Types erweitern

Neue Custom-Types können über `frontendTypes.py` registriert werden:

```python
from modules.shared.frontendTypes import FrontendType, registerCustomType

# Neuer Custom-Type hinzufügen
FrontendType.SHAREPOINT_FOLDER = "sharepointFolder"

# Registrieren
registerCustomType(
    frontendType=FrontendType.SHAREPOINT_FOLDER,
    optionsApiEndpoint="sharepoint.folder",
    description={
        "en": "SharePoint Folder",
        "fr": "Dossier SharePoint",
        "de": "SharePoint-Ordner"
    }
)
```

### Frontend-Integration

Das Frontend muss:
1. Custom-Types erkennen (z.B. `frontendType === "userConnection"`)
2. Automatisch Options von `/api/options/{optionsName}` laden
3. Die Options als Select/Multiselect rendern

**Beispiel Frontend-Logik**:
```typescript
if (param.frontendType === 'userConnection') {
  // Automatisch Options von /api/options/user.connection laden
  const options = await fetch(`/api/options/${param.frontendOptions}`);
  // Als Select rendern
}
```