簡介
本教學課程示範如何從 Oracle EPM Cloud Planning 中的 Groovy 指令碼呼叫外部 REST API。您也將瞭解如何使用功能表項目來呼叫命令檔,以及如何將動作功能表與資料表單建立關聯,來建立滑鼠右鍵動作功能表。
依序完成區段。
背景
Groovy EPM 物件模型提供呼叫內部 (跨 POD 或其他 Oracle Cloud Services) 和外部 REST API 的方式。在此範例中,您可以建立並執行 Groovy 規則來呼叫外部 Google Places REST API,以在 ManageEmployees 表單中新增或更新員工地址資訊。
必要條件
Cloud EPM 實作教學課程可能需要您將快照匯入至 Cloud EPM Enterprise Service 例項。無法透過現有的應用程式或業務程序匯入快照。匯入快照之前,請使用個別的 Cloud EPM Enterprise Service 例項,或從您計畫使用的例項中移除現有的應用程式或業務程序。匯入快照並不會自動取代或回復現有的內容。
開始此教學課程之前,您必須:
- 讓服務管理員可以存取 Cloud EPM Enterprise Service 例項。
- 將此快照上傳並匯入至您的 Planning 例項。如果您先前已為另一個 Groovy 教學課程上傳此快照,您可以繼續使用相同的快照。
- 您必須先註冊並建立計費帳戶以取得 API 金鑰,才能開始使用包含本教學課程中所使用之 Places API (新) 的 Google Maps Platform API。若要深入瞭解,請參閱 Google Maps Platform 入門。
附註:
如果匯入快照時發生移轉錯誤,請重新執行移轉 (不包括 HSS-Shared Services 元件),以及「核心」元件中的「安全性與使用者偏好設定」人工因素。如需上傳與匯入快照的詳細資訊,請參考管理 Oracle Enterprise Performance Management Cloud 的移轉文件。秘訣:
此教學課程所需的命令檔會連結為每個區段內的文字檔。載入規劃計算變數
在此區段中,您可以從 XML 檔案上傳計算變數,以用於 Groovy 指令碼。
- 在 HP4_Plan2_Variables.xml 的連結上按一下滑鼠右鍵,然後將檔案儲存至本機磁碟機。
- 按一下
(導覽器),然後在「建立並管理」下,選取規則以開啟 Calculation Manager。
- 在「系統檢視」中,依序展開 EPM Cloud 和 HP4 。在 Plan2 上按一下滑鼠右鍵,然後選取匯入。

- 在「檔案匯入詳細資訊」下,瀏覽並從本機磁碟機選取
HP4_Plan2_Variables.xml。
- 在「地點明細」下,選取下列值:
- 應用程式類型: EPM Cloud
- 應用程式:HP4
- 立方體:Plan2
- 在「匯入選項」下,選取覆寫現有物件。

- 按一下匯入。複查匯入結果,然後按一下確定。

附註:
每個物件的訊息可以說「已插入」或「已更新」。 - 按一下取消,關閉「匯入」對話方塊。
在 Planning 中建立具名連線
在此區段中,您可以建立 Google Places API 的「地圖」連線。
- 將 Calculation Manager 保持開啟,並返回 Planning 瀏覽器視窗。
- 按一下
(導覽器),然後在「工具」下,選取連線。
- 按一下建立。
- 選取其他 Web 服務提供者。

- 輸入下列值:
- 連線名稱:
Maps - 網址:
https://places.googleapis.com/v1/places:searchText
- 連線名稱:
- 按一下顯示進階選項。

- 使用下列值定義 API 金鑰標頭:
- 類型:標頭
- 安全:已選取
- 姓名:
X-Goog-Api-Key - 值:您的 Google Maps API 金鑰
保持您的 API 金鑰隱私。
- 按一下
(新增) 並使用下列值定義其他標頭:- 類型:標頭
- 安全:已清除
- 姓名:
X-Goog-FieldMask - 值:
places.formattedAddress

- 按一下儲存並關閉,以儲存連線。

建立 Groovy 指令碼
在此區段中,您可以建立 Groovy 規則,以使用預先定義的 ManageEmployees 表單來更新員工的地址。

- 返回 Calculation Manager 瀏覽器視窗。
- 在「系統檢視」頁籤上,依序展開 EPM Cloud 、HP4 及 Plan2 。在規則上按一下滑鼠右鍵,然後選取新建。

- 針對「名稱」,輸入
Groovy Add or Update Employee Address,然後按一下確定。
- 在「規則編輯器」中,將「設計工具」選項變更為編輯命令檔,並將「命令檔類型」設為 Groovy 命令檔。

- 複製此命令檔並貼到編輯器中:
/*RTPS: {Employee} {EmployeeAddress} {Scenario} {Year} {Period} {Entity} {Version}*/
Member employee = rtps.Employee.member
// Get the complete address using the Google Places API (New).
// Use the original RTP value if Google Maps can't find the address.
def address = rtps.EmployeeAddress
HttpResponse<String> jsonResponse = operation.application
.getConnection("Maps")
.post()
.header("Content-Type", "application/json")
.body(json([
"textQuery": rtps.EmployeeAddress.enteredValue
]))
.asString()
println("Google Maps HTTP status: ${jsonResponse.status}")
println("Google Maps response:")
println(jsonResponse.body)
ReadContext ctx = JsonPath.parse(jsonResponse.body)
List places = ctx.read('$.places') as List
if (jsonResponse.status >= 200 && jsonResponse.status < 300 && places && !places.isEmpty()) {
String formattedAddress = ctx.read('$.places[0].formattedAddress')
println("Google Maps formatted address: ${formattedAddress}")
address = getTextCellId(formattedAddress, true)
} else {
println("Google Maps did not return a place. Using original address: ${rtps.EmployeeAddress.enteredValue}")
}
// Generate the calc script to save the employee address
"""SET CREATENONMISSINGBLK ON;
FIX(${fixValues(rtps.Scenario, rtps.Year, rtps.Period, rtps.Entity, rtps.Version, employee)}, "USD")
"Employee Address" = $address;
ENDFIX;"""
定義此規則在第一行所使用的全部執行時期提示 (RTP)。
取得 Employee RTP 指定之員工的 Member物件。
未指派格式化位址時,請使用 EmployeeAddress RTP 作為預設位址。
使用對應連線來傳送 HTTP POST 要求。將內容類型設為 application/json,然後在 JSONtextQuery欄位中傳送輸入的 EmployeeAddress 值。
記錄用於疑難排解的 HTTP 狀態和回應主體。
使用 JsonPath 剖析 JSON 回應。明確地將 places陣列轉換為List,因此靜態類型檢查可以解析isEmpty()。當回應狀態為成功且清單不是空白時,請閱讀places[0].formattedAddress,將其轉換為文字儲存格 ID,然後將其指派給address。否則,請保留原始 RTP 值。
產生計算指令碼,以儲存 RTP 所指定交集的員工地址。附註:
「地圖」連線是 Groovy 指令碼與 Google Places API (新) 資源之間的通訊連結。 - 在工具列中,按一下
(儲存)。按一下確定,關閉資訊訊息。附註:
儲存命令檔會在「變數」頁籤中顯示變數。

- 在「變數」頁籤中,針對員工、實體、期間、案例、版本和年度選取隱藏,讓使用者只輸入 EmployeeAddress 的值。
附註:
當使用者從表單執行規則時,這些隱藏變數會從表單環境定義接收值。
- 再按一下
(儲存)。按一下確定,以關閉資訊訊息。 - 按一下
(驗證與部署)。輸入下列 RTP 值以進行驗證:- 員工:
"Full Time Employees" - 實體:
"No Entity" - 期間:
Jan - 案例:
Current - 版本:
"BU Version_1" - 年份:
FY26

- 員工:
- 選取套用值至規則以將這些值儲存為驗證的預設值,然後按一下確定。
附註:
驗證不會執行規則,但需要有效的成員才能成功驗證。 - 當系統提示時,按一下確定,然後關閉 Calculation Manager。

建立規劃動作功能表以執行 Groovy 指令碼
在此區段中,您可以使用執行 Groovy 規則的功能表項目來建立「管理員工」動作功能表。
- 在 Planning 中,按一下
(導覽器),然後在「建立並管理」下,選取動作功能表。附註:
如果您已完成其他 Groovy 教學課程,則「管理員工」動作功能表可能已存在。如果這麼做,請繼續進行步驟 4。 - 按一下
(建立功能表) 以建立動作功能表。
- 在「功能表名稱」中輸入
Manage Employees,然後按一下確定。
- 選取管理員工動作功能表,然後按一下
(編輯功能表)。
- 按一下
(新增子項)。輸入或選取下列值:選項欄位 值 功能表項目 Update Employee Address標籤 Update Employee AddressType 業務規則 必要的參數 員工 多維資料庫 Plan2 Business Rule - 商業規則 Groovy 新增或更新員工地址 
- 按一下儲存。在確認訊息中,按一下確定。

- 按一下儲存以儲存動作功能表。在確認訊息中,按一下確定。


- 按一下取消,即可關閉「動作功能表」編輯器。
將規劃動作功能表與表單建立關聯
在此區段中,您可以將「管理員工」動作功能表與 ManageEmployees 表單建立關聯。
- 按一下
(導覽器),然後選取資料。 - 按一下 ManageEmployees 開啟表單。

- 按一下動作,然後選取編輯以編輯表單。
表單編輯器會顯示新的動態頁籤。

- 選取其他選項標籤。

- 將管理員工新增至「選取的功能表」清單,然後按一下儲存。

- 按一下確定,關閉資訊訊息。

- 在頁面底端,關閉編輯 ManageEmployees 動態頁籤以返回資料表單。
測試 Groovy 指令碼
在此區段中,您可以從開啟的 ManageEmployees 表單執行規則以擷取並儲存完整地址,然後複查工作日誌。
- 在員工 1 上按一下滑鼠右鍵,然後選取更新員工地址。

- 在「員工地址」提示中,輸入
Oracle, Redwood Shores,然後按一下啟動。
- 按一下確定,關閉資訊訊息。

成功完成時,Google Maps 傳回的完整地址會儲存為員工 1 的地址。

- 按一下
(導覽器),然後在「應用程式」下,選取工作以開啟「工作主控台」。
- 按一下 Groovy 新增或更新員工地址以顯示工作詳細資料。

- 在「執行狀態」下,展開已完成以檢視 Groovy 指令碼所列印的日誌訊息。

相關連結
- Planning 教學課程 — 從興趣領域清單中選取實作 Groovy ,以探索其他 Groovy 教學課程。
- Groovy 規則的 Java API 參考 — 探索可用於開發 Groovy 規則和範本的 Groovy API。
- Oracle Fusion Cloud EPM 的 REST API — 探索可用來管理和自動化 Cloud EPM 作業的 REST API。
其他學習資源
在 docs.oracle.com/learn 上探索其他實驗室,或在 Oracle Learning YouTube 頻道上存取更多免費學習內容。此外,請造訪 education.oracle.com/learning-explorer 以成為 Oracle Learning Explorer。
如需產品文件,請造訪 Oracle Help Center 。