简介

此教程演示如何在 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 脚本。

  1. 右键单击 HP4_Plan2_Variables.xml 的链接,然后将文件保存到本地驱动器。
  2. 单击 导航器(导航器),然后在“Create and Manage(创建和管理)”下,选择规则以打开 Calculation Manager。
    “Create and Manage(创建和管理)”下突出显示的规则导航器
  3. 在“系统视图”中,依次展开 EPM 云和 HP4 。右键单击 Plan2 ,然后选择导入。
    为 Plan2 选择了“导入”的扩展系统视图层次结构
  4. 在“文件导入详细信息”下,浏览到本地驱动器并从中选择 HP4_Plan2_Variables.xml。
    选择了计算变量文件的“导入”对话框
  5. 在“地点详细信息”下,选择以下值:
    • 应用程序类型: EPM 云
    • 应用程序:HP4
    • 多维数据集:Plan2
  6. 在“导入选项”下,选择覆盖现有对象。
    选择了 EPM 云、HP4、Plan2 和覆盖现有对象的“导入”对话框
  7. 单击导入。查看导入结果,然后单击确定。
    计算变量导入结果

    注意:

    每个对象的消息可能会说 "Inserted" 或 "Updated"。
  8. 单击取消可关闭“导入”对话框。

在 Planning 中创建命名连接

在此部分中,您将为 Google Places API 创建映射连接。

  1. 将 Calculation Manager 保持打开状态并返回到 Planning 浏览器窗口。
  2. 单击 导航器(导航器),然后在“工具”下选择连接。
    在创建映射连接之前管理连接页
  3. 单击创建。
  4. 选择其他 Web 服务提供商。
    在提供程序选择页上突出显示的其他 Web 服务提供程序
  5. 输入以下值:
    • 连接名称:Maps
    • 网址:https://places.googleapis.com/v1/places:searchText
  6. 单击显示高级选项。
    将连接详细信息映射到显示的高级选项
  7. 使用以下值定义 API 密钥标头:
    • 键入:标题
    • 安全:选定
    • 产品名称:X-Goog-Api-Key
    • 价值:您的 Google Maps API 密钥

    保持 API 密钥私密。

  8. 单击 添加(添加)并使用以下值定义另一个标题:
    • 键入:标题
    • 安全:已清除
    • 产品名称:X-Goog-FieldMask
    • 值:places.formattedAddress
    配置了标头并屏蔽了 API 密钥的映射连接
  9. 单击保存并关闭以保存连接。
    使用保存的映射连接管理连接页

创建 Groovy 脚本

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

用于维护员工信息的 ManageEmployees 表单
  1. 返回到 Calculation Manager 浏览器窗口。
  2. 在“系统视图”选项卡上,依次展开 EPM 云、HP4 和 Plan2 。右键单击规则,然后选择新建。
    为 Plan2 规则文件夹选择了“新建”的扩展系统视图
  3. 对于“名称”,输入 Groovy Add or Update Employee Address,然后单击确定。
    包含员工地址规则名称的新规则对话框
  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 获取员工 RTP 指定的员工的 Member 对象。

    代码注释 3 未分配格式化地址时,请使用 EmployeeAddress RTP 作为默认地址。

    代码注释 4 使用映射连接发送 HTTP POST 请求。将内容类型设置为 application/json,并在 JSON textQuery 字段中传递输入的 EmployeeAddress 值。

    代码注释 5 记录 HTTP 状态和响应正文以进行故障排除。

    代码注释 6 使用 JsonPath 解析 JSON 响应。将 places 数组显式强制转换为 List,以便静态类型检查可以解析 isEmpty()。当响应状态成功且列表不为空时,读取 places[0].formattedAddress,将其转换为文本单元格 ID,然后将其分配给 address。否则,保留原始 RTP 值。

    代码注释 7 生成计算脚本以将员工地址保存在由 RTP 指定的交集处。

    注意:

    Maps 连接是 Groovy 脚本与 Google Places API (New) 资源之间的通信链接。
  6. 在工具栏中,单击 保存(保存)。单击 OK(确定)关闭信息消息。

    注意:

    保存脚本将在“Variables(变量)”选项卡中显示变量。
    确认已保存 Groovy 规则的信息消息
    在“Variables(变量)”选项卡中显示运行时提示的已保存规则
  7. 在“变量”选项卡中,为员工、实体、期间、方案、版本和年度选择隐藏,以便用户仅为 EmployeeAddress 输入值。

    注意:

    当用户从表单运行规则时,这些隐藏变量将从表单上下文接收值。
    隐藏除 EmployeeAddress 以外的所有运行时提示的 "Variables"(变量)选项卡
  8. 再次单击 保存 (Save)。单击确定以关闭信息消息。
  9. 单击 验证和部署 (Validate and Deploy)。输入以下 RTP 值进行验证:
    • 员工:"Full Time Employees"
    • 实体:"No Entity"
    • 期间:Jan
    • 方案:Current
    • 版本:"BU Version_1"
    • 年份:FY26
    包含验证成员和 FY26 的 "Enter RTP Values"(输入 RTP 值)对话框
  10. 选择将值应用于规则以将这些值保存为用于验证的默认值,然后单击确定。

    注意:

    验证不执行规则,但验证成功需要有效的成员。
  11. 出现提示时单击确定,然后关闭 Calculation Manager。
    消息确认规则部署成功

创建计划操作菜单以运行 Groovy 脚本

在此部分中,您将创建一个“管理员工”操作菜单,其中包含运行 Groovy 规则的菜单项。

  1. 在 Planning 中,单击 导航器(导航器),然后在“Create and Manage(创建和管理)”下选择 Action Menus(操作菜单)。

    注意:

    如果您已完成其他 Groovy 教程,则可能已存在“管理员工”操作菜单。如果是,请继续执行步骤 4。
  2. 单击 创建菜单(创建菜单)以创建操作菜单。
    在输入菜单名称之前创建菜单对话框
  3. 对于菜单名称,输入 Manage Employees,然后单击确定。
    输入了“管理员工”的“创建菜单”对话框
  4. 选择管理员工操作菜单,然后单击 “编辑”菜单(编辑菜单)。
    “管理员工”操作菜单打开进行编辑
  5. 单击 添加子代(添加子代)。输入或选择以下值:
    选项字段值
    菜单项Update Employee Address
    标签Update Employee Address
    类型业务规则
    必需参数员工
    CubePlan2
    业务规则Groovy 添加或更新员工地址
    为“更新员工地址”业务规则添加子设置
  6. 单击保存。在确认消息时,单击确定。
    确认已保存菜单项的信息消息
  7. 单击保存以保存操作菜单。在确认消息时,单击确定。
    确认操作菜单已保存的信息消息
    包含更新员工地址的已保存“管理员工”操作菜单
  8. 单击取消可关闭“操作菜单”编辑器。

将计划操作菜单与表单关联

在此部分中,您将“管理员工”操作菜单与 ManageEmployees 表单关联。

  1. 单击 导航器(导航器),然后选择数据。
  2. 单击 ManageEmployees 以打开表单。
    关联操作菜单之前的 ManageEmployees 表单
  3. 单击操作,然后选择编辑以编辑表单。

    此时将显示一个新的动态选项卡,其中包含表单编辑器。

    突出显示了 "Edit" 的 "Actions" 菜单
  4. 选择其他选项选项卡。
    表单编辑器中的“Other Options(其他选项)”选项卡
  5. 将管理员工添加到“所选菜单”列表中,然后单击保存。
    管理添加到选定菜单的员工
  6. 单击确定以关闭信息消息。
    确认表单已保存的信息消息
  7. 在页面底部,关闭编辑 ManageEmployees 动态选项卡以返回到数据表单。

测试 Groovy 脚本

在此部分中,您将从打开的 ManageEmployees 表单中运行规则以检索和保存完整地址,然后查看作业日志。

  1. 右键单击员工 1 ,然后选择更新员工地址。
    突出显示了“更新员工地址”的员工 1 上下文菜单
  2. 在“员工地址”提示中,输入 Oracle, Redwood Shores,然后单击启动。
    输入了 Oracle 的员工地址提示,Redwood Shores
  3. 单击确定以关闭信息消息。
    确认员工地址规则成功执行的信息消息

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

    ManageEmployees 表单,其中为员工 1 保存了格式化的员工地址
  4. 单击 导航器(导航器),然后在“应用程序”下,选择作业以打开作业控制台。
    显示已完成员工地址规则的“所有职务”页面
  5. 单击 Groovy Add or Update Employee Address(Groovy 添加或更新员工地址)以显示职务详细信息。
    显示了“已完成”折叠和运行时提示值的作业详细信息
  6. 在 "Run Status"(运行状态)下,展开 Completed(已完成)以查看 Groovy 脚本打印的日志消息。
    “展开已完成”状态,其中显示 HTTP 200、Google Places 响应和格式化地址

更多学习资源

通过 docs.oracle.com/learn 浏览其他实验室,或者通过 Oracle Learning YouTube 频道访问更多免费学习内容。此外,请访问 education.oracle.com/learning-explorer 以成为 Oracle Learning Explorer。

有关产品文档,请访问 Oracle 帮助中心。