Aktionen

Du stößt im tibi-admin (Verwaltungs-Backend, Release Nova) eine Action an — z. B. Versand, Import oder Aufräum-Job. Du füllst Parameter aus, klickst Ausführen und liest das Ergebnis. Diese Seite beschreibt die Bedienung — das Schreiben von Actions steht unter Jobs und Actions.

Starten

1. Projekt öffnen, Sammlung Actions (Seitenleiste) wählen.
2. Action anklicken — Route /projects/:projekt/actions/:name.
3. Methode per Reiter wählen (GET oder POST; die Wahl steht auch als ?method= in der URL).
4. Formular ausfüllen, Ausführen klicken.
5. Ergebnis unterhalb lesen (Karte „Letztes Ergebnis“).

Element	Verhalten
Methoden-Reiter	Nur GET/POST sind ausführbar (runnableMethods in ActionView.svelte); PUT/DELETE erscheinen höchstens als Ansicht, nicht als Startknopf
Ausführen-Knopf	Aktiv nur bei Startrecht und gültigem Formular; während der Ausführung dreht sich das Icon und der Knopf ist gesperrt
Upload-Toast	Enthält die Eingabe Datei-Bytes, zeigt der Admin einen Byte-Fortschritt (upload-progress)
Verlauf	Werkzeug-Menü (Schild-Icon) → Audit mit Filter collection=_actions/<name>

Ausführung: kind, cancellable, Upload-Pfad

Jede Methode darf execution tragen (Schema: action.schema.json:274-288, eingebunden unter methods.<name>.execution):

Action-Config — execution-Meta

meta:
  methods:
    post:
      execution:
        kind: "long-running"   # freier String, nur Doku-Charakter
        cancellable: true      # geplant, vom Admin aktuell nicht ausgewertet

Feld	Stand im Admin (Release Nova)
execution.kind	Freier String — der Admin wertet ihn nicht aus (kein kind-spezifischer Runner; ActionView.svelte kennt nur ausführbar vs. gesperrt)
execution.cancellable	Schema-seitig vorgesehen, im Frontend ohne Verwendung (kein Abbruch-Knopf; grep über frontend/src findet keine Auswertung) — lang laufende Actions brechen nur über SSE-Ende oder Netzwerkfehler ab
Upload-Fortschritt	Enthält data Datei-Bytes (hasInlineUploadPayload), erzeugt runAction einen Byte-Toast (createByteProgressToast, ActionView.svelte:350-357) und füttert ihn per onUploadProgress (ActionView.svelte:377) — Erfolgs-Toast erst nach Server-Antwort

Hinweis

Fortschritt während der Ausführung kommt ausschließlich aus SSE-Events plus output.mapping.progress (siehe Reiter oben) — execution steuert daran nichts.

Parameter

Das Formular (ActionMethodScaffold.svelte) trennt zwei Blöcke:

query data

Block	Wohin gesendet
Abfrage-Felder (query)	Query-String der Action-URL (?feld=wert; Arrays wiederholt)
Daten-Felder (data)	JSON-Body (POST/PUT); bei GET kein Body

• Felder kommen aus action.meta.methods.<methode>.query.fields bzw. data.fields und nutzen dieselben Widgets wie der Editor (inklusive dependsOn-Sichtbarkeit).
• Validierung läuft live: Fehler erscheinen nach Verlassen des Felds (blur), der Knopf bleibt bis zur Korrektur gesperrt und nennt die Fehlerzahl.
• Technische Vorschau (aufklappbar unter dem Formular) zeigt das exakte Payload-JSON { query, data }.
• Server-Aufruf: POST /api/v1/<namespace>/_actions/<name>?… mit Sitzungs-Kopf X-Auth-Token (siehe Token-Köpfe).

Ausgabe und Fortschritt

Zusammenfassung und Details

ActionOutputMapping.svelte zeigt gemappte Felder statt Roh-JSON:

• Zusammenfassung (output.mapping.summary.fields, UI-String outputSummary) — immer sichtbar, Werte per source-Pfad aus dem Ergebnis gelesen (deepGet, z. B. totals.grandTotal).
• Details (output.mapping.details.fields) — aufklappbar, als Widgets gerendert.
• Ohne Mapping zeigt der Admin das Ergebnis als formatiertes JSON; kennt die Methode nur einen Titel ohne Felder, steht dort „Fuer diese Aktion sind keine Ergebnisfelder konfiguriert.“ (admin.actions.noOutputFields).

Fortschritt (SSE)

Liefert die Action Live-Events (Content-Type: text/event-stream), zeigt ActionProgressMapping.svelte:

• Balken aus index / count (index/count × 100, sonst Prozent oder Zählertext).
• Status- und Meldungstext aus progress.statusField / progress.messageField.
• Optionale Zusatzfelder (progress.fields) aus jedem Event.

Hinweis

Ohne output.mapping.progress in der Action-Meta gibt es bewusst keinen Balken — ein 0-%-Balken bei jeder alten Action wäre irreführend. Dann bleibt JSON das Ergebnis.

Action-Ablauf im Überblick

Formular (query + data) → Ausführen → [SSE-Events → Balken] → Ergebnis (Mapping oder JSON)
                                              └─ Verlauf: Audit mit _actions/<name>

Rechte und Fehler

Fehlerbild	Ursache	Lösung
Kein Startknopf / „gesperrt“	Methode nicht in deinen Rechten (project.yourPermissions._actions.<name>: get/post-Flag fehlt)	Rechte unter Rechte und Tokens klären
Formularfehler genannt	Pflicht-/Formatfehler im Eingabeblock	Felder korrigieren — die Vorschau zeigt, was gesendet würde
Servertext im roten Kasten	Hook oder Server meldet fachlichen Fehler	Meldung wörtlich nehmen (der Admin reicht sie durch)
permission / not found	Falscher Kopf oder Action gelöscht	Token-Köpfe und Action-Namen prüfen
Netzwerkfehler	Server nicht erreichbar	Admin einrichten prüfen, erneut versuchen

Achtung

Actions können Daten ändern. Starte eine unbekannte Action erst in einer Testumgebung — der Verlauf (_actions/<name> im Audit) zeigt nur, was bereits lief.

Klick-Abläufe dazu stehen im Test-Plan docs/test-plans/40-actions.md (Methoden-Tabs, ausführbar vs. gesperrt, Ergebnis und Fortschritt).

Anwender-Sicht zum Starten einer Aktion: Aktionen ausführen.

Verifiziert am 2b091d8 2026-10-17 (tibi-admin-nova); execution-Abschnitt verifiziert am 4c55f82 (tibi-types: action.schema.json:274-288, 401-403), am 2b091d8 (ActionView.svelte:260-295, 350-382); Screenshot-Mock verifiziert am bff84be6 2026-10-17 (tibi-admin-nova: corporate/actions/reindex-search.yml)