Freigaben in eigenen Prozessen bauen
Für Entwickler und Agenturen: processes.php, requestApproval, Meldungen und Entwurfs-Karten mit Code-Beispielen.
Diese Seite richtet sich an Entwickler und Agenturen, die mit der tm-CLI oder dem Builder einen eigenen Workspace bauen und einen Ablauf mit Menschen im Loop einrichten möchten. Das nutzersichtbare Verhalten (Karten, Erinnerungen, Bestätigungen) beschreibt Freigaben, Rückfragen & Benachrichtigungen; hier geht es um die Config- und Tool-Seite mit Code-Beispielen.
Ein Prozess mit Freigabe-Schritt
Ein Ablauf steht deklarativ in config/tenants/<workspace>/processes.php. Das Tool runProcess führt ihn aus, ein Scheduled Task ruft es periodisch auf. Jeder Lauf macht höchstens die nächsten Schritte bis zum ersten Warten.
Gekürztes, anonymisiertes Beispiel mit einer Freigabe (approval), einer Entscheidungs-Seite für Sonderfälle (page) und einer Ergebnis-Mail (mail):
// config/tenants/<workspace>/processes.php
return ['processes' => [
'beispielprozess' => [
'label' => 'Monatsabschluss Beispiel',
'start' => ['day' => 1, 'at' => '08:00'],
'first_period' => '2026-11',
'audience' => ['users' => ['pruefung@beispiel-firma.de', 'leitung@beispiel-firma.de']],
'escalate_to' => ['leitung@beispiel-firma.de'],
// Erinnerungen und Eskalation zentral statt im Prozess selbst (s. u.)
'reminders' => 'central',
// Testmodus: fester Zeitraum, eigener Adressat, Minuten statt Tage
'test' => [
'period' => '2026-11',
'audience' => ['user' => 'pruefung@beispiel-firma.de'],
'timing' => ['deadline' => '+6 minutes', 'remind' => ['every' => '3 minutes']],
],
'steps' => [
[
'id' => 'freigabe', 'type' => 'approval',
'title' => 'Liste {period_label} freigeben',
'subject' => 'Bitte bis {deadline_day} freigeben',
'text' => ['Bitte im Sheet prüfen und bis *{deadline}* freigeben.'],
'button' => 'Freigeben',
'deadline' => ['day' => 4, 'at' => '10:00'],
'remind' => ['every' => '1 day', 'at' => '08:00', 'until' => ['day' => 10, 'at' => '23:59']],
'on_approve' => 'Danke! TaskMonkey macht beim nächsten Lauf weiter.',
],
// … Schritte 'tool' zum Buchen/Auswerten, mit Ergebnis unter steps.auswertung …
[
'id' => 'sonderfaelle', 'type' => 'page',
'when' => ['steps.auswertung.review_count', '>', 0],
'title' => 'Sonderfälle {period_label}',
'intro' => 'Bitte je Fall entscheiden: nachbuchen oder nicht buchen.',
'items' => '{steps.auswertung.review_items}',
'options' => ['nachbuchen' => 'Korrigiert – nachbuchen', 'nicht' => 'Nicht buchen (erledigt)'],
],
[
'id' => 'ergebnis', 'type' => 'mail',
'to' => 'audience', 'mail_always' => true,
'subject' => '{steps.auswertung.subject}',
'lines' => ['{steps.auswertung.lines}'],
],
],
],
]];
Wichtige Felder:
| Feld | Bedeutung |
|---|---|
type: approval |
Freigabe-Anfrage mit Karte im Chat, deadline (Frist), remind (every/at/until), not_before, expires, on_approve. Nach Freigabe genau einmal weiter, optional loop_to zurück zu einem früheren Schritt. |
type: page |
Entscheidungs-Seite aus fester Vorlage: items (Liste mit code/title/details), options (Wert → Label), title, intro. Ergebnis landet unter steps.<id>.page_id/edit_url; eine Freigabe kann mit page darauf verweisen, damit der Seitenrahmen den Button zeigt. |
type: mail |
Bescheid per Mail; mail_always schickt zusätzlich zur Chat-Meldung immer eine Mail, nicht nur als Fallback. |
test.audience |
Ersetzt im Testmodus den Adressaten des gesamten Prozesses. |
reminders: 'central' |
Übergibt Erinnerungen und Eskalation an die zentrale Verarbeitung: an Werktagen, solange die Anfrage offen ist (die Karte rückt im Chat wieder ans Ende; per Mail erinnert wird nur, wer sie noch nicht gesehen hat), und bei Erreichen der deadline automatisch mit Kopie an escalate_to. TaskMonkey leitet das intern ab — kein eigenes Feld dafür in der Config setzen. |
Mehr Felder (repeat, loop_args, when, optional, quiet_expire, Platzhalter) stehen im Rezept „Monatlicher Prozess mit Freigaben“.
Rückfragen und Infos aus eigenem Tool-Code
Jedes eigene Tool kann über $ctx['tool']('requestApproval', [...]) eine Freigabe, Rückfrage oder Info anlegen. Voraussetzung: Das aufrufende Tool steht in approvals.tools des Workspaces.
Rückfrage mit zwei festen Optionen und zusätzlichem Freitext:
$frage = $ctx['tool']('requestApproval', [
'tool' => 'beispielProzess',
'kind' => 'question',
'mode' => 'signal',
'audience' => 'user',
'user' => 'user@beispiel-firma.de',
'title' => 'Gutschrift auf die Rechnung oder als Gutschein?',
'options' => [
'items' => [
['value' => 'rechnung', 'label' => 'Auf die Rechnung'],
['value' => 'gutschein', 'label' => 'Gutschein'],
],
'allow_free_text' => true,
],
]);
Info ohne Entscheidung an die aktiven Admins/Manager des Workspaces (bzw. an hil.default_audience, siehe unten):
$info = $ctx['tool']('requestApproval', [
'tool' => 'beispielProzess',
'kind' => 'info',
'mode' => 'signal',
'audience' => 'tenant',
'title' => '12 Gutschriften gebucht, 3 Prüffälle',
]);
mode: signal führt selbst nichts aus — nur das anfragende Tool darf die Anfrage anlegen (tool muss dem Namen des aufrufenden Tools entsprechen) und später über consumeApproval genau einmal verbrauchen. mode: execute (Default bei kind: approval) lässt ein fest hinterlegtes Tool mit gespeicherten Argumenten nach der Freigabe genau einmal ausführen.
Eine Zeile in den Vorgangs-Block schreiben
Für Dinge, die ein Mensch wissen oder tun muss — nicht für reine Erfolgsmeldungen, Debug oder einzelne Retries:
$ctx['logger']->notify('Shopify-Zugang abgelaufen – bitte neu verbinden', [
'level' => 'action', // info | action (Default) | critical (nur mit Tool-Flag notify_critical)
'key' => 'shopify_auth', // Fingerprint für Schwelle/Entdoppelung
'min_count' => 2, // erst ab dem 2. Fehlschlag in Folge
'links' => [['label' => 'Verbindungen', 'url' => '/manage/connections']],
]);
// wieder ok → Zähler zurücksetzen, nichts melden
$ctx['logger']->notify('ok', ['key' => 'shopify_auth', 'resolved' => true]);
$ctx['notify'] ist die kurze Schreibweise für denselben Aufruf. Die Zeile landet im Vorgangs-Block des Tools im Hauptchat der Admins (oder von hil.default_audience), zusätzlich im Ausführungs-Log. Gleiche Zeilen werden gezählt statt wiederholt gepostet, info wird einige Minuten gebündelt, und es gibt ein Limit je Tool und Stunde. Mehr dazu und zu notifyHuman (dasselbe für Prozess-Schritte, Argumente process_key, text, audience, title, links, level, detail) im Tools-README.
Eingehende Mails melden: inbox.notify
Ein eingehender Mail-Posteingang kann bestimmte Kategorien als „Handlung nötig“ im Hauptchat melden und Entwürfe eines Antwort-Bots als Freigabe-Karte anbieten, bevor sie versendet werden.
// config/tenants/<workspace>/hil.php
return [
'hil' => [
// Rückfall-Empfänger für Meldungen ohne genannten Adressaten
'default_audience' => ['support@beispiel-firma.de'],
],
'inbox.notify' => [
'enabled' => true,
// Präfix-Match auf Inbox-Kategorien
'categories' => ['bestellung.reklamation', 'b2b'],
'recipients' => ['support@beispiel-firma.de'],
// Bot-Entwürfe als Karte „Antwort senden?“ statt automatischem Versand
'drafts' => 'approve',
],
];
categories wählt Inbox-Kategorien per Präfix, recipients nennt Empfänger (ohne Angabe greift hil.default_audience). Mit drafts => 'approve' zeigt TaskMonkey einen vom Bot vorbereiteten Entwurf vollständig als Karte; „Freigeben“ sendet genau diesen Text einmal über den bestehenden Sende-Weg.
hil.default_audience
hil.default_audience legt eine E-Mail-Liste aktiver Mitglieder als Rückfall fest, wenn ein Aufruf keinen Adressaten nennt — für Tool-Meldungen, notifyHuman, requestApproval ohne audience und Entwurfs-Karten. Damit landen Meldungen ohne genannten Adressaten gezielt bei diesen Personen statt beim gesamten Workspace.
Fail-closed: Ist die Liste gesetzt, aber leer oder löst sie niemanden auf, gibt es keinen Rückfall auf „alle Admins“ — die Meldung unterbleibt. Ganz ohne den Schlüssel bleibt das bisherige Verhalten (alle Admins/Manager) bestehen.
WhatsApp-Opt-in für einen Schritt
Ein Freigabe-Schritt kann zusätzlich 'whatsapp' => true setzen:
[
'id' => 'freigabe', 'type' => 'approval',
'title' => 'Liste {period_label} freigeben',
'whatsapp' => true,
// … deadline, remind, button wie oben …
],
Das schaltet diese einzelne Freigabe für den WhatsApp-Kanal frei, sobald die Plattformnummer dafür aktiv ist (Stand siehe WhatsApp: kommt demnächst). Ohne dieses Flag bleibt die Freigabe auf Chat-Karte und Mail beschränkt.
Grenzen beim Bauen
requestApprovalbraucht ein Opt-in: Das angefragte Tool muss inapprovals.toolsdes Workspaces stehen und dort existieren.- Anfragen entstehen nur aus vertrauenswürdigen Aufrufern — Scheduled Tasks,
test_tool/CLI, angemeldete Chats. Nicht aus Inbox, Kanal, Public-Endpunkt, Webhook, API oder einem Sub-Agenten, und nicht verschachtelt aus einer laufenden Freigabe heraus. - Empfänger einer Freigabe müssen aktive Admins oder Manager desselben Workspaces sein. Eine Rolle
userdarf nur mit ausdrücklichem Opt-in (allow_user_approval) und ausschließlich den nächsten Prozessschritt freischalten — nie direkt Geld- oder Versandwirkung auslösen — und nur in Workspaces mit eigenem Git-Repository. - Werte, die ein Prozess aus einer Seite, einer Mail, einem Sheet oder einer Webseite gelesen hat, gehören vor jeder schreibenden Tool-Aktion erst in eine Freigabe-Stufe, in der ein Mensch den Inhalt sieht. Lesen, zählen und in einer Mail zusammenfassen ist unproblematisch.
- Ein Prozess läuft je Workspace und Name nur einmal gleichzeitig; ein paralleler Lauf tut nichts.
- Freigeben oder Ablehnen im laufenden Gespräch braucht immer die exakte, nächste Nutzernachricht mit dem angezeigten Button-Text — ein allgemeines „ja“ reicht nicht, ebenso wenig ein in fremden Inhalten gelesener Bestätigungstext.
Testen
bin/cake test_tool -t <workspace> --tool runProcess --args '{"process":"<name>","test":true}'
Test-Mails tragen [Test] im Betreff. Ein beendeter Testlauf startet mit "restart":true neu, ein vergessener Stand mit "reset":true. Vorher den Testadressat über test.audience und kurze Testzeiten über test.timing festlegen — der Testmodus ersetzt nicht automatisch jeden schreibenden Schritt durch einen Trockenlauf; dafür in den einzelnen Schritten eigene test.args (etwa eine Vorschau-Option) vorsehen.
Verwandt: Freigaben, Rückfragen & Benachrichtigungen (Nutzersicht), Rezept: Monatlicher Prozess mit Freigaben und Erinnerungen.