Introducción
En este tutorial se muestra cómo llamar a una API de REST externa desde un script Groovy en Oracle EPM Cloud Planning. También aprenderá cómo crear un menú de acción con el botón derecho con un elemento del menú para llamar al script y cómo asociar el menú de acción a un formulario de datos.
Complete las secciones en orden.
Antecedentes
El modelo de objeto Groovy EPM proporciona una forma de llamar a API de REST internas (entre varios POD u otras Oracle Cloud Services) y externas. En este ejemplo, puede crear y ejecutar una regla Groovy para llamar a una API de REST externa de Google Places y agregar o actualizar la información de dirección del empleado en el formulario ManageEmployees.
Requisitos
Los tutoriales prácticos de Cloud EPM pueden requerir que importe una instantánea en una instancia de Cloud EPM Enterprise Service. No se puede importar una instantánea a través de una aplicación o un proceso de negocio existente. Antes de importar la instantánea, utilice una instancia de Cloud EPM Enterprise Service independiente o elimine la aplicación o el proceso de negocio existentes de la instancia que desea utilizar. La importación de la instantánea no sustituye ni restaura automáticamente el contenido existente.
Antes de comenzar este tutorial, debe:
- Tener acceso de administrador de servicio a una instancia de Cloud EPM Enterprise Service.
- Cargue e importe esta instantánea en la instancia de Planning. Si ha cargado previamente esta instantánea para otro tutorial de Groovy, puede continuar utilizando la misma instantánea.
- Antes de empezar a utilizar las API de la plataforma de Google Maps que incluye la API de Places (New) utilizada en este tutorial, debe registrarse y crear una cuenta de facturación para adquirir una clave de API. Para obtener más información, consulte Introducción a la plataforma Google Maps.
Note:
Si se producen errores de migración al importar la instantánea, vuelva a ejecutar la migración excluyendo el componente de HSS-Shared Services, así como los artefactos de seguridad y preferencias de usuario en el componente Core. Para obtener más información sobre la carga y la importación de instantáneas, consulte la documentación de Administración de migración para Oracle Enterprise Performance Management Cloud.Sugerencia:
Los scripts que necesita para este tutorial están enlazados como archivos de texto dentro de cada sección.Carga de variables de cálculo de planificación
En esta sección, se cargan variables de cálculo desde un archivo XML para su uso en el script Groovy.
- Haga clic con el botón derecho en el enlace de HP4_Plan2_Variables.xml y guarde el archivo en la unidad local.
- Haga clic en
(Navegador) y, a continuación, en Crear y gestionar, seleccione Reglas para abrir Calculation Manager.
- En la vista de sistema, amplíe EPM Cloud y, a continuación, HP4. Haga clic con el botón derecho en Plan2 y seleccione Importar.

- En Detalles de importación de archivos, busque y seleccione
HP4_Plan2_Variables.xmlen la unidad local.
- En Detalles de ubicación, seleccione los siguientes valores:
- Tipo de aplicación: EPM Cloud
- Aplicación: HP4
- Cubo: Plan2
- En Opciones de importación, seleccione Sustituir objetos existentes.

- Haga clic en Importar. Revise los resultados de la importación y, a continuación, haga clic en Aceptar.

Note:
El mensaje de cada objeto puede decir "Inserted" (Insertado) o "Updated" (Actualizado). - Haga clic en Cancelar para cerrar el cuadro de diálogo Importar.
Creación de una conexión con nombre en Planning
En esta sección, se crea una conexión de Maps para la API de Google Places.
- Deje Calculation Manager abierto y vuelva a la ventana del explorador de Planning.
- Haga clic en
(Navegador) y, a continuación, en Herramientas, seleccione Conexiones.
- Haga clic en Crear.
- Seleccione Otro proveedor de servicios web.

- Introduzca los siguientes valores:
- Nombre de conexión:
Maps - URL:
https://places.googleapis.com/v1/places:searchText
- Nombre de conexión:
- Haga clic en Mostrar Opciones Avanzadas.

- Defina la cabecera de clave de API mediante los siguientes valores:
- Tipo: Cabecera
- Seguro: seleccionado
- Nombre:
X-Goog-Api-Key - Valor: su clave de API de Google Maps
Mantenga su clave API privada.
- Haga clic en
(Agregar) y defina otra cabecera con los siguientes valores:- Tipo: Cabecera
- Seguro: Borrado
- Nombre:
X-Goog-FieldMask - Valor:
places.formattedAddress

- Haga clic en Guardar y cerrar para guardar la conexión.

Creación de un script Groovy
En esta sección, se crea una regla Groovy para actualizar la dirección de un empleado mediante el formulario predefinido ManageEmployees.

- Vuelva a la ventana del explorador de Calculation Manager.
- En la ficha Vista del sistema, expanda EPM Cloud, HP4 y, a continuación, Plan2. Haga clic con el botón secundario en Reglas y, a continuación, seleccione Nuevo.

- En Nombre, introduzca
Groovy Add or Update Employee Addressy, a continuación, haga clic en Aceptar.
- En el editor de reglas, cambie la opción Diseñador a Editar script y defina el tipo de script en Script de Groovy.

- Copiar esta secuencia de comandos y pegarla en el 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;"""
Defina todas las peticiones de datos en tiempo de ejecución (RTP) utilizadas por esta regla en la primera línea.
Obtenga el objeto Memberpara el empleado especificado por el RTP de empleado.
Utilice el RTP EmployeeAddress como dirección por defecto cuando no se asigne una dirección con formato.
Utilice la conexión de mapas para enviar una solicitud HTTP POST. Defina el tipo de contenido en application/jsony transfiera el valor EmployeeAddress introducido en el campotextQueryde JSON.
Registre el estado HTTP y el cuerpo de respuesta para la resolución de problemas.
Analizar la respuesta de JSON mediante JsonPath. Conecte explícitamente la matriz placesaListpara que la comprobación de tipo estático pueda resolverisEmpty(). Cuando el estado de la respuesta sea correcto y la lista no esté vacía, leaplaces[0].formattedAddress, conviértala en un ID de celda de texto y asígnela aaddress. De lo contrario, mantenga el valor RTP original.
Genere el script de cálculo para guardar la dirección del empleado en la intersección especificada por los RTP.Note:
La conexión de Maps es un enlace de comunicación entre el script Groovy y el recurso API de Google Places (Nuevo). - En la barra de herramientas, haga clic en
(Guardar). Haga clic en OK (Aceptar) para cerrar el mensaje de información.Note:
Al guardar el script, se muestran las variables en el separador Variables.

- En el separador Variables, seleccione Is Hidden (Es oculto) para Employee (Empleado), Entity (Entidad), Period (Período), Scenario (Escenario), Version (Versión) y Year (Año), para que los usuarios introduzcan un valor solo para EmployeeAddress.
Note:
Cuando los usuarios ejecutan la regla desde el formulario, estas variables ocultas reciben valores del contexto del formulario.
- Haga clic en
(Save) nuevamente. Haga clic en OK (Aceptar) para cerrar el mensaje de información. - Haga clic en
(Validar y desplegar). Introduzca los siguientes valores de RTP para la validación:- Empleado:
"Full Time Employees" - Entidad:
"No Entity" - Periodo:
Jan - Escenario:
Current - Versión:
"BU Version_1" - Año:
FY26

- Empleado:
- Seleccione Aplicar valores a la regla para guardar estos valores como valores por defecto para validación y, a continuación, haga clic en Aceptar.
Note:
La validación no ejecuta la regla, pero se necesitan miembros válidos para que la validación se realice correctamente. - Haga clic en Aceptar cuando se le solicite y, a continuación, cierre Calculation Manager.

Creación de menús de acción de planificación para ejecutar scripts Groovy
En esta sección, se crea un menú de acción Gestionar empleados con una opción de menú que ejecuta la regla Groovy.
- En Planificación, haga clic en
(Navegador) y, a continuación, en Crear y gestionar, seleccione Menús de acción.Note:
Si ha completado otros tutoriales de Groovy, es posible que el menú de acción Gestionar empleados ya exista. Si lo hace, continúe con el paso 4. - Haga clic en
(Crear menú) para crear un menú de acción.
- En Nombre de menú, introduzca
Manage Employeesy, a continuación, haga clic en Aceptar.
- Seleccione el menú de acción Gestionar empleados y, a continuación, haga clic en
(Menú Editar).
- Haga clic en
(Agregar secundario). Introduzca o seleccione los siguientes valores:Campo de opción Valor Opción de menú Update Employee AddressEtiqueta Update Employee AddressTipo Regla de negocio Parámetros Necesarios Empleado Cubo Plan2 Regla de negocio Agregar o actualizar dirección de empleado de Groovy 
- Haga clic en Guardar. Cuando aparece el mensaje de confirmación, haga clic en Aceptar.

- Haga clic en Guardar para guardar el menú de acción. Cuando aparece el mensaje de confirmación, haga clic en Aceptar.


- Haga clic en Cancel (Cancelar) para cerrar el editor del menú Action.
Asociación de menús de acción de planificación con formularios
En esta sección, asocie el menú de acción Gestionar empleados con el formulario ManageEmployees.
- Haga clic en
(Navegador) y, a continuación, seleccione Datos. - Haga clic en ManageEmployees para abrir el formulario.

- Haga clic en Acciones y, a continuación, seleccione Editar para editar el formulario.
Se muestra un nuevo separador dinámico con el editor de formularios.

- Seleccione el separador Otras opciones.

- Agregue Gestionar empleados a la lista Menús seleccionados y, a continuación, haga clic en Guardar.

- Haga clic en Aceptar para cerrar el mensaje de información.

- En la parte inferior de la página, cierre el separador dinámico Editar ManageEmployees para volver al formulario de datos.
Prueba del script Groovy
En esta sección, puede ejecutar la regla desde el formulario ManageEmployees abierto para recuperar y guardar una dirección completa y, a continuación, revisar el log de trabajos.
- Haga clic con el botón derecho en Empleado 1 y seleccione Actualizar dirección de empleado.

- En la petición de datos de dirección del empleado, introduzca
Oracle, Redwood Shoresy, a continuación, haga clic en Iniciar.
- Haga clic en Aceptar para cerrar el mensaje de información.

Una vez completada correctamente, la dirección completa devuelta por Google Maps se guarda como la dirección del Empleado 1.

- Haga clic en
(Navegador) y, a continuación, en Aplicación, seleccione Trabajos para abrir la consola de trabajos.
- Haga clic en Agregar o actualizar dirección de empleado de Groovy para mostrar los detalles del trabajo.

- En Estado de ejecución, expanda Completado para ver los mensajes de log impresos por la secuencia de comandos de Groovy.

Enlaces relacionados
- Tutoriales de planificación: seleccione Implementación de Groovy en la lista de áreas de interés para explorar tutoriales de Groovy adicionales.
- Referencia de API de Java para reglas de Groovy: explore las API de Groovy disponibles para desarrollar reglas y plantillas de Groovy.
- API de REST para Oracle Fusion Cloud EPM: explore las API de REST disponibles para gestionar y automatizar las tareas de Cloud EPM.
Más recursos de aprendizaje
Explore otros laboratorios en docs.oracle.com/learn o acceda a más contenido de aprendizaje gratuito en el canal YouTube de Oracle Learning. Además, visite education.oracle.com/learning-explorer para convertirse en un explorador de Oracle Learning.
Para obtener documentación sobre el producto, visite Oracle Help Center.
Llamada a una API REST externa por Groovy
G43146-02
noviembre de 2026