Bitrix24 工作流程小工具安裝與執行階段處理器 - n8n 工作流程

需要穩定後端來管理安裝與權杖的 Bitrix24 應用程式開發人員。
正在尋找適用於複雜 Webhook 互動的穩健 n8n 模板的使用者。
在 CRM 環境中部署自訂小工具的自動化專家。
尋求可自行架設（self-hosted）解決方案來處理 Bitrix24 API 的工程師。

為 Bitrix24 等平台開發自訂應用程式，需要對 OAuth 權杖、安裝回呼（callback）和動態內容傳遞進行複雜的處理。這個強大的 n8n 工作流程透過作為所有與您的自訂小工具應用程式相關的 Bitrix24 事件的中央處理器，解決了這些挑戰。這個 n8n 模板的主要價值在於它能無縫地管理安裝握手程序——將關鍵存取權杖儲存至磁碟——然後在執行階段利用這些儲存的憑證，在 Bitrix24 工作流程檢視分頁中擷取並顯示特定情境的資訊（例如工作流程詳情）。

每當 Bitrix24 發送請求（無論是安裝還是小工具顯示），這個特定的 n8n 節點配置都能確保安全的驗證，並立即給予客製化的回應，展現了設計良好的 n8n 工作流程的效率。

整個過程始於指定的 n8n 觸發器，即 Webhook 節點，它會監聽來自 Bitrix24 的 POST 請求。

1. 觸發與初始化： Bitrix24 處理器 (Handler) n8n 觸發器接收事件。擷取憑證 (Extract Credentials) n8n 節點會立即解析傳入的 JSON 資料負載，以取得網域、存取權杖和重新整理權杖。


2. 判斷事件類型： 檢查事件類型 (Check Event Type) 程式碼節點會分析請求，以區分應用程式安裝事件 (ONAPPINSTALL) 和執行階段放置請求（例如檢視工作流程）。


3. 安裝路徑： 如果是安裝事件，工作流程會分支出去。如果安裝尚未完成，系統會使用 設定設定資料 (Set Settings Data) n8n 節點來格式化權杖，將其轉換為 JSON 檔案（建立設定檔 (Create Settings File)），並使用 儲存安裝設定 (Save Installation Settings) n8n 節點（讀/寫檔案）來儲存配置。然後它會註冊小工具放置（註冊放置 (Register Placement) HTTP 請求節點），最後以 安裝回應 (Installation Response) webhook 回應完成流程。


4. 執行階段路徑（小工具顯示）： 如果事件是執行階段請求，系統會使用 讀取安裝設定 (Read Installation Settings) 和 擷取安裝設定 (Extract Installation Settings) n8n 節點來調用先前儲存的驗證資料。合併請求資料與安裝設定 (Merge request data with installation settings) 節點會準備必要的資料情境。


5. 資料處理與擷取： 處理設定 (Process Settings) 函式節點會擷取特定情境的資訊，例如 taskId。是否有有效設定？ (Has Valid Settings?) If 節點會驗證憑證。如果有效，獲取工作流程資料 (Get Task Data) HTTP 請求 n8n 節點會使用已儲存的 Bitrix24 存取權杖來查詢 Bitrix24 API，以獲取詳細的工作流程資訊。


6. 回應生成： 工作流程檢視回應 (Task View Response) n8n 節點會將前一個函式節點生成的 HTML 傳送回去給 Bitrix24，讓其在自訂的小工具中呈現出來。如果設定無效，則會改為傳回 錯誤回應 (Error Response)。這段複雜的邏輯展示了 n8n 工作流程的強大應用。

要部署這個全面的 n8n 工作流程，請遵循以下步驟：

1. 匯入 n8n 工作流程： 複製提供的 JSON 資料。在您的 n8n 實例中，導航至「工作流程 (Workflows)」，然後點擊「新增 (New)」。選擇「從 JSON 匯入 (Import from JSON)」，然後貼上程式碼。


2. 設定 Webhook 觸發器： 找到 Bitrix24 處理器 (Handler) n8n 觸發器節點。路徑（Path）設定為 bitrix24/widgethandler.php。啟用工作流程以生成完整的 Webhook URL。此 URL 必須在您的 Bitrix24 應用程式設定中註冊為安裝和放置事件的處理器 URL。


3. 設定預留欄位憑證： 擷取憑證 (Extract Credentials) n8n 節點包含硬編碼的預留欄位數值（例如 local.67b8a796e92127.82791242）。這些通常會在安裝 Webhook 期間被 Bitrix24 的即時資料覆寫，但如果您的應用程式使用不同的靜態 Client ID/Secret，您可能需要進行調整。請確保您的 Bitrix24 應用程式已正確配置以發送這些初始權杖。


4. 檔案系統存取權： 此工作流程使用 ReadWriteFile n8n 節點來儲存和讀取 Bitrix24 驗證權杖。請確保您的 n8n 主機環境對路徑 /data/files/hotline_files/ 具有必要的存取權限（或在 擷取憑證 (Extract Credentials) 節點中將 settingsFilePath 變數調整為您的 n8n 實例可存取的位置）。


5. 啟用： 儲存並啟用 n8n 工作流程。自動化現在將開始監聽 Bitrix24 事件。

Bitrix24 處理器 (Webhook n8n 觸發器)： n8n 工作流程的入口點。它被配置為監聽特定路徑上的 POST 請求，為安裝和工作流程檢視請求啟動一系列操作。
擷取憑證 (Set n8n 節點)： 對於安全性至關重要，此節點會解析 Bitrix24 發送的動態驗證參數（如 accesstoken 和 refreshtoken），以便在後續的 HTTP 請求中使用以及儲存至資料庫。
檢查事件類型 (Code n8n 節點)： 這是一個自訂腳本節點，用於解析傳入的請求主體，以區分應用程式安裝回呼和小工具放置事件，為 n8n 工作流程提供了關鍵的流程控制邏輯。
是安裝嗎？ (If n8n 節點)： 核心邏輯 n8n 節點，根據當前請求是否屬於應用程式安裝流程的一部分（isInstallation: true）來引導流程。
設定設定資料與儲存安裝設定 (Set & ReadWriteFile n8n 節點)： 這些節點在此 n8n 模板中協同工作，將新接收到的 Bitrix24 權杖（包含過期時間和網域）序列化，並安全地寫入本地檔案系統的 JSON 檔案中，確保資料在後續執行階段能夠持續使用。
註冊放置 (HTTP Request n8n 節點)： 執行 Bitrix24 API 呼叫，將自訂小工具的處理器 URL 綁定到所需的放置位置，特別是 TASKVIEWTAB，確保 n8n Webhook URL 能正確整合到 Bitrix24 介面中。
讀取安裝設定與處理設定 (ReadWriteFile & Function n8n 節點)： 在執行階段存取時，這些節點會調用並處理儲存的權杖，確保 n8n 工作流程具備必要的憑證和情境（如特定的 taskId）以進行後續的 API 查詢。
獲取工作流程資料 (HTTP Request n8n 節點)： 使用已驗證的存取權杖向 Bitrix24 API（tasks.task.get）執行已驗證的呼叫，擷取小工具顯示所需的詳細資料。這是此 n8n 工作流程執行階段的一個關鍵步驟。

• 工作流程檢視回應 (RespondToWebhook n8n 節點)： 針對執行階段請求的最後動作。它將前一個函式節點生成的 HTML 包裝起來，並立即傳送回 Bitrix24，從而顯示自訂小工具的內容。如果設定無效，則會改傳回 錯誤回應 (Error Response)。這段複雜的邏輯展示了 n8n 工作流程的強大應用。