自動化聯結器

自動化聯結器是一種開發者擴充套件自動化流程規則的開放能力，支援空間管理員將「外掛觸發器/操作」與「平臺內建觸發器/操作」進行連線，並配置相關跨系統的資料整合邏輯。

外掛觸發器配置

外掛觸發器返回引數條件配置

外掛操作配置

功能範圍

1. 自動化開放能力包含觸發器、條件、操作

功能類別	描述	圖示
觸發器	支援「外掛開發者」透過http方式呼叫平臺指定介面，觸發規則執行。「外掛開發者」可自定義觸發器出參欄位，並提供於規則內的條件節點和操作節點消費	觸發器出參可以內建操作消費，部分操作需要遵循欄位型別約束
條件	當「外掛開發者」定義了「觸發器返回引數」時，支援「空間管理員」配置「自動化規則」時，以「觸發器返回引數」作為篩選條件，並由平臺提供對應的資料計算和篩選過濾功能
操作	支援自動化規則的操作節點，配置「外掛自動化聯結器」操作

1. 觸發器/操作「規則表單」開放

功能類別	描述	圖示
觸發器	開放自動化觸發器/操作「表單元件」，開發者需定義欄位型別&欄位名稱即可支援規則表單	外掛觸發器配置（外掛開發者配置） 自動化配置表單（空間管理員配置）
操作	配置自動化規則時可使用外掛操作，且操作支援將「平臺內欄位」與「三方系統欄位」進行值同步	外掛操作配置（外掛開發者配置） 自動化配置表單（空間管理員配置）

1. 「自動化聯結器」外掛配置支援熱更新
2. 外掛開發者側：當表單規則發現變化或資料接收對應的webhook地址變化時，無需發版即可實時更新（新增或刪除功能點位仍需發版）
3. 空間管理員側：已安裝外掛自動化功能升級後無需更新即可進行使用，若已配置規則發生變化，自動化規則對應在列表中會提示使用者進行配置更新

使用場景

場景類別	場景描述	開發方法
外掛觸發器	使用者配置自動化觸發器，監聽指定群訊息。空間管理員進行配置並觸發指定業務	觸發器-配置釋出：完成觸發器入參、出參、webhook地址等配置併發布外掛版本 觸發器-規則訂閱處理:使用者配置規則時，平臺向「webhook地址」推送事件，開發者服務監聽自動化規則事件（參考： ），並對規則事件進行儲存處理 觸發器-飛書訊息監聽：配置監聽飛書機器人「接收訊息」事件 觸發器-業務處理併傳送自動化事件：對接收到的訊息進行邏輯判斷，並篩選符合的自動化規則配置 自動化規則-觸發並執行自動化規則：對符合篩選條件的自動化配置，向平臺傳送觸發器事件（參考： ），觸發自動化規則
外掛操作	當需求工作項建立時，同步為指定的工作項參與人員建立飛書日程	操作-配置釋出：完成入參、webhook地址、觸發器型別等配置併發布外掛版本 觸發器-需求建立：當「需求」工作項建立時，觸發器配置參考： 操作-呼叫外掛：執行「飛書日程聯結器示例」外掛的「建立飛書日程」，自動化配置參考：

功能亮點

面向外掛開發者

1. 降低openAPI呼叫量：針對複雜介面呼叫可以由平臺能力待解決，使用外掛觸發器+內建操作閉環跨系統資料同步/更新及狀態同步等高頻資料整合場景
2. 降低外掛運維成本：將Meegle與不同三方系統之間的欄位對映由規則表單承接，開發者僅需定義三方系統中的欄位名稱及型別，即可透過表單配置保證不同空間與三方系統之間的靈活對映關係
3. 提升外掛擴充套件性：將原先資料整合中的硬編碼能力轉換成靈活配置，Meegle的自動化能力直接可被外掛所消費，提升外掛的擴充套件性

面向空間管理員

1. 資料整合規則統一管理：針對平臺內及跨平臺的資料整合，均統一在自動化中進行管理，避免因openAPI造成的規則衝突對平臺資料更新不可控現象
2. 提升外掛易用性：資料整合類規則均支援由空間管理員配置，外掛資料遵循平臺欄位規範，使得平臺內建觸發器、操作可直接與外掛資料進行整合，提升整體規則易用性

管理員流程

1. 按需引導內部團隊開發者進行相關外掛開發（參考： ）
2. 在外掛管理-新增外掛中搜尋對應的外掛並進行安裝
3. 安裝後會對應外掛功能項會自動展現在自動化觸發器/操作中，直接進行相關規則配置即可

開發者流程

自動化觸發器

開發者後臺配置

首先需要在開發者後臺增加外掛構成 -「自動化觸發器」，並完善相關配置。

1. 觸發器名稱：自動化觸發器名稱，指代外掛具體的功能項，如「飛書訊息聯結器示例」
2. 觸發器描述：自動化觸發器描述，指定該觸發器具體實現了什麼樣的功能，如「當飛書群訊息到達時觸發」
3. 觸發器key：系統自動生成，不可修改
4. webhook推送至：用於接受觸發器規則訂閱事件，支援https/http地址（對應支援實時更新，無需外掛發版即可生效）
5. token：支援開發者配置驗籤token，配置後平臺推送至對應地址時會攜帶token資訊
6. 觸發器入參：支援開發者配置觸發器節點規則表單，格式規範詳見下表
7. 觸發器出參：支援開發者配置觸發器節點出參，用於後續條件/操作節點進行規則配置，格式規範同上

一個外掛支援開發多個自動化觸發器，配置互相獨立生效

業務流程

事件列表

規則訂閱事件

規則配置者填寫觸發器入參並儲存規則後，meego會向開發者定義的 觸發器 Webhook 推送地址傳送如下格式請求：

開發者推送事件規範

規則配置者填寫觸發器入參並儲存規則後，開發者可以向觸發器API傳送請求從而觸發自動化規則執行：

介面描述	觸發器API地址
請求方式	POST
請求地址	/webhook-api/auto/trigger/data
請求引數	引數型別	引數名	是否必填	值型別	說明
	query	project_key	是	string	空間key
	query	plugin_key	是	string	外掛key
	query	trigger_key	是	string	觸發器key
	header	X-ITEM-UUID	否	string	冪等key
	header	X-TOKEN	否	string	開發者後臺提示的token簽名
	body
響應引數

觸發器API Body引數樣例如下：

自動化操作

開發者後臺配置

首先需要在開發者後臺增加外掛構成 -「自動化操作」，並完善相關配置

1. 操作名稱：自動化操作名稱，指代外掛具體的功能項，如「建立飛書日程」
2. 操作描述：自動化操作描述，指定該操作具體實現了什麼樣的功能，如「建立飛書日程，並新增參與人」
3. 操作key：系統自動生成，不可修改
4. 適用的觸發器型別：支援配置操作可應用的觸發器型別，不選擇時則預設自動化內所有觸發器均可呼叫當前外掛
5. webhook推送至：支援配置接收webhook的使用者地址，支援https/http地址（對應支援實時更新，無需外掛發版即可生效）
6. token：支援開發者配置驗籤token，配置後平臺推送至對應地址時會攜帶token資訊
7. 操作入參：支援開發者配置操作節點規則表單，格式規範詳見下表

一個外掛支援開發多個自動化操作，配置互相獨立生效

業務流程

事件列表

平臺事件

指代開發者與自動化通訊時，平臺給到外掛的事件，主要為規則訂閱事件：RuleSubscribeEvent。

工作項事件

指代規則執行時，觸發器對應的工作項變更事件或事件任務事件，主要包含以下內容：

觸發器	event_type
建立工作項	WorkitemCreateEvent
欄位值修改	WorkitemUpdateEvent
終止工作項	WorkitemAbortedEvent（工作項終止） WorkitemRestoreEvent（工作項恢復）
工作項狀態修改	WorkitemStatusEvent
任務狀態修改	TaskStatusEvent
任務修改	TaskUpdateEvent
角色操作	WorkitemPersonAssignedEvent
節點狀態修改	WorkFlowNodeStatusEvent
節點排期操作	WorkFlowNodeScheduleEvent
評論操作	WorkitemCommentEvent
工作項歸檔	WorkitemFinishEvent
刪除工作項	WorkitemDeleteEvent
定時迴圈	TimedTriggerEvent
動態時間任務	DynamicTimeTriggerEvent

事件結構體明細

1. RuleSubscribeEvent —— 規則訂閱
2. 其餘事件 當規則執行時，平臺會向開發者定義的 操作 Webhook 推送地址傳送如下格式請求：

事件推送

外掛在收到 HTTP POST 請求後，需要在 60 秒內以 HTTP 200 狀態碼，以及如下響應結構返回： 否則Meegle自動化將認為本次推送失敗，並以 6秒 的間隔重新推送事件，最多推送 3 次。

附：自動化出入參欄位型別

field_type列舉	開發者消費資料結構	欄位型別	示例	值含義	範圍
text	string	單行文字		文字值	觸發器入參、觸發器出參、操作入參
multi_text	string	多行文字		文字值	觸發器入參、觸發器出參、操作入參
date	number	日期		毫秒時間戳	觸發器入參、觸發器出參、操作入參
schedule		日期區間		開始時間戳和結束時間戳	操作入參
boolean	boolean	開關		true、false、null	觸發器出參、操作入參
user	string	人員		User key	觸發器入參、操作入參
multi_user	array[string]	多選人員		User key陣列	觸發器入參、觸發器出參、操作入參
number	number	數字		數字	觸發器入參、觸發器出參、操作入參
link	string	連結		url	觸發器出參、操作入參
select	string	單選		選項id	觸發器入參、操作入參
radio	string	單選按鈕		選項id	觸發器入參、操作入參
multi_select	array[string]	多選		選項id陣列	觸發器入參、操作入參

附：觸發器型別列舉

附：「外掛觸發器/操作」與「平臺內建觸發器/操作」支援範圍

	「飛書通知」操作	「Webhook」操作	「欄位操作」操作	「節點操作」操作	「群組操作」操作	「人員分配」操作	「狀態流轉」操作	「建立工作項」操作	「通知中心」操作	「郵件」操作
「外掛觸發器」支援範圍	✅	✅	✅	✅ 「節點操作」操作不支援引用「外掛觸發器」欄位，僅支援觸發	✅ 「群組操作」操作僅支援引用人員/多選人員欄位	✅ 「人員分配」操作僅支援引用人員/多選人員欄位	✅ 「狀態流轉」操作不支援引用「外掛觸發器」欄位，僅支援觸發	✅	✅	✅

	「定時迴圈」觸發器	「動態時間任務」觸發器	「建立工作項」觸發器	「完成工作項」觸發器	「終止或恢復工作項」觸發器	「刪除工作項」觸發器	「工作項狀態修改」觸發器	「工作項節點流轉」觸發器	「欄位值修改」觸發器	「排期操作」觸發器	「人員分配」觸發器	「評論操作」觸發器	「任務修改」觸發器	「任務狀態修改」觸發器	「建立任務」觸發器	「刪除任務」觸發器
「外掛操作」支援範圍	✅ 「外掛操作」欄位不支援引用觸發器欄位	✅ 「外掛操作」欄位不支援引用觸發器欄位	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅

{ "field_xxx_1": { // 欄位key，用於使用者自定義唯一標識欄位，不可重複 "field_type": "欄位型別", // 欄位型別 "form_config": { "label": {"origin": "欄位名稱"}, "placeholder": {"origin": "欄位提示文案"}, "validate": { "required": { "value": true // 欄位是否必填，在不同場景會有不同的現象 // 1. 觸發器入參：必填 // 2. 觸發器出參：開發者呼叫觸發器API時必須傳遞，否則將視為不滿足觸發條件 // 3. 操作入參：規則配置者必須指定該欄位的值 } } }, "field_attr": { "option": { // 僅當field_type為select、radio、multi_select時生效 "type": "enum", // enum：預設下拉選項，remote：介面呼叫動態獲取下拉選項 //1.介面呼叫動態獲取方式 "remote": { "url": "可公網訪問的POST方式的http地址" //由開發者提供 // 介面body響應格式如下 // [ // { // "label": "選項名稱", // "value": "選項id" // } // ] }, //2.靜態列舉型別 "enum": [ { "label": {"origin": "選項展示名稱"}, "value": "選項id" } ] }, } }, "field_xxx_2": { // 欄位key，用於使用者自定義唯一標識欄位，不可重複 // 結構如上 } } { "header": { "operator": "74263XXXXXX7635",// 操作人 "event_type": "RuleSubscribeEvent",// "token": "", "uuid": "" }, "payload": { "project_key": "6718xxxxxx5f002325d2edac",// 空間唯一標識 "rule_name": "名稱",// 規則名稱 "rule_group_id": 74496xxxxxx4474387,// 規則ID "trigger_at": 1734504731,// 觸發時間戳秒 "rule_list": [ { "rule_id": 7449641097673834531,// 觸發器分支唯一標識 "trigger_type": 32,// 觸發器型別，可參考觸發器型別列舉 "node_list": [ { "node_id": 7449641097711599635,// 觸發器節點id "created_at": 1734504732,// 規則建立時間戳 "updated_at": 1734504732,// 規則執行時間 "operate_type": "subscribe",// 操作行為：1. subscribe（新建規則，訂閱），2. unsubscribe（修改規則後，取消訂閱），3. update（修改規則，更新資訊） "field_item": [ { "field_key": "chat_id",// 觸發器入參欄位key "field_value": "oc_5b2720153b1d5f43494338c87f90ae8e"// 觸發器入參欄位值，實際資料型別可參考 } ] } ] } ] } } { "chat_id": { "value": "oc_d6d66b40cxxxxxxx6340bbdb8005a48" }, "content": { "value": "測試獲取資料結構" } "work_item_ids": { "label": "", "value": [124235,23523] } } { "field_xxx_1": { // 欄位key，用於使用者自定義唯一標識欄位，不可重複 "field_type": "欄位型別", // 欄位型別 "form_config": { "label": {"origin": "欄位名稱"}, "placeholder": {"origin": "欄位提示文案"}, "validate": { "required": { "value": true // 欄位是否必填，在不同場景會有不同的現象 // 1. 觸發器入參：必填 // 2. 觸發器出參：開發者呼叫觸發器API時必須傳遞，否則將視為不滿足觸發條件 // 3. 操作入參：規則配置者必須指定該欄位的值 } } }, "field_attr": { "option": { // 僅當field_type為select、radio、multi_select時生效 "type": "enum", // enum：預設下拉選項，remote：介面呼叫動態獲取下拉選項 //1.介面呼叫動態獲取方式 "remote": { "url": "可公網訪問的POST方式的http地址" //由開發者提供 // 介面body響應格式如下 // [ // { // "label": "選項名稱", // "value": "選項id" // } // ] }, //2.靜態列舉型別 "enum": [ { "label": {"origin": "選項展示名稱"}, "value": "選項id" } ] }, } }, "field_xxx_2": { // 欄位key，用於使用者自定義唯一標識欄位，不可重複 // 結構如上 } } { "header": { "operator": "74263XXXXXX7635",// 操作人 "event_type": "RuleSubscribeEvent",// "token": "", "uuid": "" }, "payload": { "project_key": "6718xxxxxx5f002325d2edac",// 空間唯一標識 "rule_name": "名稱",// 規則名稱 "rule_group_id": 74496xxxxxx4474387,// 規則ID "trigger_at": 1734504731,// 觸發時間戳秒 "rule_list": [ { "rule_id": 7449641097673834531,// 觸發器分支唯一標識 "trigger_type": 32,// 觸發器型別，可參考觸發器型別列舉 "node_list": [ { "node_id": 7449641097711599635,// 觸發器節點id "created_at": 1734504732,// 規則建立時間戳 "updated_at": 1734504732,// 規則執行時間 "operate_type": "subscribe",// 操作行為：1. subscribe（新建規則，訂閱），2. unsubscribe（修改規則後，取消訂閱），3. update（修改規則，更新資訊） "field_item": [ { "field_key": "chat_id",// 觸發器入參欄位key "field_value": "oc_5b2720153b1d5f43494338c87f90ae8e"// 觸發器入參欄位值，實際資料型別可參考 } ] } ] } ] } } { "code": 0 } 1 // 建立工作項 2 // 完成工作項 3 // 刪除工作項 4 // 終止或恢復工作項 5 // 工作項狀態修改 6 // 欄位值修改 7 // 評論操作 9 // 工作項節點流轉 10 // 排期操作 11 // 人員分配 14 // 任務修改 15 // 任務狀態修改 18 // 定時任務 19 // 動態時間任務 30 // 任務建立 31 // 任務刪除 32 // 聯結器觸發 開發者需對飛書訊息開啟事件訂閱（接收訊息），並在服務中監聽處理飛書訊息事件 對接收到的飛書訊息進行邏輯判斷，篩選出訊息符合的自動化規則 { "欄位key": { "label": "欄位名稱，可用於規則配置者的自定義引數", // 規則配置自定義引數 "value": any // 欄位值，值資料型別取自欄位key定義的欄位型別，可參考外掛自動化配置規範 }, "work_item_ids": { // 特殊支援欄位，開發者不需要在外掛自動化配置規範，使用在內建操作，value格式固定為工作項id陣列 "label": "", "value": [] } } { "code": 0 // 1001 qps限制 // 1002 大小超過限制 // 1003 冪等 // 1004 簽名錯誤 // 1005 黑名單限制 // 2001 引數異常 // 2002 缺乏必填引數 // 5001 系統錯誤 } { "header": { "operator": "7426311932258287635", // 操作者的userkey "event_type": "WorkitemCreateEvent",// webhook的event_type "token": "",// 配置的token "uuid": "8af39a3ddc19617f750338d9b7356922"// 冪等串 }, "data": {// 當使用者配置了操作入參，在規則執行時會提供操作入參的具體值，格式可參考 ，樣例如下 "description": { "value": "K個人學習" }, "end_date": { "value": 1734451200000 }, "end_time": { "value": "14" }, "mentions": { "value": [ "heguiyan", "7426311932258287635" ] }, "start_date": { "value": 1734451200000 }, "start_time": { "value": "8" }, "title": { "value": "12131231231231" } }, "payload": {// 參考原新版webhook對應Body格式 "id": "102470819", "project_key": "6718b726ef5f002325d2edac" } } { "value": "測試單行文字" } { "value": "測試多行文字" } { "value": 1727091486000 } { start: number end: number } { "value": { "start": 1727091486000, "end": 1727091486000 } } { "value": true } { "value": "測試user key" } { "value": [ "測試user key" ] } { "value": 123.1 } { "value": "https://bytedance.larkoffice.com" } { "value": "測試選項id" } { "value": "測試選項id" } { "value": [ "測試選項id" ] }