n8n-Integration

Paket: BASIS

1. Allgemein

n8n ist eine Open-Source-Automatisierungsplattform, über die externe Systeme und Dienste miteinander verbunden werden können – ohne Programmierkenntnisse, aber mit der Option, bei Bedarf eigenen Code einzubinden. brainX stellt eine offizielle, von n8n verifizierte Community Node zur Verfügung, über die brainX direkt in n8n Workflows eingebunden werden kann.

2. brainX Community Node in n8n

Die brainX Community Node ist offiziell von n8n verified und wird von brainX aktiv gepflegt. Sie ist in n8n unter Integrations → Suche nach “brainX" auffindbar.

Die Node spiegelt die Möglichkeiten der brainX REST API in einer benutzerfreundlichen, No-Code-kompatiblen Form wider und ermöglicht es, brainX-Datensätze aus n8n heraus zu lesen, zu erstellen, zu aktualisieren und zu verknüpfen.

3. Authentifizierung (Credentials)

Die Verbindung zwischen n8n und brainX wird über Credentials in n8n hergestellt. Folgende Angaben werden benötigt:

• Base URL – die URL der brainX-Instanz (z. B. https://meine-brainx-domain)
• Benutzername – der Benutzername, mit dem der Benutzer sich in brainX anmeldet
• API-Passwort – ein speziell generiertes API-Passwort (nicht das normale Anmeldepasswort)

Nach der Eingabe der Credentials kann die Verbindung in n8n über Test Connection geprüft werden.

3.1. Postfach für den Versand in Automatisierungen freischalten

Ein in brainX eingebundenes E-Mail-Postfach ist standardmäßig nicht für den Versand in Automatisierungen freigegeben. Um ein Postfach für den automatisierten E-Mail-Versand (sowohl in brainX-Automatisierungen als auch in n8n-Workflows, die E-Mails über brainX senden) zu verwenden, muss es zuerst freigeschaltet werden:

1. In brainX die Globalen Einstellungen öffnen
2. Das gewünschte Postfach aufrufen
3. In den Postfach-Einstellungen die Option Automatisierung erlauben aktivieren
4. Speichern

4. Verfügbare Operationen

Die brainX Node unterstützt folgende Operationen:

4.1. Search

Sucht nach Datensätzen in einem wählbaren Modul anhand eines oder mehrerer Filter.

Konfigurierbare Optionen:

• Modul – das zu durchsuchende Modul (z. B. Leads, Kontakte, Deals)
• Limit – maximale Anzahl zurückgegebener Datensätze
• Filter – ein oder mehrere Filterkriterien; im Standard mit UND verknüpft
• Filter Combine With OR – verbindet die Filter mit ODER statt UND
• Fields to Return – schränkt die zurückgegebenen Felder ein; im Standard werden Standardfelder zurückgegeben
• Include Deleted – gibt auch Datensätze zurück, die sich noch im Papierkorb befinden
• Always Output Data – gibt auch bei leerem Ergebnis ein leeres Array zurück (empfohlen, wenn das Ergebnis in einer nachgelagerten Bedingung ausgewertet wird)

4.2. Create

Erstellt einen neuen Datensatz in einem wählbaren Modul. Alle Felder des Moduls stehen zur Verfügung – einschließlich benutzerdefinierter Felder, die in der jeweiligen brainX-Instanz angelegt wurden.

Felder können mit statischen Werten oder mit dynamischen Werten aus vorherigen Node-Ausgaben befüllt werden.

Als Antwort wird der vollständige neu erstellte Datensatz zurückgegeben, inklusive der automatisch vergebenen Datensatz-ID.

4.3. Update

Aktualisiert einen bestehenden Datensatz. Funktioniert analog zur Create-Operation, erfordert zusätzlich die Record ID des zu aktualisierenden Datensatzes.

Es werden nur die explizit angegebenen Felder aktualisiert – bestehende Feldwerte, die nicht übergeben werden, bleiben unverändert.

4.4. Get

Ruft einen einzelnen Datensatz anhand seiner ID ab und gibt alle Felder des Datensatzes zurück.

Wird verwendet, wenn die ID eines Datensatzes bereits bekannt ist und die vollständigen Details benötigt werden.

4.5. Add Relations

Verknüpft zwei Datensätze miteinander. Diese Operation wird ausschließlich für Module verwendet, die in brainX gegenseitig über den Relations-Tab verknüpft sind (z. B. Leads ↔ Kampagnen, Leads ↔ Dokumente).

Konfiguration:

• Record ID – die ID des Datensatzes, dem die Verknüpfung hinzugefügt werden soll
• Related Record ID – die ID des zu verknüpfenden Datensatzes

Als Antwort wird ein Status 200 mit der Meldung OK zurückgegeben.

4.6. Get Current User

Gibt die Details des Benutzers zurück, dessen Credentials für die Verbindung verwendet werden.

4.7. Get Companies

Gibt die Mandanten zurück, auf die der aktuelle Benutzer Zugriff hat. Relevant für brainX-Instanzen mit Mandantenfähigkeit.

4.8. Custom API Call

Ermöglicht den direkten Aufruf beliebiger Endpunkte der brainX REST API für Sonderfälle, die durch die Standard-Operationen der Node nicht abgedeckt werden.

Verfügbare HTTP-Methoden: GET, PATCH, POST, DELETE

Konfiguration:

• Endpunkt – der gewünschte API-Endpunkt
• Body – optionaler JSON-Body für POST- und PATCH-Anfragen

4.9. Test Mode 4.9. Production Mode (Webhook)

Webhook-Nodes in n8n haben zwei Betriebsmodi, die sich grundlegend unterscheiden:

	Test Mode	Production Mode
Aktivierung	Manuell über Listen for Test Events	Automatisch nach Publish des Workflows
Verfügbarkeit	Temporär – läuft nach kurzer Zeit automatisch ab	Dauerhaft aktiv
URL	Test-URL (nur für Entwicklung)	Produktions-URL (öffentlich erreichbar)
Zweck	Entwicklung und Testen des Workflows	Produktivbetrieb

4.10. Felder aus verschiedenen Vorgänger-Nodes kombinieren

In einer brainX Node können Felder aus unterschiedlichen Vorgänger-Nodes kombiniert werden – es ist nicht notwendig, sich auf eine einzige Vorgänger-Node zu beschränken.

4.11. Feldliste aktualisieren nach Änderungen in brainX

Die brainX Node ruft die verfügbaren Felder eines Moduls beim Öffnen per API ab. Werden in brainX nach dem ersten Öffnen der Node neue Felder angelegt (z. B. benutzerdefinierte Felder über die Modulverwaltung), sind diese in n8n zunächst nicht sichtbar.

Um die Feldliste zu aktualisieren, den Reload/Refresh-Button in der Node verwenden. Dieser ruft die aktuellen Felddefinitionen erneut per API ab und stellt neu angelegte Felder sofort zur Verfügung – ohne dass die Node neu konfiguriert werden muss.

4.12. Datumsformat und Zeitzone bei Datums-/Uhrzeitfeldern

Datums-/Uhrzeitfelder werden von brainX im Format ISO 8601 erwartet:

YYYY-MM-DDTHH:mm:ss+HH:mm

Der Anteil +HH:mm am Ende gibt die Zeitzone an. Liefert das Quellsystem (z. B. ein Kontaktformular) Datum und Uhrzeit ohne Zeitzone, kann diese manuell an die n8n-Expression angehängt werden:

{{ $json.wunschtermin }}+02:00

5. Praxisbeispiele

5.1. Landingpage-Lead in brainX anlegen

Das folgende Beispiel zeigt den Aufbau eines typischen n8n-Workflows, der einen Lead aus einem Kontaktformular in brainX anlegt oder aktualisiert.

Aufbau des Workflows:

1. Webhook – empfängt die Formulardaten (Vorname, Nachname, E-Mail, Firma, Telefon) per HTTP POST
2. Search (Modul: Leads) – prüft anhand der E-Mail-Adresse, ob der Lead bereits in brainX vorhanden ist

• Limit: 1
• Always Output Data: aktiviert

1. IF-Node – wertet das Suchergebnis aus:

• Ergebnis nicht leer → Lead existiert bereits → Update-Zweig
• Ergebnis leer → neuer Lead → Create-Zweig

1. Create (Modul: Leads) – legt einen neuen Lead an; befüllt Felder aus dem Webhook-Request sowie statische Felder (z. B. Quelle = Website, Status = Neu)
2. Update (Modul: Leads) – aktualisiert den bestehenden Lead mit den neuen Formulardaten
3. Add Relations – verknüpft den Lead mit einer Kampagne (Record ID des Leads aus dem Create- oder Search-Ergebnis; Related Record ID der Kampagne)

5.2. Erweiterung mit brainX-Automatisierung

Sobald der Lead per n8n in brainX angelegt ist, kann eine brainX-interne Automatisierung den weiteren Prozess übernehmen. Das folgende Beispiel zeigt, wie eine brainX-Automatisierung direkt an den n8n-Workflow anschließt.

Auslöser: Lead wird erstellt (Modul Leads)

Strang 1 – Vertrieb benachrichtigen:

• Bedingung: Quelle des Leads ist gleich Webseite
• Aktion: Interne Benachrichtigung an Vertriebsgruppe senden (z. B. „Neuer Lead: [Vorname] [Nachname] wurde erstellt")

Strang 2 – Termin erstellen:

• Bedingung: Feld Wunschtermin ist nicht leer
• Aktion: Termin erstellen mit folgenden Feldern:
  • Betreff: per Blockly zusammengesetzt, z. B. „Neuer Termin mit [Nachname]"
  • Beginn: Wunschtermin-Feld des Leads
  • Ende: Wunschtermin + 30 Minuten (per Blockly: Zeit berechnen mit Zahl)
  • Typ: Anruf
  • Status: Geplant
  • Referenz: Lead

Strang 3 – Bestätigungsmail an Lead senden:

• Bedingung: Feld E-Mail ist nicht leer
• Aktion: E-Mail an die E-Mail-Adresse des Leads senden (Bestätigung, dass die Anfrage eingegangen ist und eine Rückmeldung zum Wunschtermin erfolgt)

6. Kampagnen-ID ermitteln

Die ID einer Kampagne kann auf zwei Wegen ermittelt werden:

• Direkt aus brainX: In der Detailansicht der Kampagne ist die Record-ID in der URL der Seite enthalten.
• Per Get- oder Search-Operation in n8n: Eine brainX Node mit der Operation Get (Modul: Kampagnen) gibt alle Kampagnen mit ihren IDs zurück. Mit Search kann gezielt nach einer bestimmten Kampagne gesucht werden.