> For the complete documentation index, see [llms.txt](https://one-loop.gitbook.io/help/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://one-loop.gitbook.io/help/plattform/one-loop-plattform/automatisierung/workflows/eigenen-code-in-workflows-einsetzen.md).

# Eigenen Code in Workflows einsetzen

Mit der Aktion **Eigener Code** ergänzt du einen Workflow um eine selbst definierte Verarbeitung in JavaScript. Sie ist sinnvoll, wenn eine vorhandene Aktion die gewünschte Aufgabe nicht zuverlässig abbildet – etwa einen Wert umformen, mehrere Angaben berechnen oder Daten für einen späteren Schritt vorbereiten.

Die Aktion ist ein fortgeschrittenes Werkzeug. Prüfe zuerst, ob eine vorhandene Aktion, eine Wenn/Dann-Verzweigung oder ein Formatierer dieselbe Aufgabe einfacher, verständlicher und wartbarer lösen kann.

## Das Ergebnis: Eingaben werden zu klaren Ausgaben

Ein Code-Schritt verarbeitet bewusst ausgewählte Werte aus vorherigen Workflow-Schritten und gibt ein klar benanntes Ergebnis zurück.

1. Du wählst die benötigten Workflow-Werte aus.
2. Du gibst jedem Wert einen eindeutigen Schlüssel.
3. Der JavaScript-Code verarbeitet diese Eingaben.
4. Er gibt ein Objekt oder eine Liste von Objekten zurück.
5. Nach einem erfolgreichen Test kann ein späterer Workflow-Schritt die Ausgabe verwenden.

Stell dir die Eingaben wie beschriftete Schubladen vor. Ein Schlüssel wie **email** enthält die E-Mail-Adresse. Im Code erreichst du diese Eingabe über **inputData.email**. Gibt der Code ein Feld **emailDomain** zurück, kann ein folgender Schritt genau dieses Feld verwenden.

> **Wichtig:** Ohne erfolgreichen Test steht die Ausgabe nicht für spätere Workflow-Schritte bereit. Teste daher zuerst den Code und anschließend den vollständigen Workflow.

## Wann eigener Code passt – und wann nicht

| Dein Ziel                                                            | Der sichere Weg                                                        |
| -------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| Ein Kontaktfeld mit einem vorhandenen Wert ändern                    | Aktion zum Aktualisieren eines Kontaktfelds nutzen                     |
| Nach einem Tag, Datum oder Feldwert entscheiden                      | Wenn/Dann-Verzweigung nutzen                                           |
| Text, Zahl oder Datum mit vorhandener Aktion umformen                | Zuerst den passenden Formatierer prüfen                                |
| Mehrere Werte nach einer eigenen Regel zusammenführen oder berechnen | Eigener Code kann passen                                               |
| Ein Ergebnis aus einem externen Dienst aufbereiten                   | Eigener Code kann nach gründlicher Datenprüfung passen                 |
| Eine ganze Automatisierung erzeugen                                  | Nicht diese Aktion: Eigener Code bearbeitet nur einen Workflow-Schritt |

Wenn dein Team den Schritt später nicht erklären, prüfen und bei einer Änderung sicher testen kann, ist eine einfachere Lösung meist besser.

## Vor dem Start: Zweck, Eingabe und Ergebnis festlegen

Schreibe den Zweck des Schritts zuerst in einem Satz auf. Zum Beispiel: „Lies den vollständigen Namen aus dem Formular und gib Vor- und Nachname getrennt zurück.“

Beantworte dann diese Fragen:

* Welche Werte braucht der Code wirklich?
* Aus welchem vorherigen Schritt kommen sie?
* Können sie leer sein?
* Welches Format haben sie?
* Welche Ausgabefelder braucht der nächste Schritt?
* Was soll bei einem fehlenden oder unpassenden Wert passieren?
* Welche Information darf den Workflow auf keinen Fall verlassen?

Diese Vorbereitung verhindert die meisten Fehler. Ein Code kann technisch laufen und trotzdem unpassende Ergebnisse liefern, wenn Eingaben falsch zugeordnet oder Ausgaben unklar sind.

## Aktion Schritt für Schritt einrichten

1. Öffne **Automatisierung > Workflows** und bearbeite einen Entwurf.
2. Klicke an der gewünschten Stelle auf das **Pluszeichen**, um eine Aktion hinzuzufügen.
3. Suche nach **Eigener Code** und wähle die Aktion.
4. Gib der Aktion einen klaren Namen, etwa **E-Mail-Domain ermitteln**.
5. Prüfe, dass die Sprache auf **JavaScript** steht.
6. Füge unter **Eigenschaft in Code aufnehmen** die benötigten Eingaben an.
7. Vergib pro Eingabe einen kurzen, eindeutigen Schlüssel.
8. Ordne jedem Schlüssel den richtigen Wert aus einem vorherigen Workflow-Schritt zu.
9. Schreibe die Verarbeitung im Code-Editor.
10. Formatiere den Code bei Bedarf über **Code formatieren**.
11. Führe **Code testen** mit realistischen Beispielwerten aus.
12. Prüfe die Rückgabe und speichere die Aktion.
13. Teste anschließend den vollständigen Workflow.
14. Veröffentliche den Workflow erst, wenn Eingabe, Ausgabe und Folgeaktion zusammenpassen.

Platziere den Code erst dann im Workflow, wenn alle benötigten Werte davor wirklich verfügbar sind. Ein Wert aus einem späteren Schritt kann hier noch nicht verarbeitet werden.

## Die sichtbaren Felder richtig verwenden

| Feld oder Bedienelement           | Bedeutung                                                   | Sichere Verwendung                                                                  |
| --------------------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| **Aktionsname**                   | Beschriftung des Schritts im Workflow.                      | Benenne Ergebnis und Zweck, nicht nur „Code“.                                       |
| **Sprache**                       | Legt die Programmiersprache des Schritts fest.              | Der bestätigte Ablauf verwendet JavaScript.                                         |
| **Eigenschaft in Code aufnehmen** | Übergibt einen Workflow-Wert an den Code.                   | Lege nur Werte an, die wirklich verarbeitet werden sollen.                          |
| **Schlüssel**                     | Name, über den der Code auf eine Eingabe zugreift.          | Nutze einfache Namen ohne Leerzeichen, etwa **email**, **phone** oder **fullName**. |
| **Wert**                          | Die konkrete Eingabe aus dem Workflow oder ein fester Wert. | Prüfe Datenquelle und Format vor dem Test.                                          |
| **Eigenschaft hinzufügen**        | Fügt eine weitere Eingabezeile hinzu.                       | Weniger, klar benannte Werte sind leichter zu prüfen.                               |
| **Code**                          | Die eigentliche Verarbeitung.                               | Er muss erwartete Eingaben verwenden und eine klare Ausgabe zurückgeben.            |
| **Code formatieren**              | Verbessert Einrückung und Lesbarkeit.                       | Vor der Prüfung anwenden; es ersetzt keinen fachlichen Test.                        |
| **Code testen**                   | Führt den Schritt mit Testwerten aus.                       | Erst bei erfolgreichem Test die Ausgabe in weiteren Schritten nutzen.               |

## Eingabewerte sauber vorbereiten

Jede Eingabe besteht aus einem **Schlüssel** und einem **Wert**.

Der Schlüssel ist der Name im Code. Der Wert kommt aus dem Workflow. Möchtest du zum Beispiel eine E-Mail-Adresse verarbeiten, nennst du den Schlüssel **email** und ordnest ihm die E-Mail-Adresse des Kontakts zu. Der Code liest ihn dann als **inputData.email**.

Verwende einfache Schlüssel ohne Leerzeichen oder Sonderzeichen. Gute Beispiele sind:

* **email**
* **phone**
* **fullName**
* **appointmentDate**
* **sourceName**

Prüfe jede Eingabe mit diesen Fragen:

1. Woher kommt der Wert?
2. Ist er vor dem Code-Schritt wirklich vorhanden?
3. Kann er leer sein?
4. Welches Format erwartet der Code?
5. Was soll bei einem leeren oder ungültigen Wert passieren?

Viele Fehler entstehen nicht durch die Berechnung, sondern durch eine falsche Zuordnung oder einen fehlenden Wert.

## Ausgaben so gestalten, dass der nächste Schritt sie versteht

Der Code muss sein Ergebnis als Objekt oder als Liste von Objekten zurückgeben. Praktisch bedeutet das: Das Ergebnis besteht aus klar benannten Feldern.

Ein überschaubares Ergebnis könnte diese Felder liefern:

* **firstName**
* **lastName**
* **emailDomain**

Nach einem erfolgreichen Test stehen diese Rückgabefelder für passende spätere Schritte zur Verfügung. Vergleiche Namen, Struktur und Inhalte genau mit dem, was der nächste Schritt erwartet.

Achte dabei auf drei Regeln:

* Die Feldnamen müssen exakt stimmen.
* Die Ausgabe braucht eine klare, vorhersehbare Struktur.
* Gib nur die Werte zurück, die der nächste Schritt tatsächlich benötigt.

Kleine, eindeutige Ausgaben sind leichter testbar und weniger fehleranfällig.

## Erst den Code testen, dann den ganzen Workflow

Der Code-Test zeigt, ob der Schritt läuft und die erwartete Ausgabe zurückgibt. Bei Erfolg erscheint **Test erfolgreich**; bei einem Fehler zeigt die Oberfläche **Test fehlgeschlagen**.

### Test mit Eingabeeigenschaften

1. Öffne **Code testen**.
2. Trage in der Testeinrichtung passende Beispielwerte ein.
3. Teste einen normalen Fall.
4. Teste einen leeren Wert.
5. Teste einen unpassenden Wert, etwa eine fehlerhafte E-Mail-Adresse.
6. Prüfe, ob alle Rückgabefelder korrekt heißen und die erwarteten Inhalte haben.
7. Wiederhole den Test nach jeder Änderung am Code.

### Vollständigen Workflow testen

Ein erfolgreicher Code-Test reicht nicht. Die Testoberfläche übergibt nicht alle individuellen Werte automatisch. Teste deshalb immer zusätzlich den echten Ablauf:

1. Verwende einen sicheren Testkontakt oder Testdatensatz.
2. Sorge dafür, dass die vorherigen Schritte die erwarteten Eingaben liefern.
3. Prüfe den Code-Schritt im Ausführungsverlauf.
4. Öffne den nächsten Schritt und kontrolliere, ob er die richtige Ausgabe erhält.
5. Prüfe die eigentliche Folgeaktion, zum Beispiel eine Nachricht oder Feldaktualisierung.

Nur dieser End-to-End-Test zeigt, ob Datenquelle, Code, Ausgabe und Folgeaktion zusammenarbeiten.

## Fehler finden: Konsole und Ausführungsprotokoll

Der Code kann Protokollausgaben über **console.log** erfassen. Das hilft dabei, Zwischenschritte zu verstehen. Gib dort jedoch keine vertraulichen Inhalte aus.

Wenn ein Test oder ein echter Workflow-Lauf unerwartet endet:

1. Öffne den betreffenden Workflow-Durchlauf.
2. Wähle **Weitere Details**.
3. Prüfe die tatsächlich übergebenen Eingaben.
4. Vergleiche sie mit den Schlüsseln im Code.
5. Prüfe Fehlermeldung und Ausgabestruktur.
6. Korrigiere nur eine Ursache pro Testlauf.
7. Wiederhole zuerst den Code-Test und dann den gesamten Workflow-Test.

Typische Ursachen sind ein falsch geschriebener Schlüssel, ein leerer Wert, ein unerwartetes Format oder eine Ausgabe, die nicht als Objekt oder Objektliste aufgebaut ist.

## Externe HTTP-Anfragen nur mit klarer Datenprüfung

Die Aktion kann Anfragen an externe Dienste vorbereiten. Über **HTTP-Anfrage** stehen unter anderem GET, POST, PUT, PATCH, DELETE, HEAD und OPTIONS als Ausgangspunkt zur Verfügung.

Das ist leistungsfähig, aber sensibel: Eine externe Anfrage kann Kontakt- oder Workflow-Daten an ein anderes Ziel übertragen. Prüfe deshalb vor dem Speichern:

* Welche Daten gehen an welches Ziel?
* Ist jede übertragene Angabe wirklich notwendig?
* Stimmen Zieladresse, Methode, Kopfzeilen und Inhalt?
* Wie werden vertrauliche Angaben geschützt?
* Was geschieht bei einem nicht erreichbaren Dienst?
* Welche Antwortfelder darf der nächste Workflow-Schritt nutzen?

Teste externe Anfragen zuerst mit sicheren Beispieldaten. Baue keine Zugangsdaten oder vertraulichen Angaben ungeschützt direkt in den Code ein. Wenn Ziel oder Datenverarbeitung nicht klar dokumentiert sind, nutze die Anfrage nicht im aktiven Workflow.

## Praxisbeispiel: Namen für eine Ansprache aufteilen

Ein Formular übergibt den vollständigen Namen eines Kontakts. Für eine spätere Nachricht sollen Vor- und Nachname getrennt bereitstehen.

1. Der Workflow startet nach der Formulareinsendung.
2. Die Aktion **Eigener Code** erhält die Eingabe **fullName**.
3. Der Wert kommt aus dem Namensfeld des Formulars.
4. Der Code liefert **firstName** und **lastName** zurück.
5. Bei nur einem Namen bleibt **lastName** leer.
6. Der Code-Test prüft einen vollständigen Namen, einen einzelnen Namen und einen leeren Wert.
7. Eine spätere Nachricht verwendet nur **firstName**.
8. Ein vollständiger Workflow-Test kontrolliert die tatsächliche Ansprache.

Dieses kleine Beispiel zeigt den kompletten Weg von Eingabe über Verarbeitung und Test bis zur Verwendung der Ausgabe. Beginne mit einer solchen überschaubaren Aufgabe, bevor du komplexere Abläufe aufbaust.

## Häufige Fehler und die passende Lösung

| Beobachtung                                            | Wahrscheinliche Ursache                                                      | Sichere Lösung                                                     |
| ------------------------------------------------------ | ---------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| Ein späterer Schritt findet kein Ausgabefeld.          | Der Code wurde nicht erfolgreich getestet oder gibt das Feld nicht zurück.   | Code testen und Feldnamen exakt vergleichen.                       |
| Der Code erhält keinen erwarteten Wert.                | Die Eigenschaft ist falsch zugeordnet oder der Wert steht noch nicht bereit. | Datenquelle, Workflow-Reihenfolge und Schlüssel prüfen.            |
| Der Test funktioniert, der echte Ablauf aber nicht.    | Individuelle Werte werden im Code-Test nicht vollständig übergeben.          | Beispielwerte verwenden und zusätzlich den ganzen Workflow testen. |
| Der nächste Schritt erhält ein unbrauchbares Ergebnis. | Ausgabeformat oder Feldname stimmt nicht.                                    | Klare Objektstruktur zurückgeben und die Folgeaktion prüfen.       |
| Der Code ist schwer nachvollziehbar.                   | Zu viele Aufgaben oder unklare Namen liegen in einem Schritt.                | Schritt aufteilen, Namen präzisieren und Code formatieren.         |
| Eine externe Anfrage schlägt fehl.                     | Ziel, Methode, Daten oder Antwort passen nicht zusammen.                     | Mit sicheren Beispieldaten testen und Ausführungsdetails prüfen.   |

## Grenzen, die du kennen solltest

* Eigener Code verarbeitet nur einen Workflow-Schritt und erstellt keinen vollständigen Ablauf.
* Der Code kann nur Werte verwenden, die vorher bereits verfügbar und bewusst als Eingabe angelegt sind.
* Die Ausgabe muss als Objekt oder Objektliste zurückkommen.
* Ein erfolgreicher Code-Test ist Voraussetzung für eine nutzbare Ausgabe in späteren Schritten.
* Externe HTTP-Anfragen können Daten weitergeben und brauchen eine zusätzliche Sicherheits- und Fehlerprüfung.
* Jede Änderung am Code wird zuerst im Code-Test und danach im vollständigen Workflow geprüft.

Wenn du den Schritt klein hältst, Eingaben und Ausgaben klar benennst und jeden Fall testest, erweitert eigener Code deinen Workflow gezielt, ohne ihn unverständlich zu machen.