简介
此教程演示如何在 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 教程上载此快照,则可以继续使用相同的快照。
- 在开始使用 Google Maps Platform API(包括本教程中使用的 Places API (New))之前,您必须注册并创建计费账户才能获取 API 密钥。要了解更多信息,请参阅Google Maps Platform 入门。
注意:
如果导入快照时遇到迁移错误,请重新运行迁移(不包括 HSS-Shared Services 组件),以及核心组件中的“安全性”和“用户首选项”对象。有关上载和导入快照的更多信息,请参阅 Administering Migration for Oracle Enterprise Performance Management Cloud 文档。提示:
本教程所需的脚本作为每个部分中的文本文件链接。正在加载 Planning 计算变量
在此部分中,您将从 XML 文件上载计算变量以用于 Groovy 脚本。
- 右键单击 HP4_Plan2_Variables.xml 的链接,然后将文件保存到本地驱动器。
- 单击
(导航器),然后在“Create and Manage(创建和管理)”下,选择规则以打开 Calculation Manager。
- 在“系统视图”中,依次展开 EPM 云和 HP4 。右键单击 Plan2 ,然后选择导入。

- 在“文件导入详细信息”下,浏览到本地驱动器并从中选择
HP4_Plan2_Variables.xml。
- 在“地点详细信息”下,选择以下值:
- 应用程序类型: EPM 云
- 应用程序:HP4
- 多维数据集:Plan2
- 在“导入选项”下,选择覆盖现有对象。

- 单击导入。查看导入结果,然后单击确定。

注意:
每个对象的消息可能会说 "Inserted" 或 "Updated"。 - 单击取消可关闭“导入”对话框。
在 Planning 中创建命名连接
在此部分中,您将为 Google Places API 创建映射连接。
- 将 Calculation Manager 保持打开状态并返回到 Planning 浏览器窗口。
- 单击
(导航器),然后在“工具”下选择连接。
- 单击创建。
- 选择其他 Web 服务提供商。

- 输入以下值:
- 连接名称:
Maps - 网址:
https://places.googleapis.com/v1/places:searchText
- 连接名称:
- 单击显示高级选项。

- 使用以下值定义 API 密钥标头:
- 键入:标题
- 安全:选定
- 产品名称:
X-Goog-Api-Key - 价值:您的 Google Maps API 密钥
保持 API 密钥私密。
- 单击
(添加)并使用以下值定义另一个标题:- 键入:标题
- 安全:已清除
- 产品名称:
X-Goog-FieldMask - 值:
places.formattedAddress

- 单击保存并关闭以保存连接。

创建 Groovy 脚本
在此部分中,您将创建 Groovy 规则,以使用预定义的 ManageEmployees 表单更新员工的地址。

- 返回到 Calculation Manager 浏览器窗口。
- 在“系统视图”选项卡上,依次展开 EPM 云、HP4 和 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 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)。
获取员工 RTP 指定的员工的 Member对象。
未分配格式化地址时,请使用 EmployeeAddress RTP 作为默认地址。
使用映射连接发送 HTTP POST 请求。将内容类型设置为 application/json,并在 JSONtextQuery字段中传递输入的 EmployeeAddress 值。
记录 HTTP 状态和响应正文以进行故障排除。
使用 JsonPath 解析 JSON 响应。将 places数组显式强制转换为List,以便静态类型检查可以解析isEmpty()。当响应状态成功且列表不为空时,读取places[0].formattedAddress,将其转换为文本单元格 ID,然后将其分配给address。否则,保留原始 RTP 值。
生成计算脚本以将员工地址保存在由 RTP 指定的交集处。注意:
Maps 连接是 Groovy 脚本与 Google Places API (New) 资源之间的通信链接。 - 在工具栏中,单击
(保存)。单击 OK(确定)关闭信息消息。注意:
保存脚本将在“Variables(变量)”选项卡中显示变量。

- 在“变量”选项卡中,为员工、实体、期间、方案、版本和年度选择隐藏,以便用户仅为 EmployeeAddress 输入值。
注意:
当用户从表单运行规则时,这些隐藏变量将从表单上下文接收值。
- 再次单击
(Save)。单击确定以关闭信息消息。 - 单击
(Validate and Deploy)。输入以下 RTP 值进行验证:- 员工:
"Full Time Employees" - 实体:
"No Entity" - 期间:
Jan - 方案:
Current - 版本:
"BU Version_1" - 年份:
FY26

- 员工:
- 选择将值应用于规则以将这些值保存为用于验证的默认值,然后单击确定。
注意:
验证不执行规则,但验证成功需要有效的成员。 - 出现提示时单击确定,然后关闭 Calculation Manager。

创建计划操作菜单以运行 Groovy 脚本
在此部分中,您将创建一个“管理员工”操作菜单,其中包含运行 Groovy 规则的菜单项。
- 在 Planning 中,单击
(导航器),然后在“Create and Manage(创建和管理)”下选择 Action Menus(操作菜单)。注意:
如果您已完成其他 Groovy 教程,则可能已存在“管理员工”操作菜单。如果是,请继续执行步骤 4。 - 单击
(创建菜单)以创建操作菜单。
- 对于菜单名称,输入
Manage Employees,然后单击确定。
- 选择管理员工操作菜单,然后单击
(编辑菜单)。
- 单击
(添加子代)。输入或选择以下值:选项字段 值 菜单项 Update Employee Address标签 Update Employee Address类型 业务规则 必需参数 员工 Cube Plan2 业务规则 Groovy 添加或更新员工地址 
- 单击保存。在确认消息时,单击确定。

- 单击保存以保存操作菜单。在确认消息时,单击确定。


- 单击取消可关闭“操作菜单”编辑器。
将计划操作菜单与表单关联
在此部分中,您将“管理员工”操作菜单与 ManageEmployees 表单关联。
- 单击
(导航器),然后选择数据。 - 单击 ManageEmployees 以打开表单。

- 单击操作,然后选择编辑以编辑表单。
此时将显示一个新的动态选项卡,其中包含表单编辑器。

- 选择其他选项选项卡。

- 将管理员工添加到“所选菜单”列表中,然后单击保存。

- 单击确定以关闭信息消息。

- 在页面底部,关闭编辑 ManageEmployees 动态选项卡以返回到数据表单。
测试 Groovy 脚本
在此部分中,您将从打开的 ManageEmployees 表单中运行规则以检索和保存完整地址,然后查看作业日志。
- 右键单击员工 1 ,然后选择更新员工地址。

- 在“员工地址”提示中,输入
Oracle, Redwood Shores,然后单击启动。
- 单击确定以关闭信息消息。

成功完成后,Google Maps 返回的完整地址将保存为员工 1 的地址。

- 单击
(导航器),然后在“应用程序”下,选择作业以打开作业控制台。
- 单击 Groovy Add or Update Employee Address(Groovy 添加或更新员工地址)以显示职务详细信息。

- 在 "Run Status"(运行状态)下,展开 Completed(已完成)以查看 Groovy 脚本打印的日志消息。

相关链接
- Planning 教程 - 从兴趣区域列表中选择实施 Groovy 以浏览其他 Groovy 教程。
- Java API Reference for Groovy Rules(适用于 Groovy 规则的 Java API 参考) —了解可用于开发 Groovy 规则和模板的 Groovy API。
- REST API for Oracle Fusion Cloud EPM —了解可用于管理和自动执行 Cloud EPM 任务的 REST API。
更多学习资源
通过 docs.oracle.com/learn 浏览其他实验室,或者通过 Oracle Learning YouTube 频道访问更多免费学习内容。此外,请访问 education.oracle.com/learning-explorer 以成为 Oracle Learning Explorer。
有关产品文档,请访问 Oracle 帮助中心。