Einen Workspace aus einer Vorlage bereitstellen

Eine Workflow-Vorlage ist ein fertiger Workflow, den du in ein Projekt materialisieren kannst, statt den Graphen selbst zu zeichnen. Zwei ausgelieferte Vorlagen decken die üblichen Eingangsformen ab:

Slug	Was sie tut	Wodurch sie feuert
mail_intake	Nimmt eingehende Mail aus einem Postfach auf und startet je Nachricht einen Task	IMAP-Trigger auf einer Postfach-Ressource
scan_intake	Durchsucht eine Dokumentbibliothek nach neuen Dateien und startet je Dokument einen Task	Zeitplan (standardmäßig täglich)

Die Management-API legt beide für dich an — ein Postfach anzuschließen ist damit eine einzige Anfrage statt einer Handmontage im Builder.

Hinweis

Diese Seite beschreibt den deklarativen Weg (Management-API). Du kannst eine Vorlage auch interaktiv beim Anlegen eines Workflows wählen — es sind dieselben Vorlagen wie in der Vorlagen-Auswahl.

Mail-Eingang bereitstellen

1. Das Postfach als Ressource deklarieren.

   Der name der Ressource ist die Kennung, auf die du dich später beziehst — ein eigenes Schlüsselfeld gibt es nicht, und die Referenz unten muss den Namen zeichengenau treffen. Wähle einen Namen, den du gern noch einmal tippst. Das Passwort ist schreibgeschützt: ein Lesen des Workspace-Zustands gibt es nie zurück.

   {
     "resources": [
       {
         "name": "workspace-mailbox",
         "kind": "imap",
         "config": {
           "host": "mail.example.com",
           "port": 993,
           "username": "intake@example.com"
         },
         "secret": "das-postfach-passwort"
       }
     ]
   }

   Achtung

   Ein secret einer Ressource wird genau so gespeichert, wie du es sendest. Es ist keine ${{ secrets.… }}-Referenzstelle — nur credentials[].credential_data löst diese Form auf, und zwar bei der Verwendung. Setze den echten Wert vor der Anfrage aus deinem eigenen Geheimnisspeicher ein; das Senden der Markierung wird mit 400 abgelehnt statt als Passwort gespeichert, mit dem sich niemand anmelden kann.

2. Den Workflow aus der Vorlage materialisieren.

   Der IMAP-Trigger bindet das Postfach über seine Id, schreibe also die Referenzform ${{ resources.<name>.id }} — sie wird gegen die Ressource aus Schritt 1 aufgelöst, in derselben Anfrage, du fügst also nie eine UUID ein.

   {
     "workflow_templates": [
       {
         "key": "mail-intake",
         "project_key": "my-project",
         "template": "mail_intake",
         "name": "Mailbox Intake",
         "config": {
           "mailbox_resource_id": "${{ resources.workspace-mailbox.id }}"
         }
       }
     ]
   }

   Jede andere Lücke der Vorlage hat einen funktionierenden Standardwert, diese eine Zeile genügt also für einen laufenden Mail-Eingang:

   config-Schlüssel	Standard	Was er füllt
   mailbox_resource_id	(keiner)	Das abzufragende Postfach. Ohne ihn wird der Workflow ohne Trigger materialisiert und du hängst später einen an.
   mailbox_folder	INBOX	Der Ordner, den der Trigger abfragt.
   agent_type	claude	Der Agent, der jede Nachricht sichtet und bearbeitet.
   mailbox_label	the connected mailbox	Wie der Prompt dieses Postfach benennt.
   intake_purpose	Ein allgemeiner Satz	Wofür dieses Postfach da ist — der Maßstab der Sichtung.
   approval_note	Ein allgemeiner Satz	Zusätzlicher Hinweis für die freigebende Person.
   handling_instructions	Hausregeln zum Umgang mit Zugangsdaten	Wie die freigegebene Handlung auszuführen ist.

3. Beide Blöcke in einer Anfrage senden.

   curl -X PUT \
     -H "Authorization: Bearer $SUPACLOUD_MANAGEMENT_TOKEN" \
     -H "Content-Type: application/json" \
     --data @workspace-state.json \
     https://app.example.com/api/management/v1/workspaces/my-workspace/state

   Die Blöcke werden in fester Reihenfolge angewandt — Ressourcen, dann Projekte, dann Workflow-Vorlagen, dann Trigger und Zeitpläne. Was ein späterer Block referenziert, existiert also bereits.

Dokument-Scan bereitstellen

Die Scan-Vorlage arbeitet gegen eine Dokumentbibliothek statt gegen ein Postfach, und sie bindet diese Bibliothek über den blanken Namen — nicht über die Id. Ihre beiden Programmschritte erreichen die Bibliothek über eine Bindung, die per Ressourcennamen aufgelöst wird; schreibe also den Namen selbst, genau wie deklariert:

{
  "resources": [
    {
      "name": "document-library",
      "kind": "seafile_webdav",
      "config": {
        "base_url": "https://seafile.example.com/seafdav",
        "user": "scanner@example.com",
        "library_path": "/Documents",
        "repo_name": "Documents"
      },
      "secret": "das-seafile-passwort"
    }
  ],
  "workflow_templates": [
    {
      "key": "scan-intake",
      "project_key": "my-project",
      "template": "scan_intake",
      "config": {
        "library_resource": "document-library",
        "scan_folder": "/Inbox",
        "archive_folder": "/Archive"
      }
    }
  ]
}

config-Schlüssel	Standard	Was er füllt
library_resource	scans	Der Name der zu durchsuchenden seafile_webdav-Ressource. Ein Name, den keine Ressource trägt, lässt die Anfrage scheitern.
scan_folder	/Inbox	Der Ablageordner, der durchsucht wird.
archive_folder	/Archive	Wohin ein bestätigter Stapel verschoben wird.
file_extensions	.pdf,.jpg,.jpeg,.png,.tif,.tiff	Welche Dateien als Dokument zählen.
lookback_minutes	1440	Wie weit ein Durchlauf zurückschaut.
review_note	Ein allgemeiner Satz	Zusätzlicher Hinweis für die bestätigende Person.

Die Bibliotheks-Ressource trägt zwei Ortsangaben, und die Scan-Vorlage braucht beide Arten von Information:

config-Feld	Pflicht	Wer es liest
base_url	ja	Der WebDAV-/Seafile-Host. Er ist zugleich der einzige Host, den die beiden Programmschritte erreichen dürfen.
user	ja	Das Seafile-Konto, mit dem sich die Schritte anmelden.
library_path	ja	Der WebDAV-Pfad der Bibliothek; die Ressourcenart seafile_webdav verlangt ihn.
repo_name	eines von beiden	Der Anzeigename der Bibliothek. Die Schritte schlagen die Bibliothek darüber nach.
repo_id	eines von beiden	Die Id der Bibliothek, falls du sie schon kennst. Ist sie gesetzt, wird repo_name nicht herangezogen.
web_base_url	nein	Der Seafile-Web-Host, falls er von base_url abweicht.

Gib entweder repo_name oder repo_id an. Ohne beides wird die Ressource zwar angenommen — der Ressourcenart sind beide Felder optional —, aber der erste Durchlauf scheitert mit Seafile library is not resolvable by name: ''.

Achtung

Die beiden Vorlagen nehmen ihre Ressource in unterschiedlicher Form, weil sie sie unterschiedlich nutzen: mail_intake braucht die Id des Postfachs (schreibe ${{ resources.<name>.id }}), scan_intake den Namen der Bibliothek (schreibe ihn blank). Eine ${{ resources.… }}-Referenz in library_resource wird zu einer UUID aufgelöst, die zu keinem Ressourcennamen passt — die Anfrage scheitert.

Da eine Dokumentbibliothek nicht von sich aus benachrichtigt, läuft diese Vorlage über einen Zeitplan statt über einen Trigger. Die Taktung ergänzt du mit einem workflow_schedules-Eintrag, der den materialisierten Workflow benennt — Scan intake, sofern du am Vorlagen-Eintrag kein name überschreibst:

{
  "workflow_schedules": [
    {
      "key": "scan-sweep",
      "project_key": "my-project",
      "workflow": "Scan intake",
      "cadence": "daily",
      "timezone": "Europe/Berlin",
      "next_run_at": "2026-09-01T06:00:00Z"
    }
  ]
}

Was ein erneutes Anwenden bewirkt

Dasselbe Dokument erneut anzuwenden ist gefahrlos und tut nichts:

• Eine Vorlage, deren Workflow bereits existiert, meldet changed: false. Das Anwenden überschreibt deine Änderungen nie — sobald der Workflow materialisiert ist, gehört der Graph dir und du kannst ihn im Builder frei anpassen.
• Einen Eintrag aus dem Dokument zu entfernen löscht den Workflow nicht. Jede Liste im Workspace-Zustand ist additiv; Löschen ist immer eine ausdrückliche Handlung.
• Den Workflow umzubenennen ist gefahrlos. Der Abgleich läuft über den key, den du gewählt hast, nicht über den Anzeigenamen.

Achtung

Alles, was eine Vorlage braucht, wird geprüft, bevor irgendetwas angelegt wird. Ein unbekannter template-Slug lässt die Anfrage mit 404 scheitern; eine unbekannte Ressource — in einer ${{ resources.… }}-Referenz oder in der library_resource-Bindung von scan_intake — mit 400, unter Nennung der Ressource und des Schritts, der sie wollte. Das ist Absicht: eine Bereitstellung, die stillschweigend einen wirkungslosen Workspace erzeugt, fiele erst beim ersten echten Lauf auf — und dann ist das erneute Anwenden ein No-op, das Korrigieren des Manifests würde es also nicht mehr reparieren.

Was in einem config-Wert stehen darf

Ein config-Wert füllt genau eine Lücke in der ausgelieferten Vorlage — einen Ordner, eine Bezeichnung, einen Satz Anleitung. Die Vorlage wird zuerst als Dokument gelesen, und dein Wert wird danach in die eine Lücke gesetzt, zu der er gehört. Er bleibt damit ein Stück Text: er kann keinen Schritt hinzufügen, kein Feld umbenennen und keine zweite Lücke erreichen — egal, was in ihm steht. Ein config-Schlüssel, der keine Lücke der Vorlage benennt, füllt nichts.

Zwei Dinge kann ein Wert weiterhin nicht, und beide betreffen nicht das Dokument, sondern das, was den Wert danach liest. Beides wird geprüft, bevor irgendetwas angelegt wird; ein Wert, der daran scheitert, lässt die Anfrage mit 400 scheitern und nennt den Schlüssel:

• Das Programm der Scan-Vorlage. Ihre beiden Schritte führen ein kleines Programm gegen deine Bibliothek aus, mit deren Zugangsdaten in Reichweite, und einige Lücken sitzen im Text dieses Programms (scan_folder, archive_folder, file_extensions, lookback_minutes). Ein Wert darf dort kein " und kein \ enthalten — beides würde den Text beenden, in den er gesetzt wird.
• Eine zweite Vorlagen-Markierung. Kein Wert darf ${{ … }} enthalten. Prompts und Programmtext werden beim Lauf des Workflows erneut gefüllt, eine jetzt eingeschmuggelte Markierung würde also später gegen echte Daten aufgelöst. Einzige Ausnahme ist die Referenzform ${{ resources.<name>.id }}, die zu einer UUID aufgelöst wird, bevor der Wert die Vorlage überhaupt erreicht.

Zwei weitere Regeln runden es ab: halte jeden Wert einzeilig (ein Zeilenumbruch wird abgelehnt statt umgedeutet — längere Anleitung trägst du danach im Builder ein) und unter 8192 Zeichen.

Keine der Vorlagen wird automatisch angewandt

Neue Projekte bekommen diese Workflows nicht. Beide Vorlagen sind opt-in — über diesen Block oder die Auswahl — für bestehende Projekte ändert sich also nichts.

Verwandt

• Einen IMAP-Trigger einrichten
• Eine eigene Verbindung anlegen
• Einen Zeitplan einrichten