イントロダクション

このチュートリアルでは、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ファイルからアップロードします。

  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. 「インポート」をクリックします。インポート結果を確認して、「OK」をクリックします。
    計算変数のインポート結果

    ノート:

    各オブジェクトのメッセージは、「Inserted」または「Updated」と表示される場合があります。
  8. 「取消」をクリックして、インポート・ダイアログ・ボックスを閉じます。

Planningでの名前付き接続の作成

この項では、Google Places APIのMaps接続を作成します。

  1. Calculation Managerを開いたまま、Planningブラウザ・ウィンドウに戻ります。
  2. ナビゲータ (Navigator)をクリックし、「Tools (ツール)」の下の「Connections」を選択します。
    マップ接続の作成前の「接続の管理」ページ
  3. 「作成」をクリックします。
  4. 「その他のWebサービス・プロバイダ」を選択します。
    プロバイダ選択ページで強調表示されたその他のWebサービス・プロバイダ
  5. 次の値を入力します:
    • 接続名: Maps
    • URL: https://places.googleapis.com/v1/places:searchText
  6. 「拡張 オプションの表示」をクリックします。
    拡張オプションが表示された接続詳細をマップします
  7. 次の値を使用してAPIキー・ヘッダーを定義します。
    • タイプ: Header
    • 保護: 選択済
    • 名前: X-Goog-Api-Key
    • 値: Google Maps APIキー

    APIキーを秘密に保ちます。

  8. 追加 (「追加」)をクリックし、次の値を使用して別のヘッダーを定義します。
    • タイプ: Header
    • セキュア: クリア済
    • 名前: X-Goog-FieldMask
    • 値: places.formattedAddress
    ヘッダーが構成され、APIキーがマスクされた状態で接続をマップします
  9. 「保存してクローズ」をクリックして、接続を保存します。
    保存されたマップ接続を含む「接続の管理」ページ

Groovyスクリプトの作成

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

従業員情報を保守するためのManageEmployeesフォーム
  1. Calculation Managerのブラウザ・ウィンドウに戻ります。
  2. 「システム・ビュー」タブで、EPM Cloud、HP4、Plan2の順に展開します。「Rules」を右クリックして、「New」を選択します。
    Plan2ルール・フォルダに対して「新規」が選択された拡張システム・ビュー
  3. 「名前」にGroovy Add or Update Employee Addressと入力し、「OK」をクリックします。
    従業員住所ルール名が表示された「新規ルール」ダイアログ
  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に設定し、入力されたEmployeeAddress値をJSONのtextQueryフィールドに渡します。

    コード・ノート5 トラブルシューティングのためにHTTPステータスおよびレスポンス本文をログに記録します。

    コード・ノート6 JsonPathを使用してJSONレスポンスを解析します。静的型チェックでisEmpty()を解決できるように、places配列をListに明示的にキャストします。レスポンス・ステータスが成功し、リストが空でない場合は、places[0].formattedAddressを読み取り、それをテキスト・セルIDに変換して、addressに割り当てます。それ以外の場合は、元のRTP値を保持します。

    コード・ノート7 計算スクリプトを生成して、RTPで指定された交差に従業員住所を保存します。

    ノート:

    Maps接続は、GroovyスクリプトとGoogle Places API (新規)リソース間の通信リンクです。
  6. ツールバーで、保存 (保存)をクリックします。「OK」をクリックして情報メッセージを閉じます。

    ノート:

    スクリプトを保存すると、「変数」タブに変数が表示されます。
    Groovyルールが保存されたことを確認する情報メッセージ
    「変数」タブに表示される実行時プロンプトを含む保存済ルール
  7. 「変数」タブで、「従業員」、「エンティティ」、「期間」、「シナリオ」、「バージョン」および「年」の「非表示」を選択し、ユーザーがEmployeeAddressの値のみを入力します。

    ノート:

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

    ノート:

    検証ではルールが実行されませんが、検証を成功させるには有効なメンバーが必要です。
  11. プロンプトが表示されたら「OK」をクリックし、Calculation Managerを閉じます。
    ルール・デプロイメントの成功を確認するメッセージ

Groovyスクリプトを実行するためのPlanningアクション・メニューの作成

この項では、Groovyルールを実行するメニュー・アイテムを含む「従業員の管理」アクション・メニューを作成します。

  1. Planningで、ナビゲータ (ナビゲータ)をクリックし、「作成および管理」で「アクション・メニュー」を選択します。

    ノート:

    他のGroovyチュートリアルを完了している場合は、「従業員の管理」アクション・メニューがすでに存在している可能性があります。存在する場合は、手順4に進んでください。
  2. 「作成」メニュー (「Create Menu」)をクリックして、アクション・メニューを作成します。
    メニュー名を入力する前に「メニューの作成」ダイアログ
  3. 「Menu Name」にManage Employeesと入力し、「OK」をクリックします。
    「従業員の管理」が入力された「メニューの作成」ダイアログ
  4. 「従業員の管理」アクション・メニューを選択し、「編集」メニュー (「編集」メニュー)をクリックします。
    「従業員の管理」処理メニューが編集のために開かれています
  5. 子の追加 (子の追加)をクリックします。次の値を入力または選択します。
    オプション・フィールド値
    メニュー・アイテムUpdate Employee Address
    ラベルUpdate Employee Address
    入力してくださいビジネス・ルール
    必須パラメータ社員
    キューブPlan2
    ビジネス・ルールGroovy従業員住所の追加または更新
    「従業員住所の更新」ビジネス・ルールの子設定の追加
  6. 「保存」をクリックします。確認メッセージで、「OK」をクリックします。
    メニュー項目が保存されたことを確認する情報メッセージ
  7. 「保存」をクリックして、アクション・メニューを保存します。確認メッセージで、「OK」をクリックします。
    処理メニューが保存されたことを確認する情報メッセージ
    従業員住所の更新を含む保存済「従業員の管理」処理メニュー
  8. 「取消」をクリックすると、アクション・メニュー・エディタが閉じます。

プランニング処理メニューとフォームの関連付け

この項では、「従業員の管理」アクション・メニューをManageEmployeesフォームに関連付けます。

  1. ナビゲータ(「ナビゲータ」)をクリックし、「データ」を選択します。
  2. ManageEmployeesをクリックしてフォームを開きます。
    アクション・メニューを関連付ける前のManageEmployeesフォーム
  3. 「アクション」をクリックし、「編集」を選択してフォームを編集します。

    フォーム・エディタに新しい動的タブが表示されます。

    「編集」が強調表示された「アクション」メニュー
  4. 「Other Options」タブを選択します。
    フォーム・エディタの「その他のオプション」タブ
  5. 「選択したメニュー」リストに「従業員の管理」を追加し、「保存」をクリックします。
    選択したメニューに追加された従業員の管理
  6. 「OK」をクリックして情報メッセージを閉じます。
    フォームが保存されたことを確認する情報メッセージ
  7. ページの下部で、「編集」ManageEmployees動的タブを閉じてデータ・フォームに戻ります。

Groovyスクリプトのテスト

この項では、開いているManageEmployeesフォームからルールを実行して完全なアドレスを取得して保存し、ジョブ・ログを確認します。

  1. 「従業員1」を右クリックし、「従業員住所の更新」を選択します。
    従業員住所の更新が強調表示された従業員1コンテキスト・メニュー
  2. 「従業員住所」プロンプトで、Oracle, Redwood Shoresと入力し、「起動」をクリックします。
    Oracle、Redwood Shoresが入力された従業員住所プロンプト
  3. 「OK」をクリックして情報メッセージを閉じます。
    従業員住所ルールが正常に実行されたことを確認する情報メッセージ

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

    従業員1用に保存された書式設定された従業員住所を含むManageEmployeesフォーム
  4. ナビゲータ (ナビゲータ)をクリックし、「アプリケーション」で「ジョブ」を選択してジョブ・コンソールを開きます。
    完了した従業員住所ルールが表示された「すべてのジョブ」ページ
  5. 「Groovy従業員住所の追加または更新」をクリックして、ジョブ詳細を表示します。
    「Completed(完了)」と表示された「Job Details(ジョブ詳細)」と実行時プロンプト値
  6. 「実行ステータス」で、「完了」を展開し、Groovyスクリプトによって出力されるログ・メッセージを表示します。
    HTTP 200、Google Placesレスポンスおよびフォーマット済アドレスを示す拡張完了ステータス

その他の学習リソース

docs.oracle.com/learnの他のラボを調べるか、Oracle Learning YouTubeチャネルで無料のラーニング・コンテンツにアクセスしてください。また、Oracle Learning Explorerになるには、education.oracle.com/learning-explorerにアクセスしてください。

製品ドキュメントについては、Oracle Help Centerを参照してください。