Introduction
This tutorial shows you how to call an external REST API from a Groovy script in Oracle EPM Cloud Planning. You'll also learn how to create a right-click action menu with a menu item to call the script, and how to associate the action menu with a data form.
Complete the sections in order.
Background
The Groovy EPM object model provides a way to call internal (cross-POD or other Oracle Cloud Services) and external REST APIs. In this example, you create and execute a Groovy rule to call an external Google Places REST API to add or update employee address information in the ManageEmployees form.
Prerequisites
Cloud EPM Hands-on Tutorials may require you to import a snapshot into a Cloud EPM Enterprise Service instance. A snapshot cannot be imported over an existing application or business process. Before importing the snapshot, use a separate Cloud EPM Enterprise Service instance or remove the existing application or business process from the instance you plan to use. Importing the snapshot does not automatically replace or restore existing content.
Before starting this tutorial, you must:
- Have Service Administrator access to a Cloud EPM Enterprise Service instance.
- Upload and import this snapshot into your Planning instance. If you've previously uploaded this snapshot for another Groovy tutorial, you can continue using the same snapshot.
- Before you can start using the Google Maps Platform APIs which includes the Places API (New) used in this tutorial, you must sign up and create a billing account to acquire an API key. To learn more, see Get Started with Google Maps Platform.
Note:
If you run into migration errors importing the snapshot, re-run the migration excluding the HSS-Shared Services component, as well as the Security and User Preferences artifacts in the Core component. For more information on uploading and importing snapshots, refer to the Administering Migration for Oracle Enterprise Performance Management Cloud documentation.Tip:
The scripts you need for this tutorial are linked as text files within each section.Loading Planning Calculation Variables
In this section, you upload calculation variables from an XML file for use in the Groovy script.
- Right-click the link for HP4_Plan2_Variables.xml, and save the file to your local drive.
- Click
(Navigator), then, under Create and Manage, select Rules to open Calculation Manager.
- In System View, expand EPM Cloud, then HP4. Right-click Plan2 and select Import.

- Under File Import Details, browse to and select
HP4_Plan2_Variables.xmlfrom your local drive.
- Under Location Details, select the following values:
- Application Type: EPM Cloud
- Application: HP4
- Cube: Plan2
- Under Import Options, select Override Existing Objects.

- Click Import. Review the import results, then click OK.

Note:
The message for each object may say "Inserted" or "Updated." - Click Cancel to close the Import dialog box.
Creating a Named Connection in Planning
In this section, you create a Maps connection for the Google Places API.
- Leave Calculation Manager open and return to the Planning browser window.
- Click
(Navigator), then, under Tools, select Connections.
- Click Create.
- Select Other Web Service Provider.

- Enter the following values:
- Connection Name:
Maps - URL:
https://places.googleapis.com/v1/places:searchText
- Connection Name:
- Click Show Advanced Options.

- Define the API-key header using the following values:
- Type: Header
- Secure: Selected
- Name:
X-Goog-Api-Key - Value: Your Google Maps API key
Keep your API key private.
- Click
(Add) and define another header using the following values:- Type: Header
- Secure: Cleared
- Name:
X-Goog-FieldMask - Value:
places.formattedAddress

- Click Save and Close to save the connection.

Creating a Groovy Script
In this section, you create a Groovy rule to update an employee’s address using the predefined ManageEmployees form.

- Return to the Calculation Manager browser window.
- On the System View tab, expand EPM Cloud, then HP4, then Plan2. Right-click Rules, then select New.

- For Name, enter
Groovy Add or Update Employee Address, then click OK.
- In the Rule Editor, change the Designer option to Edit Script and set the Script Type to Groovy Script.

- Copy this script and paste it into the editor:
/*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;"""
Define all the runtime prompts (RTPs) used by this rule on the first line.
Get the Memberobject for the employee specified by the Employee RTP.
Use the EmployeeAddress RTP as the default address when a formatted address is not assigned.
Use the Maps connection to send an HTTP POST request. Set the content type to application/jsonand pass the entered EmployeeAddress value in the JSONtextQueryfield.
Log the HTTP status and response body for troubleshooting.
Parse the JSON response using JsonPath. Explicitly cast the placesarray toListso static type checking can resolveisEmpty(). When the response status is successful and the list is not empty, readplaces[0].formattedAddress, convert it to a text cell ID, and assign it toaddress. Otherwise, retain the original RTP value.
Generate the calculation script to save the employee address at the intersection specified by the RTPs.Note:
The Maps connection is a communication link between the Groovy Script and the Google Places API (New) resource. - On the toolbar, click
(Save). Click OK to close the information message.Note:
Saving the script displays the variables in the Variables tab.

- In the Variables tab, select Is Hidden for Employee, Entity, Period, Scenario, Version, and Year, so users enter a value only for EmployeeAddress.
Note:
When users run the rule from the form, these hidden variables receive values from the form context.
- Click
(Save) again. Click OK to close the information message. - Click
(Validate and Deploy). Enter the following RTP values for validation:- Employee:
"Full Time Employees" - Entity:
"No Entity" - Period:
Jan - Scenario:
Current - Version:
"BU Version_1" - Year:
FY26

- Employee:
- Select Apply values to the rule to save these values as defaults for validation, then click OK.
Note:
Validation does not execute the rule, but valid members are required for validation to succeed. - Click OK when prompted, then close Calculation Manager.

Creating Planning Action Menus to Run Groovy Scripts
In this section, you create a Manage Employees action menu with a menu item that runs the Groovy rule.
- In Planning, click
(Navigator), then, under Create and Manage, select Action Menus.Note:
If you've completed other Groovy tutorials, the Manage Employees action menu may already exist. If it does, please proceed to step 4. - Click
(Create Menu) to create an action menu.
- For Menu Name, enter
Manage Employees, then click OK.
- Select the Manage Employees action menu, then click
(Edit Menu).
- Click
(Add Child). Enter or select the following values:Option Field Value Menu Item Update Employee AddressLabel Update Employee AddressType Business Rule Required Parameters Employee Cube Plan2 Business Rule Groovy Add or Update Employee Address 
- Click Save. At the confirmation message, click OK.

- Click Save to save the action menu. At the confirmation message, click OK.


- Click Cancel to close the Action Menu editor.
Associating Planning Action Menus with Forms
In this section, you associate the Manage Employees action menu with the ManageEmployees form.
- Click
(Navigator), then select Data. - Click ManageEmployees to open the form.

- Click Actions, then select Edit to edit the form.
A new dynamic tab is displayed with the form editor.

- Select the Other Options tab.

- Add Manage Employees to the Selected Menus list, then click Save.

- Click OK to close the information message.

- At the bottom of the page, close the Edit ManageEmployees dynamic tab to return to the data form.
Testing the Groovy Script
In this section, you run the rule from the open ManageEmployees form to retrieve and save a full address, then review the job log.
- Right-click Employee 1 and select Update Employee Address.

- In the Employee Address prompt, enter
Oracle, Redwood Shores, then click Launch.
- Click OK to close the information message.

On successful completion, the full address returned by Google Maps is saved as the address for Employee 1.

- Click
(Navigator), then, under Application, select Jobs to open the Jobs Console.
- Click Groovy Add or Update Employee Address to display the job details.

- Under Run Status, expand Completed to view the log messages printed by the Groovy script.

Related Links
- Planning Tutorials — Select Implementing Groovy from the area-of-interest list to explore additional Groovy tutorials.
- Java API Reference for Groovy Rules — Explore the Groovy APIs available for developing Groovy rules and templates.
- REST APIs for Oracle Fusion Cloud EPM — Explore the REST APIs available for managing and automating Cloud EPM tasks.
More Learning Resources
Explore other labs on docs.oracle.com/learn or access more free learning content on the Oracle Learning YouTube channel. Additionally, visit education.oracle.com/learning-explorer to become an Oracle Learning Explorer.
For product documentation, visit Oracle Help Center.
Calling an External REST API using Groovy
F88047-03
November 2026