简介

此教程演示如何在 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 地图平台 API（包括本教程中使用的位置 REST API）之前，您必须注册并创建计费账户才能获取 API 密钥。要了解更多信息，请参阅Google Maps Platform 入门。

注意：

如果导入快照时遇到迁移错误，请重新运行迁移（不包括 HSS-Shared Services 组件），以及核心组件中的“安全性”和“用户首选项”对象。有关上载和导入快照的更多信息，请参阅 Administering Migration for Oracle Enterprise Performance Management Cloud 文档。

提示：

本教程所需的脚本作为每个部分中的文本文件链接。

正在加载 Planning 计算变量

在此部分中，您将从 XML 文件上载计算变量以用于 Groovy 脚本。

  1. 右键单击 HP4_Plan2_Variables.xml 的链接，然后将文件保存到本地驱动器。
  2. 从左上角，单击 “浏览器”图标 导航器并导航到规则（在“创建和管理”下），以打开 Calculation Manager。在“系统视图”中，展开 EPM 云 > HP4 。右键单击 Plan2 ，然后选择导入。
  3. 在“文件导入详细信息”下，浏览以从本地驱动器中选择 HP4_Plan2_Variables.xml 。
  4. 在“Location Details（地点详细信息）”下，进行以下选择：
    • 应用程序类型：EPM 云
    • 应用：HP4
    • 多维数据集：Plan2
  5. 在“导入选项”下，选择覆盖现有对象。
    6. 导入变体
  6. 单击导入。查看导入结果，然后单击确定。
    导入成果
  7. 单击取消以关闭“导入”对话框。

在 Planning 中创建命名连接

在此部分中，您可以编辑现有连接以包括位置 REST API 密钥。

  1. 导航到连接（在“工具”下），然后选择位置连接。
    2. 连接
  2. 通过在密钥参数中输入 API 密钥来编辑连接。保存并关闭连接。
    3. API 密钥参数

创建 Groovy 脚本

在此部分中，将实施 Groovy 脚本以更新员工地址。我们将使用预定义的 ManageEmployees 表单。

管理雇员
  1. 在 Calculation Manager 中，在 Plan2 多维数据集中创建名为 Groovy Add or Update Employee Address 的规则。
    2. 新建规则
  2. 在规则编辑器中，将设计器选项更改为编辑脚本，并将脚本类型设置为 Groovy 脚本。
    3. 规则编辑器选项
  3. 复制此脚本并将其粘贴到编辑器中：
    4. /*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)。

    获取由员工 RTP 指定的 employee 的 Member 对象。

    将在 EmployeeAddress RTP 中输入的文本指定为 address 的默认值。

    获取 Places 连接以对此资源执行 HTTP GET 请求，并将 EmployeeAddress RTP 中输入的文本作为 input 查询参数的值传递。

    注意：

    Places 连接对象是 Groovy 脚本与 Google Places REST API 资源之间的通信链接。

    记录 Google Maps REST API 响应以实现调试目的。

    使用 JsonPath 库分析从 API 接收的 JSON 响应。如果状态 == OK，请从返回数组中的第一个候选对象中读取 formatted_address 字段，获取 formatted_address 的文本单元格 ID 并将其分配给地址。

    生成计算脚本以保存此员工地址。

  4. 在工具栏上，单击 保存（保存）以保存脚本。

    5. 注意：

    保存脚本将在“Variables（变量）”选项卡中显示变量。
  5. 您希望用户仅为 EmployeeAddress 输入值。在“变量”选项卡中，为员工、实体、期间、方案、版本和年度选择隐藏。
    6. 隐藏变量

    注意：

    当用户从表单运行脚本时，会从表单上下文为这些隐藏变量赋值。
  6. 再次保存脚本。
  7. 单击 验证和部署 (Validate and Deploy)。输入用于验证的 RTP 值：
    • 员工：Full Time Employees
    • 实体：No Entity
    • 期间：Jan
    • 方案：Current
    • 版本：BU_Version_1
    • 年份：FY16
    规则编辑器选项
  8. 选中将值应用于规则以将这些值保存为默认值以进行验证，然后单击确定。

    9. 注意：

    在此步骤中，规则不会执行；但是，您必须输入有效的成员，验证过程才能成功。
  9. 出现提示时单击确定，然后关闭 Calculation Manager。

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

在此部分中，您将创建一个名为“管理员工”的操作菜单，其中包含用于运行 Groovy 脚本的右键单击操作菜单项。

  1. 从左上角，单击 “浏览器”图标 导航器并导航到操作菜单（位于“创建和管理”下），然后创建名为管理员工的操作菜单。
    2. 创建管理员工操作菜单
  2. 编辑“管理员工”操作菜单并添加名为更新员工地址的子菜单项。输入或选择以下选项以定义菜单项：
    3. 选项字段 要输入或选择的值
    菜单项 更新员工地址
    标签 更新员工地址
    类型 业务规则
    必需参数 员工
    Cube Plan2
    业务规则 Groovy 添加或更新员工地址

    更新员工地址菜单项

  3. 单击保存，然后单击确定以保存菜单项。最后，单击保存以保存操作菜单。
    4. 已完成管理员工操作菜单

将 Planning 操作菜单与表单关联

在此步骤中，您将操作菜单与 ManageEmployees 表单关联并测试脚本。

  1. 导航到表单（位于“创建和管理”下）并编辑 ManageEmployees 表单。
    2. 编辑“管理员工”表单
  2. 在“其他选项”选项卡上，将管理员工上下文菜单添加到“所选菜单”列表中。
    3. 添加管理员工上下文菜单
  3. 单击完成以保存对表单所做的更改。
  4. 关闭表单管理器并返回到主页。

测试 Groovy 脚本

在此步骤中，您将测试脚本。测试过程包括为 EmployeeAddress RTP 输入有效位置以检索该位置的完整地址。

  1. 从左上角，单击 “浏览器”图标 导航器，然后单击数据以显示数据输入表单的列表，然后单击 ManageEmployees 以打开“管理员工”表单。
    2. 数据输入表单列表
  2. 要测试 Groovy 脚本，请右键单击 Employee 1 ，然后选择 Update Employee Address（更新员工地址）菜单项。
    3. 添加具有无效电子邮件和名称的员工对话框
  3. 在“员工地址”提示中，键入 Oracle，San Jose ，然后单击启动。
    4. 员工姓名错误消息无效

    成功启动后，您应该会看到 Oracle 的完整地址，San Jose 将其保存为员工 1 的完整地址。

    员工电子邮件错误消息无效
  4. 保存并关闭该表单。导航到 Jobs（作业）（在应用程序下）以打开作业控制台。
    5. 作业控制台
  5. 单击 Groovy Add and Update Employee Address 以显示职务详细信息。单击已完成状态可查看 Groovy 脚本打印的日志消息。
    6. Groovy 脚本日志消息

更多学习资源

通过 docs.oracle.com/learn 浏览其他实验室，或者通过 Oracle Learning YouTube 频道访问更多免费学习内容。此外，请访问 Oracle University 查看可用的培训资源。

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