釘釘整合

1.1 版本

1.2 應用場景

使用者如果將釘釘作為行動端辦公平台，可以透過安裝此插件直接將報表整合到釘釘中，以釘釘為統一入口進行報表的查看。

1.3 功能簡介

• 安裝釘釘管理插件，就可以實現釘釘整合。
  

• 在釘釘管理中配置釘釘平台的基本參數，就可以讀取到釘釘平台通訊錄，將報表使用者與釘釘使用者綁定，就可以實現單點登入。

• 在排程管理的匯出設定中，可以配置並推播釘釘訊息。

• 支援整合多個企業應用，進行釘釘升級時請注意進行相容設定。

注1：釘釘整合下若使用「掃碼元件」， 要求 單點登入

注2：「釘釘管理」支援 叢集

2.1 環境準備

2.1.1 安裝插件

點選下載插件：釘釘管理、HTML5 行動端展現插件

設計器插件安裝方法參照 設計器插件管理

伺服器安裝插件方法參照 伺服器插件管理

注：微信/釘釘整合程式中，必須確定各版本相對應，請參見：微信、釘釘、H5、伺服器、JAR 之間的依賴關係

2.1.2 配置網路環境

在釘釘整合之前，必須先完成網路環境配置，參考文檔：行動端整合環境準備

2.2 建立應用

1）管理者登入釘釘企業號，進入開放平台後開啟「應用開發>釘釘應用」介面，點選「建立應用」。如下圖所示：

填寫建立應用的相關資訊。如下圖所示：

2.3 配置H5微應用

配置應用能力。點選「新增應用能力>網頁應用」進入配置介面。

填寫應用首頁地址（可以先填數據決策系統的地址，具體的地址需要在後續步驟生成後，將生成的連結再貼上過來）。點選「儲存」完成配置。如下圖所示：

伺服器出口 IP 獲取方法本文提供 4 種，如下所示：

• 百度瀏覽器輸入 IP 獲取地址

• 點選右邊連結獲取：獲取伺服器出口IP

• Linux 系統中，輸入curl ifconfig.me 獲取

• 開啟 cmd 命令視窗，輸入如下指令：ping 域名（內網映射到外網的域名）如下圖所示：

2.4 發佈H5微應用

在「文檔測試」應用中點選「版本管理與發佈>確認發佈」。發佈後，設定應用的可使用範圍，並點選「儲存」。如下圖所示：

注：可使用範圍應以部門為主，不能選擇到個人。

2.5 獲取應用參數值

1）需獲取的四個參數及說明如下表所示：

2）在「文檔測試」應用中點選「基礎資訊」，在「應用證件」下即可查看 AgentID、AppKey、AppSecret 這三個參數的值。如下圖所示：

3）「首頁」查看企業的 CorpID，如下圖所示：

完成 H5 微應用發佈並獲取應用參數值後，進入 Finereport 進行後續配置。

2.6 平台中新增釘釘應用

以管理者身分進入數據決策系統，點選「管理系統」>「釘釘管理」。

2.6.1 儲存報表伺服器地址

必須設定「報表伺服器地址」並儲存，如果不設定，推播的時候可能會有問題，例如：http://secure.finedevelop.com:65081/webroot/decision

輸入「報表伺服器地址」，如下圖所示：

2.6.2 建立釘釘應用

點選「建立釘釘應用」，輸入釘釘應用名稱，並將本文 2.5 節已確認的 AgentID、CorpID、AppKey、AppSecret 分別填到釘釘應用 ID、CropID、AppKey、AppSecret 中，點選「確定」。如下圖所示：

注：請填寫合乎規範的資訊，釘釘應用名稱、釘釘應用 ID（AgentId）、CropID、AppKey、AppSecret 均不可為空，且釘釘應用名稱不可重複。

建立釘釘應用成功後，可對資訊進行修改和刪除，支援整合多個釘釘應用。

2.7 應用快捷配置

2.7.1 釘釘代理跳轉

內網環境：

若報表伺服器是配置在內網，則需要配置代理伺服器地址，來進行釘釘的存取。如下圖所示：

注：當客戶需要配置正向代理時，可將對應代理伺服器的地址填寫在快捷配置這裏，具體正向代理的配置可以參考：行動端整合環境準備

正文框中輸入正確的「代理伺服器地址」，點選「測試連結」，連結成功後，會提示資訊：「連結成功」

外網環境：

外網環境不需要設定代理伺服器地址。

私有化部署環境下可能需要在進階請求配置參數，用於認證等，操作詳情見「其他配置」的 2.7.4.2 節。

2.7.2 生成釘釘連結

該功能可以生成存取決策平台或某個範本的連結，透過 範本訊息事件 可以將該連結推播給行動端使用者，使用者點開後即可存取連結對應的內容。

1）生成存取決策平台的釘釘連結

首先要選擇「企業應用名稱」，連結頁面下拉選擇「決策平台」，點選「生成連結」後，點選「複製」按鈕即可，如下圖所示：

2）生成存取某個範本的釘釘連結

首先要選擇「釘釘應用名稱」，連結頁面選擇「單個範本」，然後選擇一張範本，如果需要設定參數，可以點選「設定參數預設值」進行設定，設定了參數後可以根據自己的需要選擇是否「解析參數值」，最後點選「生成連結」，點選「複製」按鈕即可，如下圖所示：

注 1：若生成的連結想用於排程管理自訂連結推播、直接存取、掛載到釘釘後台的時候，必須勾選「解析參數值」，否則將導致參數丟失。

注 2：範本訊息推播的訊息連結可選擇不解析參數值，進而實現推播時的公式計算。

下面介紹下如何配置參數。

• 設定參數預設值

點選「設定參數預設值」後，如果範本本身有參數，那麼會顯示在下方，使用者可以設定參數的預設值，當然也可以點選右上角新增參數，如下圖所示：

注：如果想刪除參數，可以滑鼠懸浮在參數列表的右邊，會出現刪除按鈕。

• 解析參數值

假如一張範本「a.cpt」設定了一個參數「date」，其值為公式${today}。

如果勾選了「解析參數值」，那麼點選「生成連結」後，連結中會自動解析出今天的日期，也就是變成了：a.cpt&date=2020-11-03。

如果不想連結中直接解析參數，想要保留這個公式，可以取消勾選「解析參數值」，點選「生成連結」後，公式保留：a.cpt&date=${today}。

3）生成自訂連結

生成在釘釘能夠存取的應用封裝連結。

首先，選擇「企業應用名稱」，生成「自訂連結」並填入「應用封裝」中生成的連結。然後點選「生成連結」並複製即可。如下圖所示：

2.7.3 其他設定

2.7.3.1 PC端在瀏覽器開啟連結

若使用者希望 PC 端點選訊息推播的連結，能夠在外部瀏覽器下開啟內容，開啟按鈕「PC端在瀏覽器開啟連結」。如下圖所示：

在 PC 端點選推播訊息後，釘釘內建瀏覽器提示「連結將在外部瀏覽器開啟」。

2.7.3.2 （非必須項）進階請求配置

需要請求頭自訂的使用者可進行配置，沒有需求可跨越此步驟。

進階請求配置可設定請求頭參數，用於認證等。

透過修改 FINE_CONF_ENTITY視覺化配置參數DingTalkConfig.requestConfigEnable的值為true，開啟「釘釘管理」的進階請求配置功能頁面，進行自訂請求配置。

完成後傳回「釘釘管理>應用快捷配置」中，查看到「其他配置」項中出現了「進階請求配置」。可新增請求頭配對的「鍵」和「值」。可新增多個。完成後點選「儲存」。如下圖所示：

2.7.4 建立釘釘群

給釘釘應用建立釘釘群，支援透過排程管理推播群訊息到釘釘群。建群方法如下：

1）在釘釘開放平台裏新增一個權限：chat相關API的管理權限。步驟詳情請參見釘釘說明文檔：企業群訊息---概述

否則會出現報錯，如下圖所示：

釘釘傳回失敗資訊為：{'errcode':60011,'errmsg':'沒有呼叫該API的權限，API權限申請參考：https://ding-doc.dingtalk.com/doc#/serverapi2/rnomdt'}

2）開啟企業對話權限後，點選「建立釘釘群」，選擇「釘釘應用」，填寫「釘釘群名稱」，選擇「群主」和「群成員」，如下圖所示：

注：所有設定項均不允許為空。

釘釘整合支援推播釘釘群訊息，詳細介紹參見文檔：釘釘定時推播訊息

2.8 （可選）修改首頁地址連結

使用者若需要設定 PC 端單點登入，需要填寫對應連結。

2.8.1 修改應用首頁地址

進入本文 2.3 節中已建立的H5微應用，點選「開發管理>修改」，將 2.7.2 節 生成的連結貼上到「應用首頁地址」，點選「儲存」。

使用者若需要設定 PC 端單點登入 ，需填寫「PC端首頁地址」，該地址與「應用首頁連結」地址一致。如下圖所示：

2.9 開啟權限

點選「權限管理>通訊錄管理」，開啟權限。如下圖所示：

開通的權限為以下4項：

• 企業員工手機號碼碼資訊

• 通訊錄部門資訊讀權限

• 成員資訊讀權限

• 通訊錄部門成員讀權限

若要實現群訊息推播，需要在釘釘開放平台裏新增一個權限：釘釘群基礎資訊管理權限。

2.10 成員管理

2.10.1 使用者匹配方式

可根據實際情況選擇一種使用者匹配方式。

使用者匹配方式：「釘釘工號匹配」、「手機號碼碼匹配」、「手動匹配」、「自訂匹配」，預設為「釘釘工號匹配」。「成員管理」頁面如下圖所示：

注1：不管整合幾個釘釘應用，使用者統一進行管理。

注2：切換了匹配方式後，都需要同步一下使用者。

釘釘工號匹配：

「釘釘工號匹配」和「手機號碼碼匹配」展示列相同。

釘釘工號匹配，則是釘釘工號與報表裏的帳號匹配，為一對一匹配。

手機號碼碼匹配，釘釘使用者的手機號碼碼是唯一的，但是報表使用者可以設定多個使用者有同一個手機號碼碼，此時的匹配邏輯為哪個報表使用者先建立則匹配哪個

選擇這兩個匹配方式時，釘釘通訊錄資訊展示：「姓名」、「釘釘工號」、「釘釘成員ID」、「釘釘部門」和「釘釘成員手機號碼碼」，如下圖所示：

手動匹配：

當匹配方式為「手動匹配」時，釘釘成員列表中多出「報表帳號」一欄資訊，點選出現下拉框，選擇相應的報表帳號，進行手動匹配。如下圖所示：

注1：手動匹配時，報表帳號支援選擇「不選」選項。

注2：手動匹配方式是使用者可以自由選擇與釘釘使用者匹配的報表使用者，可實現多個釘釘使用者匹配同一個報表使用者。

自訂匹配：

即透過設定的「伺服器資料集」，將對應資料列的釘釘使用者和報表使用者相匹配。若出現一個釘釘使用者對應了多個報表使用者的情況，預設匹配第一個報表使用者。

選擇自訂匹配時，下方多出「匹配設定」項，選擇「資料集」、「釘釘成員ID」以及「報表帳號」，進行匹配。如下圖所示：

注 1：自訂匹配時，釘釘使用者列填寫的是釘釘成員 ID 。

注 2：資料集是使用者自己寫的做匹配的伺服器資料集，釘釘成員ID、帳號選擇表內對應的欄位。

2.10.2 通訊錄更新

點選左側「立即更新」按鈕，立即更新通訊錄內容。也可設定定時更新，點選「自動更新」按鈕，彈出設定框，設定更新頻率。如下圖所示：

注1：使用者匹配方式為「釘釘工號匹配」或「手機號碼碼匹配」時，如果使用者增刪改報表使用者或者在後台增刪改釘釘使用者，需要手動同步通訊錄更新。

注2：使用者匹配方式為「手動匹配」或「自訂匹配」時，如果使用者增刪改報表使用者或者在後台增刪改釘釘使用者，無需更新同步。

注3：時間點設定不要為 00:00，可能會概率導致通訊錄同步失敗，因為釘釘管理平台那邊有API頻率呼叫限制，限制600次/秒，而大部分企業的時間可能都會使用00:00這個時間點，導致同步失敗，通訊錄獲取的使用者資訊缺失。

2.10.3 使用者同步

報表版本 V11.0.2 ，釘釘管理插件版本 V11.0.54 之後，支援將釘釘通訊錄的使用者資訊同步到「使用者管理」介面中，儲存到平台。

使用者同步配置詳情請參見：同步使用者

1）同步配置

在「使用者管理」中進行「同步使用者」，使用者來源選擇「從釘釘同步」，選中對應的釘釘應用，即可根據釘釘通訊錄實現同步效果。

注：「釘釘管理>成員管理」的通訊錄手動更新和自動更新；「使用者管理>同步使用者」都能實現平台使用者資訊的更新。

2）同步成功後，使用者資訊同步到平台。

注：因為釘釘API限制，所有無法同步密碼，報表使用者初始密碼隨機生成。如果使用者在 APP 或 PC 端想透過帳號密碼登入，需點選 忘記密碼  ，重置後才能登入。

同步出現問題請參見：同步/匯入使用者常見問題

3）同步觸發方式

注意事項：

1）釘釘通訊錄新增的使用者，要保證姓名、釘釘工號、釘釘部門和手機號碼碼不為空；

2）使用釘釘同步前，平台同步功能是開啟的，且不能清空過同步資料；

不滿足以上兩點，同步釘釘使用者到平台會失敗。

4）釘釘和平台同步欄位的映射關係

將釘釘中的成員資訊，同步到「使用者管理」中時，每條欄位的映射關係。

2.11 效果查看

登入釘釘，點選「工作台」>「文檔測試」，該使用者會看到自己權限內可以查看的目錄，如下圖所示：

3.1 推播到釘釘的範本報表塊展示異常

問題描述：

設定排程管理任務推播包含報表塊的決策報表給釘釘，其中「檔案處理」步驟「使用者端通知」中，「連結」選擇「定時結果連結」，報表塊展示異常。如下圖所示：

原因分析：

範本受到 自適應屬性 的影響。

解決方案：

「檔案處理」步驟「使用者端通知」中，「連結」選擇「自訂連結」。如下圖所示：

3.2 內網開放白名單

在做釘釘整合時，有的客戶為內網環境，不允許所有網頁都能存取，但要確定能存取釘釘的域名：https://oapi.dingtalk.com/

3.3 插件不支援內外網同時配置

若同時配置會出現報錯 redirect_uri，以及部分使用者登入有問題。如下圖所示：

3.4 蘋果使用者釘釘 PC 端強制開啟範本

如果蘋果（Mac）電腦使用者，想讓範本連結強制使用釘釘內部瀏覽器開啟，可以在範本 url 後新增上 ?ddtab=true 在釘釘內部瀏覽器開啟以保證與釘釘登入使用者匹配。

3.5 23001網路異常

釘釘部署代理伺服器時，插件日誌出現 error 級別的日誌報錯，報錯碼為「23001」則是網路異常的問題。

可以參考文檔解決異常：代理伺服器連結外網 3.1節。

3.6 新增伺服器出口IP

呼叫釘釘服務端API時的合法IP列表，多個IP請以“,”隔開，支援帶一個*號通配符的IP格式