Action-Links

Ein Link in einer Mail führt per Klick eine einzelne, vordefinierte Tool-Aktion aus — ohne Login.

Ein Action-Link steht in einer Mail (z. B. einer Alert-Mail eines Scheduled Tasks) und führt beim Klick genau eine vordefinierte Tool-Aktion mit festen Argumenten aus — ohne dass sich der Empfänger einloggt. Klassiker: eine Lagerwarnung mit dem Link „33 Stück buchen".

Action-Links stehen damit neben Chat, Scheduled Tasks, Email-Verarbeitung und der API als fünfter Weg, ein Tool auszuführen.

#Wie es funktioniert

1. Ein Tool (typischerweise ein Scheduled Task) erzeugt den Link über $ctx['actionLink'](tool, args, ttlHours?).
2. Die Plattform legt dafür einen Einmal-Token an (gespeichert wird nur ein Hash, der Klartext steht einmalig in der Mail-URL) und liefert eine URL wie https://app.taskmonkey.de/a/<token> zurück.
3. Klickt der Empfänger den Link, sieht er nur eine Bestätigungsseite — „33 Stück auf B0355 buchen?" mit einem Ausführen-Button. Der Klick (GET) führt nichts aus. Das ist Absicht: Mail-Scanner und Vorschau-Clients öffnen Links automatisch, ein ausführender GET wäre ein scharfer Fehlschuss.
4. Erst der Klick auf den Button (POST) führt das Tool genau einmal aus. Ein zweiter Klick, ein abgelaufener Link oder ein manipulierter Link ändert nichts mehr.

#Ein Tool freigeben

Ein Tool ist für Action-Links fail-closed gesperrt, bis die Config es explizit freigibt:

'updateStock' => [
    'action_link' => true,
    // optional: Anzeigetext der Bestätigungsseite, {platzhalter} aus den Args
    'action_link_summary' => '{delta} Stück auf {sku} buchen?',
    'parameters' => [ /* ... */ ],
    'handler' => [\App\Tooling\JtlTools::class, 'updateStock'],
],

Ohne action_link: true lehnt die Plattform jeden Action-Link auf dieses Tool ab — auch mit einem sonst gültigen Token. Der Flag wird zweimal geprüft: einmal beim Erzeugen des Links, einmal erneut beim Klick (die Config kann sich innerhalb der Gültigkeitsdauer des Links geändert haben).

#Einen Link erzeugen

Aus einem Handler (z. B. in einem Scheduled Task):

'handler' => function (array $results, array $args, array $ctx): array {
    $link = $ctx['actionLink']('updateStock', [
        'sku' => $sku,
        'delta' => 33,
        'note' => "Action-Link Lagerwarnung {$sku}",
    ], 72); // TTL in Stunden, Default 72

    if ($link !== '') {
        $ctx['tool']('sendAdminEmail', [
            'subject' => "Lagerwarnung {$sku}",
            'lines' => ["33 Stück buchen: {$link}"],
            'recipients' => $admins,
        ]);
    }

    return ['success' => true];
},

$ctx['actionLink'] liefert nur die URL zurück (oder '', wenn das Tool nicht freigegeben ist) — bewusst keine weiteren Daten oder Nebenwirkungen Richtung Tool-Code. Die Argumente kommen ausschließlich aus diesem Aufruf; niemand kann sie später über die URL oder das Formular verändern.

#Sicherheit

• Einmal-Token, nur Hash in der DB. Wie ein Passwort-Reset-Link: der Klartext steht nur in der Mail-URL, die Plattform speichert sha256(token).
• GET führt nie aus. Nur eine Bestätigungsseite.
• Atomarer Claim. POST markiert den Link als „benutzt" nur, wenn er noch offen und nicht abgelaufen ist — bei Doppelklick oder zwei geöffneten Tabs gewinnt genau einer.
• Gültigkeit. Default 72 Stunden, danach läuft der Link ab (nichts wird mehr ausgeführt).
• Fail-closed per Tool. action_link: true ist Opt-in, erneut geprüft bei der Ausführung.
• Audit. Jede Ausführung landet in task_executions mit entry_type = action_link.

#Beobachten und Debuggen

tm monitor      # Live-Stream — Action-Link-Ausführungen erscheinen mit entry_type action_link
tm logs

#Wann nicht nutzen

• Mehrstufige Aktionen oder Rückfragen — ein Action-Link führt genau ein Tool mit festen Argumenten aus, keine Konversation.
• Geld-Aktionen über dem Autonomie-Deckel eines Workspace-Mitglieds — dafür gibt es die eingeloggte Freigabe in TaskMonkey (/manage/approvals).

#Checkliste

• Ziel-Tool hat action_link: true in seiner Config
• $ctx['actionLink'](tool, args) liefert eine URL (nicht '') im Test
• Mail mit dem Link verschickt, Link öffnet die Bestätigungsseite (GET führt nichts aus)
• Klick auf „Ausführen" bucht/erledigt die Aktion, zweiter Klick zeigt „bereits eingelöst"