Bitrix24 Task-Widget: Installation und Laufzeit-Handler - n8n-Workflow

Bitrix24-Anwendungsentwickler, die ein zuverlässiges Backend für Installation und Token-Verwaltung benötigen.
Anwender, die nach ausgereiften n8n-Vorlagen für komplexe Webhook-Interaktionen suchen.
Automatisierungsspezialisten, die eigene Widgets in CRM-Umgebungen einsetzen.
Entwickler, die eine selbst gehostete Lösung für die Bitrix24-API-Anbindung suchen.

Die Entwicklung benutzerdefinierter Anwendungen für Plattformen wie Bitrix24 erfordert eine komplexe Handhabung von OAuth-Tokenn, Installations-Callbacks und der Bereitstellung dynamischer Inhalte. Dieser leistungsstarke n8n-Workflow löst diese Herausforderungen, indem er als zentrale Drehscheibe für alle Bitrix24-Ereignisse im Zusammenhang mit Ihrer benutzerdefinierten Widget-Anwendung fungiert. Der Hauptvorteil dieser n8n-Vorlage liegt in ihrer Fähigkeit, den Installations-Handshake nahtlos zu verwalten – kritische Zugriffstoken auf dem Speichermedium zu speichern – und diese gespeicherten Anmeldeinformationen dann zur Laufzeit zu nutzen, um kontextspezifische Informationen (wie Aufgabendetails) innerhalb einer Bitrix24-Aufgabenansicht-Registerkarte abzurufen und anzuzeigen.

Jedes Mal, wenn Bitrix24 eine Anfrage sendet (sei es zur Installation oder zur Widget-Anzeige), stellt diese spezifische n8n-Knoteneinrichtung eine sichere Authentifizierung und sofortige, maßgeschneiderte Antworten sicher und demonstriert so die Effizienz eines gut konzipierten n8n-Workflows.

Der gesamte Prozess beginnt mit dem festgelegten n8n-Trigger, dem Webhook-Knoten, der auf POST-Anfragen von Bitrix24 wartet.

1. Trigger und Initialisierung: Der n8n-Trigger Bitrix24 Handler empfängt das Ereignis. Der n8n-Knoten Extract Credentials analysiert sofort die eingehende JSON-Nutzlast, um die Domain, Zugriffstoken und Refresh-Token abzurufen.


2. Ereignisbestimmung: Der Code-Knoten Check Event Type analysiert die Anfrage, um zwischen einem Anwendungsinstallationsereignis (ONAPPINSTALL) und einer Laufzeit-Platzierungsanfrage (z. B. beim Anzeigen einer Aufgabe) zu unterscheiden.


3. Installationspfad: Wenn es sich um eine Installation handelt, verzweigt sich der Workflow. Wenn die Installation noch nicht abgeschlossen ist, verwendet das System den n8n-Knoten Set Settings Data, um die Token zu formatieren, wandelt sie in eine JSON-Datei um (Create Settings File) und speichert die Konfiguration mithilfe des n8n-Knotens Save Installation Settings (Read/Write File). Anschließend wird die Widget-Platzierung registriert (Register Placement HTTP Request-Knoten) und der Vorgang mit der Webhook-Antwort Installation Response abgeschlossen.


4. Laufzeitpfad (Widget-Anzeige): Wenn das Ereignis eine Laufzeitanfrage ist, ruft das System die zuvor gespeicherten Authentifizierungsdaten mithilfe der n8n-Knoten Read Installation Settings und Extract Installation Settings ab. Der Knoten Merge request data with installation settings bereitet den notwendigen Datenkontext vor.


5. Datenverarbeitung und -abruf: Der Funktionsknoten Process Settings extrahiert kontextspezifische Informationen, wie die taskId. Der Wenn-Knoten Has Valid Settings? validiert die Anmeldeinformationen. Bei Gültigkeit fragt der n8n-Knoten Get Task Data (HTTP Request) mithilfe des gespeicherten Bitrix24-Zugriffstokens die Bitrix24-API nach detaillierten Aufgabendetails ab.


6. Antwortgenerierung: Der Funktionsknoten Format Task Data wandelt die Rohaufgabendaten in strukturiertes HTML um. Schließlich sendet der n8n-Knoten Task View Response dieses HTML zurück an Bitrix24, welches es im benutzerdefinierten Task-Widget rendert. Falls die Einstellungen ungültig waren, wird stattdessen eine Error Response zurückgegeben. Diese komplexe Logik demonstriert eine leistungsstarke Anwendung eines n8n-Workflows.

Um diesen umfassenden n8n-Workflow bereitzustellen, befolgen Sie diese Schritte:

1. n8n-Workflow importieren: Kopieren Sie die bereitgestellten JSON-Daten. Navigieren Sie in Ihrer n8n-Instanz zu 'Workflows' und klicken Sie auf 'Neu'. Wählen Sie 'Aus JSON importieren' und fügen Sie den Code ein.


2. Webhook-Trigger konfigurieren: Lokalisieren Sie den n8n-Trigger-Knoten Bitrix24 Handler. Der Pfad ist auf bitrix24/widgethandler.php gesetzt. Aktivieren Sie den Workflow, um die vollständige Webhook-URL zu generieren. Diese URL muss in Ihren Bitrix24-Anwendungseinstellungen als Handler-URL für Installations- und Platzierungsereignisse registriert werden.


3. Platzhalter-Anmeldeinformationen festlegen: Der n8n-Knoten Extract Credentials enthält fest codierte Platzhalterwerte (z. B. local.67b8a796e92127.82791242). Diese werden normalerweise durch die Live-Daten von Bitrix24 während des Installations-Webhooks überschrieben, müssen aber möglicherweise angepasst werden, wenn Ihre Anwendung andere statische Client-IDs/Geheimnisse verwendet. Stellen Sie sicher, dass Ihre Bitrix24-App korrekt konfiguriert ist, um diese anfänglichen Token zu senden.


4. Dateisystemzugriff: Der Workflow verwendet den n8n-Knoten ReadWriteFile, um die Bitrix24-Authentifizierungstoken zu speichern und zu lesen. Stellen Sie sicher, dass Ihre n8n-Hostumgebung über die erforderlichen Berechtigungen für den Zugriff auf den Pfad /data/files/hotline_files/ verfügt (oder passen Sie die Variable settingsFilePath im Knoten Extract Credentials an einen für Ihre n8n-Instanz zugänglichen Ort an).


5. Aktivieren: Speichern und aktivieren Sie den n8n-Workflow. Die Automatisierung wartet nun auf Bitrix24-Ereignisse.

Bitrix24 Handler (Webhook n8n-Trigger): Der Einstiegspunkt des n8n-Workflows. Er ist so konfiguriert, dass er auf POST-Anfragen unter einem bestimmten Pfad lauscht und so die Abfolge der Operationen sowohl für Installations- als auch für Aufgabenansichtsanfragen einleitet.
Extract Credentials (Set n8n-Knoten): Essentiell für die Sicherheit. Dieser Knoten extrahiert dynamische Authentifizierungsparameter (wie accesstoken und refreshtoken), die von Bitrix24 gesendet werden, und bereitet sie für die Verwendung in nachfolgenden HTTP-Anfragen und zum Speichern im Speicher vor.
Check Event Type (Code n8n-Knoten): Ein benutzerdefinierter Skriptknoten, der den eingehenden Request Body parst, um zwischen App-Installations-Callbacks und Widget-Platzierungsereignissen zu unterscheiden, was eine entscheidende Ablaufsteuerung für den n8n-Workflow darstellt.
Is Installation? (If n8n-Knoten): Ein zentraler Logik-n8n-Knoten, der den Ablauf steuert, basierend darauf, ob die aktuelle Anfrage Teil des Anwendungsinstallationsprozesses ist (isInstallation: true).
Set Settings Data & Save Installation Settings (Set & ReadWriteFile n8n-Knoten): Diese Knoten arbeiten zusammen in der n8n-Vorlage, um die neu empfangenen Bitrix24-Token (einschließlich Ablaufdatum und Domain) zu serialisieren und sie sicher in einer JSON-Datei auf dem lokalen Dateisystem zu speichern, was eine Persistenz für die spätere Laufzeitnutzung garantiert.
Register Placement (HTTP Request n8n-Knoten): Führt einen Bitrix24-API-Aufruf aus, um die benutzerdefinierte Widget-Handler-URL an der gewünschten Platzierung, speziell TASKVIEWTAB, zu binden und so sicherzustellen, dass die n8n-Webhook-URL korrekt in die Bitrix24-Oberfläche integriert wird.
Read Installation Settings & Process Settings (ReadWriteFile & Function n8n-Knoten): Beim Laufzeitzugriff rufen diese Knoten die gespeicherten Token ab und verarbeiten sie, um sicherzustellen, dass der n8n-Workflow über die notwendigen Anmeldeinformationen und den Kontext (wie die spezifische taskId) verfügt, um mit API-Abfragen fortzufahren.
Get Task Data (HTTP Request n8n-Knoten): Verwendet die validierten Zugriffstoken, um einen authentifizierten Aufruf an die Bitrix24-API (tasks.task.get) durchzuführen und die für die Widget-Anzeige benötigten Details abzurufen. Dies ist ein kritischer Schritt in der Laufzeitphase dieses n8n-Workflows.

• Task View Response (RespondToWebhook n8n-Knoten): Die letzte Aktion für Laufzeitanfragen. Er paketiert das vom vorherigen Funktionsknoten generierte HTML und sendet es sofort zurück an Bitrix24, wodurch der Inhalt des benutzerdefinierten Widgets angezeigt wird.