wiki/b-reference/gateway/automation.md

Automation

Ueberblick

PowerOn hat mehrere Automatisierungs-Spuren, die sich die gleiche Unified Action Library (workflows/methods/ + ActionExecutor) teilen, aber unterschiedliche Persistenz, Scheduler und Execution Engines nutzen. Die Business Spec beschreibt eine Ziel-Architektur: konsolidierte Plattform mit klarer Trennung Mandant / Feature / Feature-Instanz, skalierbarer Toolbox-Schicht fuer Agent-Tools und einem vereinheitlichten Workflow-Datenmodell (Draft/Published, Runs, Tracing).

Leitentscheide (Business Spec):

• Keine Migration von Altdaten fuer Automation v1 (nicht produktiv); v1 bleibt bis zur Abloesung.
• Vier Saeulen: AI Service (Agent, Streaming, Neutralisierung, Failover), Graphical Editor (Flow + kuenftig Editor-Chat/UDB), Automation Scheduler (Cron/Events/Webhooks), Unified Action Library mit Toolboxes.
• Inkonsistenzen heute: zwei Workflow-Datenwelten (v1 vs Automation2), zwei DB-Schemas, zwei Scheduler-Patterns, zwei Engines -- Ausrichtung ueber Zielmodell und Uebernahme bewaehrter v1-Scheduler-Patterns in Richtung v2.

---

Ist-Systeme (Gateway, Stand 2026-04-05)

System	Kurzbeschreibung
Automation v1	Template + Cron + Placeholders; robuster inkrementeller Scheduler-Sync; keine visuelle Branching-Logik.
Automation2	n8n-Style Graph; Run/Task; Pause/Resume; Human-in-the-loop; weniger robuster Scheduler-Sync als v1.
AI Workspace	Chat-Agent mit vielen Tools + RAG; kein persistiertes Workflow-Modell wie im Graph-Editor.

Gemeinsame technische Basis: Alle genannten Pfade fuehren ueber ActionExecutor.executeAction() zur Method/Action Library; der Workspace-Agent mappt dynamicMode-Actions via ActionToolAdapter auf Tools; Automation2-Nodes tragen _method / _action.

Automation v1 vs v2 (Ist-Vergleich)

Aspekt	Automation v1	Automation2 (v2)
Modell	Template/Cron/Placeholders	Graph + Node-Typen (nodeDefinitions/)
DB / Schema	poweron_automation	poweron_automation2
Scheduler	Inkrementell, Callback automation.changed, eventId auf AutomationDefinition	Full re-register, Callback automation2.workflow.changed
Engine	WorkflowManager + WorkflowProcessor + modeAutomation	executionEngine.executeGraph
Staerken	Bewaehrtes Scheduling, Execution-Logs	Branching, Loops, Pause/Resume, visuelles Editing

Konsolidierungsrichtung (Spec): v1-Scheduler-Muster (inkrementell, Job-Handle, Reload+active-Check vor Run, capped Logs, sysCreatedBy fuer Kontext) in die v2-Welt uebernehmen; einheitliches Workflow/Version/Run-Konzept langfristig ueber beide Welten.

---

Datenmodell

Ist: Konkrete Modelle (Gateway, Stand 2026-04-05)

Modell	Datei	DB	Beschreibung
AutomationDefinition	features/automation/datamodelFeatureAutomation.py	poweron_automation	v1 Template mit schedule, placeholders, eventId
ChatWorkflow	datamodels/datamodelChat.py	poweron_chat	v1 Execution-Artefakt (Status, Tasks, Messages)
Automation2Workflow	features/automation2/datamodelFeatureAutomation2.py	poweron_automation2	v2 Graph mit active, inline graph, invocations
Automation2WorkflowRun	gleiche Datei	poweron_automation2	v2 Run: Status running/paused/completed/failed, nodeOutputs, context
Automation2HumanTask	gleiche Datei	poweron_automation2	Human-Task: Status pending/completed/rejected

Hinweis: Es gibt keine WorkflowVersion-Tabelle -- v2 speichert den Graph direkt in Automation2Workflow. Tracing ist nodeOutputs im Run, nicht ein separates RunStepLog-Entity.

Ziel: Vereinheitlichtes Workflow-Modell (Spec -- nicht implementiert)

Entitaet	Zweck	Heute approximiert durch
Workflow	Metadaten, Mandant/Instanz, active, eventId, Zeiger auf aktuelle Version	Automation2Workflow (ohne Versioning)
WorkflowVersion	Immutabler Snapshot: graph, invocations, Status draft/published/archived	nicht vorhanden (Graph inline in Workflow)
WorkflowRun	Ausfuehrung mit Status, Trigger, nodeOutputs, Kostenfelder	Automation2WorkflowRun (ohne Kostenfelder, Statusmenge abweichend)
RunStepLog	Pro Node: Input, Output, Dauer, Fehler, Token	nicht vorhanden (approximiert durch nodeOutputs)
HumanTask	Menschliche Aufgabe bei Pause; Status pending/completed/cancelled/expired	Automation2HumanTask (Status: pending/completed/rejected, kein expired)

Invarianten (Zielmodell): Pro Workflow hoechstens eine PUBLISHED Version; Scheduler bindet an die veroeffentlichte Version.

Toolbox-Datenmodell (Ziel -- nicht im Gateway implementiert)

ToolboxDefinition (id, label i18n, tools[], optional requiresConnection), ToolboxRegistry, erweiterte AgentConfig mit initialToolboxes / availableToolboxes.

Kein Match im Gateway-Code fuer requestToolbox, ToolboxDefinition oder availableToolboxes (Stand 2026-04-05).

Gateway-Schichten

Frontend -> Features (instanzgebunden) -> Services (request-scoped) -> Shared Infrastructure (workflows/methods, workflows/processing, workflows/automation2, interfaces, aicore, datamodels, security).

Feature-Container-Pattern: features/<name>/ mit main*.py (FEATURE_CODE, UI/RESOURCE/TEMPLATE_ROLES), routeFeature*.py, interfaceFeature*.py, datamodelFeature*.py, optional nodeDefinitions/, service*/. Discovery ueber registry.py / ServiceHub.

---

Ziel-Konzepte (Business Spec, nicht implementiert)

Toolbox-Konzept: Statt alle Tools flach zu exponieren, thematische Toolboxes (core, ai, email, sharepoint, workflow, ...) mit Meta-Tool requestToolbox -- Agent startet schlank, fordert Spezial-Toolboxes nach Bedarf; availableToolboxes ist pro Feature/RBAC/Connections filterbar.

Sub-Agents: Datenintensive Features (z. B. Trustee) kapseln Schema-Wissen in einem Feature Data Agent; Main-Agent sieht ein aggregiertes Tool (queryFeatureInstance), nicht Dutzende Tabellen-Tools.

Agent-Run (State Machine, konzeptionell -- nicht im Code): IDLE -> THINKING -> bei Tool-Calls EXECUTING_TOOLS -> optional TOOLBOX_ESCALATION / SUB_AGENT_CALL -> COMPLETED / FAILED / CANCELLED (Limits: maxRounds, maxCostCHF).

RBAC (Kurz): Zwei getrennte Template-Systeme -- System-Template-Rollen (Mandant: admin/user/viewer) vs Feature-Template-Rollen (Instanz: z. B. workspace-admin); keine Vermischung.

---

Schluessel-Dateien

Bereich	Typische Pfade (gateway/modules/)
Action Library	workflows/methods/, workflows/processing/ (ActionExecutor, methodDiscovery)
Automation v1 Feature	features/automation/
Automation v1 Runtime	workflows/automation/ (mainWorkflow.py, subAutomationSchedule.py)
Automation2 Feature	features/automation2/
Automation2 Runtime	workflows/automation2/ (executionEngine.py, subAutomation2Schedule.py)
Agent <-> Actions	serviceCenter/services/serviceAgent/ (Tool-Registrierung, ActionToolAdapter)
Feature-Discovery	system/registry.py, serviceHub/__init__.py
RBAC	interfaces/interfaceRbac.py, security/, Rollen/AccessRules in Datamodels

---

Regeln / Invarianten

1. Eine Action Library: Aenderungen an Methods/Actions betreffen Workspace, Automation v1, Automation2 und Agent-Tools gleichzeitig -- Kompatibilitaet und actionId-Stabilitaet beachten.
2. RBAC strikt trennen: Mandantenrollen vs Feature-Instanz-Rollen nicht mischen; Permissions ueber AccessRules und Prioritaetsregeln.
3. Scheduler vs Editor: Ausfuehrung und Zeitplanung gehoeren zur Scheduler-Saeule; der Graph ist Version-gebunden (Draft vs Published).
4. Tool-Skalierung: Flache Tool-Listen skalieren nicht; Toolbox + requestToolbox + connection-basierte Verfuegbarkeit sind das vorgesehene Gegenmittel (Ziel, nicht implementiert).
5. Zielmodell vs Ist: Workflow / WorkflowVersion / WorkflowRun in der Spec sind Zielarchitektur. Ist-Modelle siehe oben (Automation2Workflow, Automation2WorkflowRun etc.). Abgleich bei Implementierungsarbeiten erforderlich.
6. Neutralisierung / KI: Plattformweit gelten die zentralen KI-Datenpfade (siehe workflow.md / Compliance); Automation nutzt dieselben Services wie der Rest des Gateways.