簡介

本教學課程示範如何從 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 指令碼。

  1. 在 HP4_Plan2_Variables.xml 的連結上按一下滑鼠右鍵,然後將檔案儲存至本機磁碟機。
  2. 按一下 瀏覽器 (導覽器),然後在「建立並管理」下,選取規則以開啟 Calculation Manager。
    「建立與管理」底下反白顯示「規則」的導覽器
  3. 在「系統檢視」中,依序展開 EPM Cloud 和 HP4 。在 Plan2 上按一下滑鼠右鍵,然後選取匯入。
    已為 Plan2 選取「匯入」的擴充「系統檢視」階層
  4. 在「檔案匯入詳細資訊」下,瀏覽並從本機磁碟機選取 HP4_Plan2_Variables.xml。
    已選取計算變數檔案的匯入對話方塊
  5. 在「地點明細」下,選取下列值:
    • 應用程式類型: EPM Cloud
    • 應用程式:HP4
    • 立方體:Plan2
  6. 在「匯入選項」下,選取覆寫現有物件。
    與 EPM Cloud、HP4、Plan2 及「覆寫已選取的現有物件」的「匯入」對話方塊
  7. 按一下匯入。複查匯入結果,然後按一下確定。
    計算變數匯入結果

    附註:

    每個物件的訊息可以說「已插入」或「已更新」。
  8. 按一下取消,關閉「匯入」對話方塊。

在 Planning 中建立具名連線

在此區段中,您可以建立 Google Places API 的「地圖」連線。

  1. 將 Calculation Manager 保持開啟,並返回 Planning 瀏覽器視窗。
  2. 按一下 瀏覽器 (導覽器),然後在「工具」下,選取連線。
    建立地圖連線之前,請先管理連線頁面
  3. 按一下建立。
  4. 選取其他 Web 服務提供者。
    在提供者選取頁面上醒目標示的其他 Web 服務提供者
  5. 輸入下列值:
    • 連線名稱:Maps
    • 網址:https://places.googleapis.com/v1/places:searchText
  6. 按一下顯示進階選項。
    將連線詳細資訊與顯示的進階選項對應
  7. 使用下列值定義 API 金鑰標頭:
    • 類型:標頭
    • 安全:已選取
    • 姓名:X-Goog-Api-Key
    • 值:您的 Google Maps API 金鑰

    保持您的 API 金鑰隱私。

  8. 按一下 新增 (新增) 並使用下列值定義其他標頭:
    • 類型:標頭
    • 安全:已清除
    • 姓名:X-Goog-FieldMask
    • 值:places.formattedAddress
    對應已設定標頭和遮罩 API 金鑰的連線
  9. 按一下儲存並關閉,以儲存連線。
    使用儲存的地圖連線管理連線頁面

建立 Groovy 指令碼

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

維護員工資訊的 ManageEmployees 表單
  1. 返回 Calculation Manager 瀏覽器視窗。
  2. 在「系統檢視」頁籤上,依序展開 EPM Cloud 、HP4 及 Plan2 。在規則上按一下滑鼠右鍵,然後選取新建。
    已為 Plan2 規則資料夾選取「新建」的展開系統檢視
  3. 針對「名稱」,輸入 Groovy Add or Update Employee Address,然後按一下確定。
    含員工地址規則名稱的新規則對話方塊
  4. 在「規則編輯器」中,將「設計工具」選項變更為編輯命令檔,並將「命令檔類型」設為 Groovy 命令檔。
    已選取編輯命令檔和 Groovy 命令檔的規則編輯器
  5. 複製此命令檔並貼到編輯器中:
    Code note 1 /*RTPS: {Employee} {EmployeeAddress} {Scenario} {Year} {Period} {Entity} {Version}*/
    
    Code note 2 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.
    Code note 3 def address = rtps.EmployeeAddress
    
    Code note 4 HttpResponse<String> jsonResponse = operation.application
        .getConnection("Maps")
        .post()
        .header("Content-Type", "application/json")
        .body(json([
            "textQuery": rtps.EmployeeAddress.enteredValue
        ]))
        .asString()
    
    Code note 5 println("Google Maps HTTP status: ${jsonResponse.status}")
    println("Google Maps response:")
    println(jsonResponse.body)
    
    Code note 6 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
    Code note 7 """SET CREATENONMISSINGBLK ON;
    FIX(${fixValues(rtps.Scenario, rtps.Year, rtps.Period, rtps.Entity, rtps.Version, employee)}, "USD")
        "Employee Address" = $address;
    ENDFIX;"""

    代碼備註 1 定義此規則在第一行所使用的全部執行時期提示 (RTP)。

    代碼備註 2 取得 Employee RTP 指定之員工的 Member 物件。

    代碼備註 3 未指派格式化位址時,請使用 EmployeeAddress RTP 作為預設位址。

    代碼備註 4 使用對應連線來傳送 HTTP POST 要求。將內容類型設為 application/json,然後在 JSON textQuery 欄位中傳送輸入的 EmployeeAddress 值。

    代碼備註 5 記錄用於疑難排解的 HTTP 狀態和回應主體。

    代碼備註 6 使用 JsonPath 剖析 JSON 回應。明確地將 places 陣列轉換為 List,因此靜態類型檢查可以解析 isEmpty()。當回應狀態為成功且清單不是空白時,請閱讀 places[0].formattedAddress,將其轉換為文字儲存格 ID,然後將其指派給 address。否則,請保留原始 RTP 值。

    代碼備註 7 產生計算指令碼,以儲存 RTP 所指定交集的員工地址。

    附註:

    「地圖」連線是 Groovy 指令碼與 Google Places API (新) 資源之間的通訊連結。
  6. 在工具列中,按一下 儲存 (儲存)。按一下確定,關閉資訊訊息。

    附註:

    儲存命令檔會在「變數」頁籤中顯示變數。
    確認已儲存 Groovy 規則的資訊訊息
    含有執行時期提示的已儲存規則會顯示在「變數」頁籤中
  7. 在「變數」頁籤中,針對員工、實體、期間、案例、版本和年度選取隱藏,讓使用者只輸入 EmployeeAddress 的值。

    附註:

    當使用者從表單執行規則時,這些隱藏變數會從表單環境定義接收值。
    隱藏 EmployeeAddress 以外之所有執行時期提示的「變數」頁籤
  8. 再按一下 儲存 (儲存)。按一下確定,以關閉資訊訊息。
  9. 按一下 驗證和部署 (驗證與部署)。輸入下列 RTP 值以進行驗證:
    • 員工:"Full Time Employees"
    • 實體:"No Entity"
    • 期間:Jan
    • 案例:Current
    • 版本:"BU Version_1"
    • 年份:FY26
    輸入含有驗證成員和 FY26 的「RTP 值」對話方塊
  10. 選取套用值至規則以將這些值儲存為驗證的預設值,然後按一下確定。

    附註:

    驗證不會執行規則,但需要有效的成員才能成功驗證。
  11. 當系統提示時,按一下確定,然後關閉 Calculation Manager。
    確認成功部署規則的訊息

建立規劃動作功能表以執行 Groovy 指令碼

在此區段中,您可以使用執行 Groovy 規則的功能表項目來建立「管理員工」動作功能表。

  1. 在 Planning 中,按一下 瀏覽器 (導覽器),然後在「建立並管理」下,選取動作功能表。

    附註:

    如果您已完成其他 Groovy 教學課程,則「管理員工」動作功能表可能已存在。如果這麼做,請繼續進行步驟 4。
  2. 按一下 建立功能表 (建立功能表) 以建立動作功能表。
    輸入功能表名稱前先建立功能表對話方塊
  3. 在「功能表名稱」中輸入 Manage Employees,然後按一下確定。
    已輸入「管理員工」的「建立功能表」對話方塊
  4. 選取管理員工動作功能表,然後按一下 編輯功能表 (編輯功能表)。
    「管理員工」動作功能表開啟以供編輯
  5. 按一下 新增子項 (新增子項)。輸入或選取下列值:
    選項欄位值
    功能表項目Update Employee Address
    標籤Update Employee Address
    Type業務規則
    必要的參數員工
    多維資料庫Plan2
    Business Rule - 商業規則Groovy 新增或更新員工地址
    新增「更新員工地址」商業規則的下階設定
  6. 按一下儲存。在確認訊息中,按一下確定。
    確認已儲存功能表項目的資訊訊息
  7. 按一下儲存以儲存動作功能表。在確認訊息中,按一下確定。
    確認已儲存動作功能表的資訊訊息
    包含更新員工地址的已儲存管理員工動作功能表
  8. 按一下取消,即可關閉「動作功能表」編輯器。

將規劃動作功能表與表單建立關聯

在此區段中,您可以將「管理員工」動作功能表與 ManageEmployees 表單建立關聯。

  1. 按一下 瀏覽器 (導覽器),然後選取資料。
  2. 按一下 ManageEmployees 開啟表單。
    關聯動作功能表前的 ManageEmployees 表單
  3. 按一下動作,然後選取編輯以編輯表單。

    表單編輯器會顯示新的動態頁籤。

    標示「編輯」的「動作」功能表
  4. 選取其他選項標籤。
    表單編輯器中的「其他選項」頁籤
  5. 將管理員工新增至「選取的功能表」清單,然後按一下儲存。
    管理新增至所選功能表的員工
  6. 按一下確定,關閉資訊訊息。
    確認表單已儲存的資訊訊息
  7. 在頁面底端,關閉編輯 ManageEmployees 動態頁籤以返回資料表單。

測試 Groovy 指令碼

在此區段中,您可以從開啟的 ManageEmployees 表單執行規則以擷取並儲存完整地址,然後複查工作日誌。

  1. 在員工 1 上按一下滑鼠右鍵,然後選取更新員工地址。
    已標示「更新員工地址」的「員工 1」內容功能表
  2. 在「員工地址」提示中,輸入 Oracle, Redwood Shores,然後按一下啟動。
    已輸入 Oracle 的員工地址提示,Redwood Shores
  3. 按一下確定,關閉資訊訊息。
    確認成功執行員工地址規則的資訊訊息

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

    ManageEmployees 表單,其中已儲存員工 1 的格式化員工地址
  4. 按一下 瀏覽器 (導覽器),然後在「應用程式」下,選取工作以開啟「工作主控台」。
    顯示已完成員工地址規則的「所有職務」頁面
  5. 按一下 Groovy 新增或更新員工地址以顯示工作詳細資料。
    已收合完成且顯示執行時期提示值的工作明細
  6. 在「執行狀態」下,展開已完成以檢視 Groovy 指令碼所列印的日誌訊息。
    顯示 HTTP 200、Google Places 回應和格式化位址的已展開完成狀態

其他學習資源

在 docs.oracle.com/learn 上探索其他實驗室,或在 Oracle Learning YouTube 頻道上存取更多免費學習內容。此外,請造訪 education.oracle.com/learning-explorer 以成為 Oracle Learning Explorer。

如需產品文件,請造訪 Oracle Help Center 。