wiki/b-reference/gateway/automation.md

Automation

Überblick

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 für Agent-Tools und einem vereinheitlichten Workflow-Datenmodell (Draft/Published, Runs, Tracing).

Leitentscheide (Business Spec):

• Keine Migration von Altdaten für Automation v1 (nicht produktiv); v1 bleibt bis zur Ablösung.
• Vier Säulen: AI Service (Agent, Streaming, Neutralisierung, Failover), Graphical Editor (Flow + künftig 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 über Zielmodell und Übernahme bewährter v1-Scheduler-Patterns in Richtung v2.

---

Business Spec (Zusammenfassung)

Ist-Systeme:

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 führen über ActionExecutor.executeAction() zur Method/Action Library; der Workspace-Agent mappt dynamicMode-Actions via ActionToolAdapter auf Tools; Automation2-Nodes tragen _method / _action.

Toolbox-Konzept (Ziel): 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): 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. Auflösung: höchste Priorität gewinnt bei DATA; View OR über Rollen der Top-Priorität; Item-Spezifität exact > prefix > generic.

---

Datenmodell (Zusammenfassung)

Gateway-Schichten (Data Model Doc): 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 über registry.py / ServiceHub ohne manuelles Wiring sämtlicher Router.

Ziel-Entitäten (vereinheitlichtes Workflow-Modell, Spec):

Entität	Zweck
Workflow	Metadaten, Mandant/Instanz, active, optional eventId (Scheduler-Job), Zeiger auf aktuelle Version
WorkflowVersion	Immutabler Snapshot: graph (Nodes/Connections), invocations (Trigger: manual, schedule, webhook, …), Status draft / published / archived
WorkflowRun	Eine Ausführung: Status (pending → running → completed/failed/paused/cancelled), Trigger-Metadaten, nodeOutputs, Pause-/Resume-Kontext, Kostenfelder
RunStepLog	Pro Node: Input-Snapshot, Output, Dauer, Fehler, Token-Nutzung
HumanTask	Menschliche Zwischenaufgabe bei Pause (approval/form); Status pending → completed/cancelled/expired

Invarianten (Zielmodell): Pro Workflow höchstens eine PUBLISHED Version; Scheduler bindet an die veröffentlichte Version. Pause z. B. durch Human-Task-Nodes oder E-Mail-Warten; Resume mit geliefertem Ergebnis.

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

---

Automation v1 vs v2

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 Workflow	u.a. Full re-register, Callback automation2.workflow.changed
Engine	WorkflowManager + WorkflowProcessor + modeAutomation	executionEngine.executeGraph
Stärken	Bewährtes 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 für Kontext) in die v2-Welt übernehmen; einheitliches Workflow/Version/Run-Konzept langfristig über beide Welten.

---

Schlüssel-Dateien

Bereich	Typische Pfade (gateway/modules/)
Action Library	workflows/methods/, workflows/processing/ (ActionExecutor, methodDiscovery)
Automation v1 Feature	features/automation/
Automation2 Feature	features/automation2/, workflows/automation2/
Agent ↔ Actions	serviceCenter/services/serviceAgent/ (u. a. 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: Änderungen an Methods/Actions betreifen Workspace, Automation v1, Automation2 und Agent-Tools gleichzeitig — Kompatibilität und actionId-Stabilität beachten.
2. RBAC strikt trennen: Mandantenrollen vs Feature-Instanz-Rollen nicht mischen; Permissions über AccessRules und Prioritätsregeln.
3. Scheduler vs Editor: Ausführung und Zeitplanung gehören zur Scheduler-Säule; der Graph ist Version-gebunden (Draft vs Published).
4. Tool-Skalierung: Flache Tool-Listen skalieren nicht; Toolbox + requestToolbox + connection-basierte Verfügbarkeit sind das vorgesehene Gegenmittel.
5. Zielmodell vs Ist: Workflow / WorkflowVersion / WorkflowRun in der Spec sind Zielarchitektur — Abgleich mit produktivem Schema 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.