Jobs und Aktionen

Jobs laufen nach Zeitplan (Cron), Aktionen auf Abruf per HTTP. Beides sind JavaScript-Programme in der goja-Laufzeit des tibi-server — wie Hooks, aber ohne dass du sie erst an ein Formular hängen musst. Suchbegriffe: Cron-Job, geplante Aufgabe, Action-Endpunkt, Kontaktformular-Backend.

Jobs

Laufen nach Zeitplan (Cron) — zum Beispiel Aufräumen alle 5 Minuten.

Aktionen

Laufen auf Abruf per HTTP — zum Beispiel Kontaktformular oder Webhook.

Hinweis

Der Starter liefert keine jobs:- oder actions:-Abschnitte in api/config.yml mit. Du legst sie selbst an — die Schlüssel jobs und actions gehören zum Projektschema, die Dateiformate zu job.schema.json und action.schema.json.

Job anlegen

api/config.yml — Job registrieren

jobs:
  - cron: "*/5 * * * *"      # alle 5 Minuten (klassisches 5-Felder-Format)
    type: javascript
    file: jobs/cleanup.js
    timeout: 30000           # Millisekunden, optional

Feld	Pflicht	Bedeutung
cron	nein (Schema-Pflicht: nur type + file) — aber ohne cron läuft der Job nie	5 Felder (Minute Stunde Tag Monat Wochentag), z. B. 0 8 * * * für täglich 8 Uhr
type	ja	Immer javascript
file	ja	Pfad zum Skript, relativ zum Projekt
timeout	nein	Abbruch nach N Millisekunden — setze ihn immer, damit ein Hänger nicht ewig läuft

1. Skript unter jobs/ ablegen (gleiche Hook-Laufzeit, aber JOB_CONTEXT: kein HTTP-Request).
2. jobs:-Block in api/config.yml ergänzen.
3. Config neu laden (POST …/_/admin/reload, siehe Veröffentlichen).
4. Zum Testen erst Minutentakt (* * * * *), Log prüfen, dann auf den echten Takt stellen.

jobs/cleanup.js — Beispiel mit Timeout im Blick

// Läuft unter der Projekt-UID (suexec-isoliert), fast alle Hook-Pakete verfügbar.
// Halte jeden Durchlauf kurz: Lieber oft und klein als selten und groß,
// damit der Timeout nie zuschlägt.

Action anlegen

Aktionen sind Hook-basierte Endpunkte ohne Sammlung dahinter — ideal für Kontaktformulare, Newsletter-Anmeldungen oder Webhooks. Sie nutzen dasselbe Rechte-, Hook-, CORS- und Audit-System wie Sammlungen, haben aber keine Felder, Indizes, Uploads oder Suche.

api/config.yml — Actions einbinden

actions:
  - !include actions/contact-form.yml

api/actions/contact-form.yml — eine Action

name: contact-form

meta:
  label: { de: "Kontaktformular", en: "Contact Form" }

permissions:
  public:
    methods:
      post: true        # anonym senden darf jeder
  user:
    methods:
      post: true
      get: true

hooks:
  post:
    bind:
      type: javascript
      file: hooks/contact-form/post_bind.js
    validate:
      type: javascript
      file: hooks/contact-form/post_validate.js
    handle:
      type: javascript
      file: hooks/contact-form/post_handle.js
    return:
      type: javascript
      file: hooks/contact-form/post_return.js

Baustein	Regeln
name	Nur [0-9A-Za-z_-], erreichbar unter /_actions/<name>
permissions	Gleiche Blöcke wie Sammlungen (public, user, token:…) — siehe Rechte und Tokens
hooks	Ein String (Kurzform) oder Stufen bind/validate/handle/return, je get/post
cors	Eigener Eintrag mit merge: true/false (anhängen oder ersetzen) — die CORS-Kaskade beginnt bei /_actions/<name>
audit	enabled: true plus actions: [get, post] protokolliert Aufrufe

Per API auslösen

Action per curl senden

curl -X POST http://localhost:8080/api/v1/_/<namespace>/_actions/contact-form \
  -H "Content-Type: application/json" \
  -d '{"name":"Aylin","email":"a@example.de","message":"Hallo!"}'

Im Admin auslösen

Rufe die Action-Übersicht im tibi-admin auf: Karten pro Action, Methoden-Tabs (get/post), Eingabemaske bei ausführbaren Methoden, Ergebnis- oder Fortschrittsanzeige. Gesperrte Methoden zeigen den Grund als Hinweis statt eines Buttons.

MCP-Werkzeuge für Aktionen

Zwei MCP-Werkzeuge spiegeln diese Seite: actions_list (Aktionen auflisten, braucht Lese-Recht) und action_call (Aktion aufrufen, method: get/post, Scope folgt der Methode). Signaturen, Beispiele und Fehler stehen in MCP nutzen — dort ist die einzige Referenzstelle.

Beobachten

Signal	Wo
Job-Fehler	Server-Log (docker compose logs -f tibiserver) mit Job-Name und Ursache
Action-Antwort	HTTP-Status plus Hook-return-Payload; Fortschritt bei langen Läufen
Nutzung und Quotas	LLM-Nutzungsablage und /metrics (siehe Betrieb)
Aufruf-Protokoll	Audit-Log, wenn audit.enabled auf Action-Ebene steht (siehe Sicherung)

Fehler

Fehlerbild	Ursache	Lösung
Job bricht kommentarlos ab	timeout gerissen oder Cron-Feld ungültig	Timeout erhöhen, Cron auf 5 Felder prüfen, Server-Log lesen
permission denied auf /_actions/…	Falsche Rolle oder falscher Kopf	permissions-Block und Token-Kopf prüfen (Rechte und Tokens)
Browser blockt die Action	CORS-Eintrag der Action fehlt	cors: an der Action setzen, merge-Verhalten beachten
Action läuft, schreibt aber nichts	validate/handle-Hook fehlt oder wirft	Hook-Kette Stufe für Stufe testen
project not found	Namespace falsch	Neues Projekt Schritt 5

Verifiziert am 4c55f82 2026-10-12 (tibi-types, job- und action-schema), am 68b4278 2026-10-15 (tibi-server, jobs- und actions-docs), am 2b091d8 2026-10-13 (tibi-admin-nova, actions-test-plan 40)