打造釘釘事件分發平臺之釘釘審批等事件處理

福祿網路技術團隊發表於2020-09-29
事件

前言

上講和上上講我們說到了釘釘的審批和釘釘通訊錄的一個簡單示例，這次我們講下如何快速打造一個自己的釘釘事件分發平臺。讓你能夠通過監聽使用者在釘釘上的操作，然後進行對應的業務處理，比如釘釘流程審批完後業務處理、通訊錄員工增加後對應自己系統的業務處理等等

為什麼要做一套自己的釘釘事件分發平臺?
之前我們講過通過釘釘提供的通訊錄介面進行同步自己OA系統和釘釘通訊錄，這種同步的方式為：OA系統通訊錄更改-》釘釘通訊錄同步。這種方式只解決了單向同步，所以如果我們把釘釘通訊錄的事件監聽起來，這樣釘釘通訊錄更改-》OA系統通訊錄同步就能實現雙向同步的過程。
再說回上講的釘釘審批，我們講了如果通過介面進行釘釘的流程發起，但是審批的操作都是在釘釘上進行，所以也必須把釘釘上的審批動作事件進行監聽，然後將結果返回給自己的系統進行業務處理。
釘釘官方明確註明了，一個企業只能註冊一個接收回撥的URL地址 ，所以我們必須將事件的回撥進行統一管理，做一套屬於自己的釘釘事件分發平臺，註冊對應的事件，然後只提供一個回撥地址給釘釘，然後在自己的回撥地址中進行轉發。我簡單畫了一個圖，如下：
20200923225618

釘釘的事件回撥
回撥是開發者在釘釘開放平臺註冊一個HTTP介面，並訂閱相關的事件，當事件發生時，釘釘會主動呼叫開發者註冊的HTTP介面，推送對應的事件資訊。比如訂閱審批事件回撥後，當審批狀態變更時，會向註冊的HTTP介面推送事件資訊。

針對所有的回撥事件，在收到事件推送後，務必返回包含經過加密的字串“success”的json資料，只有返回了對應的json資料，釘釘才會判斷此事件推送成功。具體返回的資料格式為：

{
  "msg_signature":"111108bb8e6dbce3c9671d6fdb69d15066227608",
  "timeStamp":"1783610513",
  "nonce":"123456",
  "encrypt":"1ojQf0NSvw2WPvW7LijxS8UvISr8pdDP+rXpPbcLGOmIBNbWetRg7IP0vdhVgkVwSoZBJeQwY2zhROsJq/HJ+q6tp1qhl9L1+ccC9ZjKs1wV5bmA9NoAWQiZ+7MpzQVq+j74rJQljdVyBdI/dGOvsnBSCxCVW0ISWX0vn9lYTuuHSoaxwCGylH9xRhYHL9bRDskBc7bO0FseHQQasdfghjkl"
 }

20200923222844

先來註冊釘釘事件回撥

註冊回撥介面時，釘釘伺服器會向URL發起【測試回撥URL】事件，來驗證填寫url的合法性，url伺服器需要在接收到回撥之後返回字串“success”的加密json資料，才能完成註冊。流程如下圖：
20200923230502

請求地址(POST)：

https://oapi.dingtalk.com/call_back/register_call_back?access_token=ACCESS_TOKEN

請求包結構體 ：

{
    "call_back_tag": ["user_add_org", "user_modify_org", "user_leave_org"],
    "token": "123456",
    "aes_key": "xxxxxxxxlvdhntotr3x9qhlbytb18zyz5zxxxxxxxxx",
    "url":"http://test001.vaiwan.com/eventreceive"
}

20200923231025

測試事件回撥URL
在註冊事件回撥介面的時候，釘釘伺服器會向您“註冊回撥介面”時候設定的url(接收回撥的url)發起POST請求，用來測試url的合法性。收到訊息後，需要返回經過加密後的字串“success”的json資料，否則釘釘伺服器將認為url不合法。
20200923231357

msg_signature ：訊息體簽名
timeStamp ：時間戳
nonce ：隨機字串
encrypt ：字串“success”加密值，加解密說明：https://ding-doc.dingtalk.com/doc#/faquestions/ltr370

這裡我已經註冊好了，直接用查詢介面看看
20200923232906
20200923232931

再來看下審批的事件回撥

20200924000222

我們自己寫的測試回撥介面：

        /// <summary>
        ///     響應釘釘事件
        /// </summary>
        /// <param name="value"></param>
        /// <returns></returns>
        [HttpPost("DingEventReceive")]
        public async Task<IActionResult> DingEventReceive([FromBody] string value)
        {           
            var dic = JsonConvert.DeserializeObject<Dictionary<string, object>>(value);
            var eventType = dic["EventType"]?.ToString();//事件型別 bpms_instance_change、bpms_task_change
            var processInstanceId = dic["processInstanceId"]?.ToString();//審批例項id
            var corpId = dic["corpId"]?.ToString();//審批例項對應的企業
            var createTime = dic["createTime"].ToString();//流程建立事件
            var title = dic["title"].ToString();//標題
            // type為start表示審批例項開始，審批正常結束（同意或拒絕）的type為finish，審批終止（發起人撤銷審批單）的type為terminate
            var type = dic["type"].ToString();           
            var staffId = dic["staffId"].ToString();//發起流程例項的員工
            var url = dic["url"].ToString();//審批例項url，可在釘釘內跳轉到審批頁面
            var processCode = dic["processCode"].ToString();//審批模板的唯一碼
            var result = dic["result"].ToString();//同意時result為agree，拒絕時result為refuse,只有審批任務結束、審批任務轉交時才有
            var remark = dic["remark"].ToString();//remark表示操作時寫的評論內容
            return Ok(1);
        }

再說回事件分發平臺，這裡我們只需要將需要接受回撥的業務系統A的回撥地址告訴分發平臺，由分發平臺接收到釘釘回撥後根據需要分別通知即可，這裡就不做程式碼展示了。

上講的時候我們是的流程發起，其實填單是在自己的內部系統填寫的然後通過介面像釘釘發起流程，實現這次的事件分發平臺後，我們可以將一些簡單的表單由釘釘上直接填寫，然後通過事件回撥，然後傳給我們內部系統進行歸檔。

內部系統填寫表單 （由於自己內部系統，可以支援各種複雜的表單填寫，資料關聯操作等）：
20200924002417

釘釘系統填寫表單 （適合簡單的表單填寫）：
20200924002626

好了，到此結束，更多的大家可以多關注下釘釘官方文件：https://ding-doc.dingtalk.com/doc#/personnal/fdzxvg

如果大家有疑問或者更好的想法建議，評論區見~
20200924005259

福祿ICH·ERP專案部 福樂裡

相關文章