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.

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

5. Praxisbeispiel: 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)

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.