Lark整合

1.1 版本

1.2 功能簡介

管理者安裝插件並配置，可實現Lark整合，並進行訊息推播。

1.3 注意事項

1）Lark成員ID不要設定成中文和特殊字元，不然會導致單點失敗，成員ID不可修改，只能刪除成員重新新增。

2）飛書管理和lark管理，這兩個插件不能同時安裝使用 。

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

插件安裝方法參照：插件管理

3.1 建立應用

1）管理者登入Lark管理後台，開啟「工作台>應用管理」，點選「建立應用程式」。

2）進入「Lark開放平台」後，點選「Create App」按鈕，建立應用。

3）在建立介面選擇「Custom Apps > Create Custom App」，輸入資訊後，點選「Create」。如下圖所示：

3.2 設定應用權限

1）建立應用後，進入應用配置介面。在「權限管理」中開通所需權限，如下圖所示：

2）所需要開放的權限名稱如下表所示：

3）對應權限說明可點選「權限名稱」查看，如下圖所示：

注：在應用發佈前，還有一些配置，需要先在報表伺服器中配置好才能繼續，需進入報表工程配置並獲取資訊。

3.3 獲取應用參數

先獲取在報表伺服器中需要使用的三個參數：

1）在「Lark  Developer」建立的應用下，開啟「Credentials & Basic Info > Credentials」獲取「App ID」、「App Secret」 。如下圖所示：

2）進入「Lark Admin」，在「企業設定>企業資訊」中，獲取「企業編號」。如下圖所示：

4. 應用管理

以管理者身分進入FineBI，點選「管理系統>飛書管理>應用管理」。

4.1 伺服器

點選「管理系統>Lark管理>應用管理」，輸入「伺服器地址」並「儲存」。

範例：http://域名:埠號/webroot/decision

注：請使用二級或二級以上域名，且需透過 ICP 備案。

4.2 Lark

點選「建立Lark應用」，設定Lark應用的名稱，並根據文檔 2.2.3 節獲取的應用參數，填入 App_Id、租戶ID（即企業編號）、App_Secret

以管理者身分進入數據決策系統，點選「管理系統>Lark管理>應用快捷配置」 。

「應用快捷配置」分為「Lark代理跳轉」、「生成Lark連結」、「Lark群」三部分 。

5.1 Lark代理跳轉

1）若伺服器配置在外網環境中，則 不需要 設定代理伺服器地址 。

2）若伺服器是配置在內網環境中：

客戶伺服器可以存取Lark伺服器，網路正常，則 不需要 設定代理伺服器地址 。

客戶伺服器存取不到Lark伺服器，網路不通，則 需要 設定代理伺服器地址 。

注1：判斷伺服器是否可以存取Lark伺服器的方法，詳情參見：報表伺服器存取微信/釘釘/Lark伺服器  。

注2：設定代理伺服器的方法，詳情參見：網路不通情況下Lark伺服器正向代理  。

3）點選「應用快捷配置>代理伺服器地址」，輸入地址後點選「測試連結並儲存」。如下圖所示：

5.2 生成Lark連結

設定項說明如下表所示：

注：使用 V11.0.74 版本插件生成的連結，若回退插件，需使用老版本插件重新生成連結，重新掛載Lark主頁連結和 Lark RedirectURL 重定向連結。

5.2.1 生成存取決策平台的Lark連結

1）選擇Lark應用名稱後，連結頁面下拉選擇「決策平台」。

2）點選生成連結後，生成「Lark連結」和「Lark RedirectURL」。

3）點選複製按鈕即可複製，如下圖所示：

5.2.2 生成存取單個範本的Lark連結

1）選擇Lark應用名稱，連結頁面下拉選擇「單個範本」，然後選擇一張範本。

2）如需設定參數，請點選「設定參數預設值」進行設定，設定了參數後可以根據實際需要選擇是否勾選「解析參數值」。

3）點選生成連結後，生成「Lark連結」和「Lark RedirectURL」。

4）點選複製按鈕即可複製，如下圖所示：

設定參數預設值

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

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

解析參數值

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

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

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

注：僅「範本訊息推播」的訊息連結可選擇不勾選解析參數值，進而實現推播的公式計算；其他範本單點連結必須勾選「解析參數值」，否則將導致參數丟失。

5.3 建立Lark群

在 6 節應用發佈後，才能夠成功建群。點選「建立Lark群」，可實現推播訊息到群，群成員除群主外還要至少兩人。

傳回Lark開放平台，進入 3.1 節建立的Lark應用，對應用進行進一步配置，併發布應用。

6.1 安全設定

1）將本文 2.4.2 節生成的「Lark RedirectURL」連結，填入應用的「Security Settings > Redirect URLs」處。

2）配置 IP 白名單。如下圖所示：

注：如沒有配置白名單則無法存取整合應用。

3）Lark整合下若使用掃碼元件、檔案元件， 則要求單點登入、且必須經過可信域名校驗。如下圖所示：

6.2 設定應用首頁

1）點選「Add Features」，新增「Web app」。

2）將本文 5.2 節生成的「Lark連結」，填入「Web app configuration」中，並點選「Save」。

注：如果要桌上端登入，需配置「Desktop Homepage」連結。

6.3 啟動機器人

為了保證Lark推播訊息成功，需要在「Add Features」中新增「Bot」。否則會導致訊息推播失敗。

訊息推播參見文檔：Lark定時推播訊息 。

6.4 發佈應用

注：每次配置、修改完成Lark應用後都要發佈才生效。

1）點選「Version Management & Release > Create a version」，如下圖所示：

2）「App version」和「Update Notes」使用者在Lark合理範圍內填寫即可，Default feathers 選擇「Web App」。

3）可用範圍可選擇 All members 或 Selected members，完成後點選「Save」。

注 1：V11.0.65.1 版本之前的Lark整合插件，Lark應用可用範圍需選擇「All members」。

注 2：如果想要跳轉到平台，需將「Default feathers」設定為 Web App。

4）儲存後點選「Publish」。

5）管理者審核透過發佈。

6.5 效果預覽

企業使用者登入「工作台」在應用中可找到建立的應用。

設計器 V11.0.10 版本，Lark管理插件 V11.0.75 版本及之後，支援將Lark通訊錄的使用者資訊同步到「使用者管理」介面中，儲存到平台 。

注：請注意區分本文的使用者同步和使用者匹配。使用者同步是指將Lark通訊錄中的使用者資訊同步到決策平台的「使用者管理」介面中，確定 FineReport 平台中的使用者資訊與Lark通訊錄中的資訊保持一致。使用者匹配是指在決策平台中，透過不同的匹配方式將Lark通訊錄中的使用者與 FineReport 中的使用者進行聯動，確定兩者能夠正確對應 。

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

1）同步配置

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

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

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

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

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

3）同步觸發方式

注1：Lark通訊錄新增的使用者，要保證姓名、Lark成員ID、部門、手機號碼碼不為空，不滿足此條件則同步Lark使用者到平台會失敗 。

注2：使用Lark同步前，平台同步功能是開啟的，且不能清空過同步資料，不滿足此條件則同步Lark使用者到平台會失敗 。

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

將Lark中的成員資訊，同步到「使用者管理」中時，每條欄位的映射關係如下表所示：

Lark應用發佈後，在數據決策系統「管理系統>Lark管理>成員管理」中，可透過使用者匹配獲取Lark通訊錄的資料。

8.1 使用者匹配方式

Lark應用發佈後，在數據決策系統「管理系統>Lark管理>成員管理」中，可透過使用者匹配聯動Lark通訊錄中的使用者。

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

使用者匹配方式包括：Lark帳號匹配、手機號碼碼匹配、手動匹配、自訂匹配。「成員管理」頁面如下圖所示：

注1：Lark成員ID 不要設定成中文和特殊字元，不然會導致單點失敗。成員ID 不支援修改，只能刪除成員重新新增資訊。

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

1）Lark帳號/手機號碼碼匹配

「Lark帳號匹配」和「手機號碼碼匹配」展示欄相同。

• Lark帳號匹配：Lark成員ID 對應報表帳號，若一個 成員ID 對應多個報表帳號，則遍歷取第一個報表使用者進行匹配。

• 手機號碼碼匹配：Lark成員手機號碼碼對應報表使用者手機號碼碼，若一個成員手機號碼碼可對應多個報表帳號，則遍歷取第一個報表使用者進行匹配。

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

2）手動匹配

手動設定Lark使用者匹配具體報表使用者。當匹配方式為「手動匹配」時，成員列表中多出「帳號」一欄資訊，點選出現下拉框，選擇相應的帳號，進行手動匹配。

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

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

如下圖所示：

3）自訂匹配

選擇對應伺服器資料集，選擇對應欄，實現飛書成員 ID 匹配對應報表成員帳號。

即透過設定的「伺服器資料集」，將對應資料欄的飛書使用者和報表使用者相匹配。若出現一個飛書使用者對應了多個報表使用者的情況，預設匹配第一個報表使用者。選擇自訂匹配時，下方多出「匹配設定」項，選擇「資料集」、「飛書成員ID」及「帳號」，進行匹配。如下圖所示：

8.2 Lark通訊錄

點選「立即更新」按鈕，立即更新通訊錄內容。

點選「設定自動更新」按鈕，可設定自動定時更新，和更新週期。如下圖所示：

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

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

9.1 修改已發佈的Lark應用

使用者已發佈應用中需要修改配置後重新發布，需要在Lark開放後台進入應用，修改配置。

9.2 Lark整合支援可用範圍為部門

V11.0.65.1 及之後版本的Lark整合插件，Lark應用可用性範圍支援設定為部門，如下圖所示：

注：Lark整合插件不支援可見範圍設定為某個單獨使用者。

9.3 報錯程式碼10010002

配置Lark時彈窗報錯：發生錯誤，錯誤碼為：10010002

這是由於Lark插件未授權導致的，購買插件獲得授權後可解決該問題。