Groovyを使用した外部REST APIのコール

イントロダクション

このチュートリアルでは、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 REST APIを含むGoogle Maps Platform APIの使用を開始する前に、APIキーを取得するために、サインアップして請求アカウントを作成する必要があります。詳細は、Google Mapsプラットフォームの開始を参照してください。

ノート:

スナップショットのインポート中に移行エラーが発生した場合は、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を選択して参照します。
「Location Details」で、次の項目を選択します。

アプリケーション・タイプ: EPM Cloud
アプリケーション: HP4
キューブ: Plan2

「インポート・オプション」で、「既存のオブジェクトの上書き」を選択します。

「インポート」をクリックします。インポート結果を確認し、「OK」をクリックします。
「インポート」ダイアログ・ボックスを閉じるには、「取消」をクリックします。

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

この項では、既存の接続を編集して、場所REST APIキーを含めます。

「ツール」の下の「接続」に移動し、「場所」接続を選択します。

キー・パラメータにAPIキーを入力して接続を編集します。接続を保存してクローズします。

Groovyスクリプトの作成

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

Calculation Managerで、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 maps REST API. Use the original if Google maps can't find the address
def address = rtps.EmployeeAddress  
HttpResponse<String> jsonResponse = operation.application.getConnection("Places")
.get()
.queryParam("input", rtps.EmployeeAddress.enteredValue)
.asString()  
println(jsonResponse.body)  
ReadContext ctx = JsonPath.parse(jsonResponse.body) 
if(ctx.read('$.status') == "OK") 
	address = getTextCellId(ctx.read('$.candidates[0].formatted_address') as String, true) 

// 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)を1行目で定義します。

Employee RTPで指定されたemployeeのメンバー・オブジェクトを取得します。

EmployeeAddress RTPに入力したテキストをaddressのデフォルト値として割り当てます。

Places接続を取得して、このリソースでHTTP GETリクエストを実行し、EmployeeAddress RTPに入力されたテキストをinput問合せパラメータの値として渡します。

ノート:

Places接続オブジェクトは、GroovyスクリプトとGoogle Places REST APIリソース間の通信リンクです。

デバッグ目的でGoogle Maps REST APIレスポンスを記録します。

JsonPathライブラリを使用して、APIから受信したJSONレスポンスを解析します。status == OKの場合、返された配列の最初の候補のオブジェクトからformatted_addressフィールドを読み取り、formatted_addressのテキスト・セルIDを取得し、アドレスに割り当てます。

この従業員住所を保存するための計算スクリプトを生成します。

ツールバーで、(保存)をクリックしてスクリプトを保存します。

ノート:

スクリプトを保存すると、「変数」タブに変数が表示されます。

ユーザーは、EmployeeAddressの値のみを入力できます。「変数」タブで、「従業員」、「エンティティ」、「期間」、「シナリオ」、「バージョン」および「年」に「非表示」を選択します。

ノート:

ユーザーがフォームからスクリプトを実行すると、これらの非表示変数にはフォーム・コンテキストから値が割り当てられます。

スクリプトを再度保存します。
(検証およびデプロイ)をクリックします。検証のためにRTP値を入力します。

従業員: Full Time Employees
エンティティ: No Entity
期間: Jan
シナリオ: Current
バージョン: BU_Version_1
年: FY16

検証目的でこれらの値をデフォルトとして保存するには、「ルールに値を適用」を選択し、「OK」をクリックします。

ノート:

このステップでは、ルールは実行されません。ただし、検証プロセスを成功させるには、有効なメンバーを入力する必要があります。

プロンプトが表示されたら「OK」をクリックし、Calculation Managerを閉じます。

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

この項では、Groovyスクリプトを実行する右クリック・アクション・メニュー項目を使用して、「従業員の管理」というアクション・メニューを作成します。

左上から「ナビゲータ」をクリックし、「アクション・メニュー」(「作成および管理」の下)に移動して、「従業員の管理」という名前のアクション・メニューを作成します。

「従業員の管理」処理メニューを編集し、「従業員住所の更新」という名前の子メニュー項目を追加します。次のオプションを入力または選択して、メニュー項目を定義します。

オプション・フィールド	入力または選択する値
メニュー・アイテム	従業員住所の更新
ラベル	従業員住所の更新
入力してください	ビジネス・ルール
必須パラメータ	従業員
キューブ	Plan2
ビジネス・ルール	Groovy従業員住所の追加または更新