イントロダクション
このチュートリアルでは、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チュートリアル用にこのスナップショットを以前にアップロードした場合は、引き続き同じスナップショットを使用できます。
- このチュートリアルで使用するPlaces API (New)を含むGoogle Maps Platform APIの使用を開始する前に、APIキーを取得するためにサインアップして請求アカウントを作成する必要があります。さらに学習するには、Google Maps Platformの開始を参照してください。
ノート:
スナップショットのインポート中に移行エラーが発生した場合は、HSS-Shared Servicesコンポーネントを除く移行、およびコア・コンポーネントのセキュリティ・アーティファクトとユーザー・プリファレンス・アーティファクトを再実行します。スナップショットのアップロードおよびインポートの詳細は、Oracle Enterprise Performance Management Cloud移行の管理のドキュメントを参照してください。ヒント :
このチュートリアルに必要なスクリプトは、各セクション内にテキスト・ファイルとしてリンクされています。Planning計算変数のロード
この項では、Groovyスクリプトで使用する計算変数をXMLファイルからアップロードします。
- HP4_Plan2_Variables.xmlのリンクを右クリックして、ファイルをローカル・ドライブに保存します。
(ナビゲータ)をクリックし、「作成および管理」で「ルール」を選択してCalculation Managerを開きます。
- システム・ビューで、「EPM Cloud」、HP4の順に展開します。Plan2を右クリックし、「インポート」を選択します。

- 「ファイル・インポートの詳細」で、ローカル・ドライブから
HP4_Plan2_Variables.xmlを参照して選択します。
- 「事業所詳細」で、次の値を選択します。
- アプリケーション・タイプ: EPM Cloud
- アプリケーション: HP4
- キューブ: Plan2
- 「インポート・オプション」で、「既存のオブジェクトのオーバーライド」を選択します。

- 「インポート」をクリックします。インポート結果を確認して、「OK」をクリックします。

ノート:
各オブジェクトのメッセージは、「Inserted」または「Updated」と表示される場合があります。 - 「取消」をクリックして、インポート・ダイアログ・ボックスを閉じます。
Planningでの名前付き接続の作成
この項では、Google Places APIのMaps接続を作成します。
- Calculation Managerを開いたまま、Planningブラウザ・ウィンドウに戻ります。
(Navigator)をクリックし、「Tools (ツール)」の下の「Connections」を選択します。
- 「作成」をクリックします。
- 「その他のWebサービス・プロバイダ」を選択します。

- 次の値を入力します:
- 接続名:
Maps - URL:
https://places.googleapis.com/v1/places:searchText
- 接続名:
- 「拡張 オプションの表示」をクリックします。

- 次の値を使用してAPIキー・ヘッダーを定義します。
- タイプ: Header
- 保護: 選択済
- 名前:
X-Goog-Api-Key - 値: Google Maps APIキー
APIキーを秘密に保ちます。
(「追加」)をクリックし、次の値を使用して別のヘッダーを定義します。- タイプ: Header
- セキュア: クリア済
- 名前:
X-Goog-FieldMask - 値:
places.formattedAddress

- 「保存してクローズ」をクリックして、接続を保存します。

Groovyスクリプトの作成
この項では、事前定義済のManageEmployeesフォームを使用して従業員の住所を更新するGroovyルールを作成します。

- Calculation Managerのブラウザ・ウィンドウに戻ります。
- 「システム・ビュー」タブで、EPM Cloud、HP4、Plan2の順に展開します。「Rules」を右クリックして、「New」を選択します。

- 「名前」に
Groovy Add or Update Employee Addressと入力し、「OK」をクリックします。
- ルール・エディタで、「デザイナ」オプションを「スクリプトの編集」に変更し、「スクリプト・タイプ」を「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に設定し、入力されたEmployeeAddress値をJSONのtextQueryフィールドに渡します。
トラブルシューティングのためにHTTPステータスおよびレスポンス本文をログに記録します。
JsonPathを使用してJSONレスポンスを解析します。静的型チェックでisEmpty()を解決できるように、places配列をListに明示的にキャストします。レスポンス・ステータスが成功し、リストが空でない場合は、places[0].formattedAddressを読み取り、それをテキスト・セルIDに変換して、addressに割り当てます。それ以外の場合は、元のRTP値を保持します。
計算スクリプトを生成して、RTPで指定された交差に従業員住所を保存します。ノート:
Maps接続は、GroovyスクリプトとGoogle Places API (新規)リソース間の通信リンクです。 - ツールバーで、
(保存)をクリックします。「OK」をクリックして情報メッセージを閉じます。ノート:
スクリプトを保存すると、「変数」タブに変数が表示されます。

- 「変数」タブで、「従業員」、「エンティティ」、「期間」、「シナリオ」、「バージョン」および「年」の「非表示」を選択し、ユーザーがEmployeeAddressの値のみを入力します。
ノート:
ユーザーがフォームからルールを実行すると、これらの非表示変数はフォーム・コンテキストから値を受け取ります。
(保存)を再度クリックします。「OK」をクリックして情報メッセージを閉じます。
(「Validate and Deploy」)をクリックします。検証用に次のRTP値を入力します。- 従業員:
"Full Time Employees" - エンティティ:
"No Entity" - 期間:
Jan - シナリオ:
Current - バージョン:
"BU Version_1" - 年:
FY26

- 従業員:
- 「ルールに値を適用」を選択してこれらの値を検証のデフォルトとして保存し、「OK」をクリックします。
ノート:
検証ではルールが実行されませんが、検証を成功させるには有効なメンバーが必要です。 - プロンプトが表示されたら「OK」をクリックし、Calculation Managerを閉じます。

Groovyスクリプトを実行するためのPlanningアクション・メニューの作成
この項では、Groovyルールを実行するメニュー・アイテムを含む「従業員の管理」アクション・メニューを作成します。
- Planningで、
(ナビゲータ)をクリックし、「作成および管理」で「アクション・メニュー」を選択します。ノート:
他のGroovyチュートリアルを完了している場合は、「従業員の管理」アクション・メニューがすでに存在している可能性があります。存在する場合は、手順4に進んでください。
(「Create Menu」)をクリックして、アクション・メニューを作成します。
- 「Menu Name」に
Manage Employeesと入力し、「OK」をクリックします。
- 「従業員の管理」アクション・メニューを選択し、
(「編集」メニュー)をクリックします。
(子の追加)をクリックします。次の値を入力または選択します。オプション・フィールド 値 メニュー・アイテム Update Employee Addressラベル Update Employee Address入力してください ビジネス・ルール 必須パラメータ 社員 キューブ Plan2 ビジネス・ルール Groovy従業員住所の追加または更新 
- 「保存」をクリックします。確認メッセージで、「OK」をクリックします。

- 「保存」をクリックして、アクション・メニューを保存します。確認メッセージで、「OK」をクリックします。


- 「取消」をクリックすると、アクション・メニュー・エディタが閉じます。
プランニング処理メニューとフォームの関連付け
この項では、「従業員の管理」アクション・メニューをManageEmployeesフォームに関連付けます。
(「ナビゲータ」)をクリックし、「データ」を選択します。- ManageEmployeesをクリックしてフォームを開きます。

- 「アクション」をクリックし、「編集」を選択してフォームを編集します。
フォーム・エディタに新しい動的タブが表示されます。

- 「Other Options」タブを選択します。

- 「選択したメニュー」リストに「従業員の管理」を追加し、「保存」をクリックします。

- 「OK」をクリックして情報メッセージを閉じます。

- ページの下部で、「編集」ManageEmployees動的タブを閉じてデータ・フォームに戻ります。
Groovyスクリプトのテスト
この項では、開いているManageEmployeesフォームからルールを実行して完全なアドレスを取得して保存し、ジョブ・ログを確認します。
- 「従業員1」を右クリックし、「従業員住所の更新」を選択します。

- 「従業員住所」プロンプトで、
Oracle, Redwood Shoresと入力し、「起動」をクリックします。
- 「OK」をクリックして情報メッセージを閉じます。

正常に完了すると、Googleマップから返された住所全体が従業員1の住所として保存されます。

(ナビゲータ)をクリックし、「アプリケーション」で「ジョブ」を選択してジョブ・コンソールを開きます。
- 「Groovy従業員住所の追加または更新」をクリックして、ジョブ詳細を表示します。

- 「実行ステータス」で、「完了」を展開し、Groovyスクリプトによって出力されるログ・メッセージを表示します。

関連リンク
- Planningチュートリアル— 関心領域リストから「Implementing 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チャネルで無料のラーニング・コンテンツにアクセスしてください。また、Oracle Learning Explorerになるには、education.oracle.com/learning-explorerにアクセスしてください。
製品ドキュメントについては、Oracle Help Centerを参照してください。