Bitrix24タスクウィジェットのインストールと実行時のハンドラ - n8n ワークフロー

インストールとトークン管理のための信頼性の高いバックエンドを必要とするBitrix24アプリケーション開発者。
複雑なWebhook連携のための堅牢なn8nテンプレートを探しているユーザー。
CRM環境内にカスタムウィジェットを展開する自動化スペシャリスト。
Bitrix24 API処理のためのセルフホスト型ソリューションを求めるエンジニア。

Bitrix24のようなプラットフォーム向けにカスタムアプリケーションを開発するには、OAuthトークンの処理、インストール時のコールバック、動的コンテンツの配信などを複雑に取り扱う必要があります。この強力なn8nワークフローは、カスタムウィジェットアプリケーションに関連するすべてのBitrix24イベントを一元的に処理することで、これらの課題を解決します。このn8nテンプレートの主な価値は、インストール時のハンドシェイク（アクセス トークンのディスクへの保存を含む）をシームレスに管理し、保存された認証情報を使用して実行時にコンテキスト固有の情報（タスク詳細など）を取得し、Bitrix24タスクビューのタブ内に表示できる点にあります。

Bitrix24がインストール要求またはウィジェット表示要求のいずれかでリクエストを送信するたびに、この特定のn8nノード設定により、安全な認証と即時的で調整されたレスポンスが保証され、適切に設計されたn8nワークフローの効率性が示されます。

全プロセスは、指定されたn8nトリガーであるWebhookノードから開始され、Bitrix24からのPOSTリクエストをリッスンします。

1. トリガーと初期化: Bitrix24 Handler n8nトリガーがイベントを受信します。Extract Credentials n8nノードが直ちに受信JSONペイロードを解析し、ドメイン、アクセストークン、リフレッシュトークンを取得します。


2. イベントの判別: Check Event Type Codeノードがリクエストを分析し、アプリケーションのインストールイベント（ONAPPINSTALL）と実行時の配置リクエスト（例：タスクの表示）を区別します。


3. インストール時の処理パス: インストールイベントの場合、ワークフローは分岐します。インストールがまだ完了していない場合、システムはSet Settings Data n8nノードを使用してトークンをフォーマットし、JSONファイル（Create Settings File）に変換して、Save Installation Settings n8nノード（Read/Write File）を使用して設定を保存します。その後、Register Placement HTTPリクエストノードでウィジェットの配置を登録し、Installation Response Webhookレスポンスでプロセスを完了します。


4. 実行時の処理パス（ウィジェット表示）: イベントが実行時のリクエストである場合、システムはRead Installation SettingsおよびExtract Installation Settings n8nノードを使用して、事前に保存された認証データを取得します。Merge request data with installation settingsノードが、必要なデータコンテキストを準備します。


5. データ処理と取得: Process Settings Functionノードが、taskIdなどのコンテキスト固有の情報を抽出します。Has Valid Settings? Ifノードが認証情報を検証します。有効な場合、Get Task Data HTTPリクエストn8nノードは保存されているBitrix24アクセストークンを使用してBitrix24 APIにクエリを実行し、ウィジェット表示に必要な詳細なタスク情報を取得します。


6. レスポンスの生成: Format Task Data Functionノードが、取得した生データを構造化されたHTMLに変換します。最後に、Task View Response n8nノードがこのHTMLをBitrix24に返送し、カスタムタスクウィジェット内に表示されます。設定が無効だった場合は、代わりにError Responseが返されます。この複雑なロジックは、n8nワークフローの強力な応用例を示しています。

この包括的なn8nワークフローをデプロイするには、次の手順に従ってください。

1. n8nワークフローのインポート: 提供されたJSONデータをコピーします。お使いのn8nインスタンスで「Workflows」に移動し、「New」をクリックします。「Import from JSON」を選択し、コードを貼り付けます。


2. Webhookトリガーの設定: Bitrix24 Handler n8nトリガーノードを見つけます。Pathは bitrix24/widgethandler.php に設定されています。ワークフローをアクティブ化して完全なWebhook URLを生成します。このURLは、インストールおよび配置イベントのハンドラURLとしてBitrix24アプリケーション設定に登録する必要があります。


3. プレースホルダー認証情報の設定: Extract Credentials n8nノードには、ハードコードされたプレースホルダー値（例: local.67b8a796e92127.82791242）が含まれています。これらは通常、インストールWebhook中にBitrix24から送信される実際のデータで上書きされますが、アプリケーションが異なる静的なクライアントID/シークレットを使用する場合は調整が必要になることがあります。Bitrix24アプリがこれらの初期トークンを送信するように正しく設定されていることを確認してください。


4. ファイルシステムへのアクセス権限: このワークフローは、ReadWriteFile n8nノードを使用してBitrix24認証トークンを保存および読み取ります。お使いのn8nホスト環境がパス /data/files/hotline_files/ にアクセスするための必要な権限を持っていることを確認するか（またはExtract CredentialsノードのsettingsFilePath変数を、お使いのn8nインスタンスからアクセス可能な場所に調整してください）。


5. 有効化: n8nワークフローを保存して有効化します。これで自動化がBitrix24イベントの待機を開始します。

Bitrix24 Handler (Webhook n8nトリガー): n8nワークフローのエントリーポイントです。特定のパスへのPOSTリクエストをリッスンするように設定されており、インストールとタスクビューリクエストの両方の操作シーケンスを開始します。
Extract Credentials (Set n8nノード): セキュリティ上不可欠なこのノードは、Bitrix24によって送信される動的な認証パラメーター（accesstokenやrefreshtokenなど）を抽出し、後続のHTTPリクエストでの使用やストレージへの保存のために準備します。
Check Event Type (Code n8nノード): カスタムスクリプトノードであり、受信リクエストボディを解析してアプリのインストールコールバックとウィジェット配置イベントを区別し、n8nワークフローの重要なフロー制御ロジックを提供します。
Is Installation? (If n8nノード): 中核となるロジックノードであり、現在リクエストがアプリケーションインストールプロセスの一部であるか（isInstallation: true）、どうかに基づいてフローを分岐させます。
Set Settings Data & Save Installation Settings (Set & ReadWriteFile n8nノード): これらのノードはn8nテンプレート内で連携し、新しく受信したBitrix24トークン（有効期限やドメインを含む）をシリアライズしてローカルファイルシステム上のJSONファイルに安全に書き込み、後続の実行時の使用のために永続性を保証します。
Register Placement (HTTP Request n8nノード): Bitrix24 APIを呼び出し、カスタムウィジェットのハンドラURLを目的の配置、特に TASKVIEWTAB に関連付け、n8n Webhook URLがBitrix24インターフェースに正しく統合されるようにします。
Read Installation Settings & Process Settings (ReadWriteFile & Function n8nノード): 実行時にアクセスがあった際、これらのノードは保存されているトークンを読み取り処理し、n8nワークフローが必要な認証情報とコンテキスト（特定のtaskIdなど）を保持し、APIルックアップに進めるようにします。
Get Task Data (HTTP Request n8nノード): 検証済みのアクセストークンを使用してBitrix24 API (tasks.task.get) に対して認証付きの呼び出しを実行し、ウィジェット表示に必要な詳細情報をフェッチします。これはこのn8nワークフローの実行フェーズにおける重要なステップです。

• Task View Response (RespondToWebhook n8nノード): 実行時リクエストの最終アクションです。先行するFunctionノードによって生成されたHTMLをパッケージ化し、即座にBitrix24に返送することで、カスタムウィジェットコンテンツを表示します。