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.

  1. Haga clic con el botón derecho en el enlace de HP4_Plan2_Variables.xml y guarde el archivo en la unidad local.
  2. Haga clic en Navegador (Navegador) y, a continuación, en Crear y gestionar, seleccione Reglas para abrir Calculation Manager.
    Navegador con reglas resaltadas en Crear y gestionar
  3. 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.
    Jerarquía de vista de sistema ampliada con la importación seleccionada para Plan2
  4. En Detalles de importación de archivos, busque y seleccione HP4_Plan2_Variables.xml en la unidad local.
    Cuadro de diálogo Importar con el archivo de variables de cálculo seleccionado
  5. En Detalles de ubicación, seleccione los siguientes valores:
    • Tipo de aplicación: EPM Cloud
    • Aplicación: HP4
    • Cubo: Plan2
  6. En Opciones de importación, seleccione Sustituir objetos existentes.
    Cuadro de diálogo Importar con EPM Cloud, HP4, Plan2 y Sustituir objetos existentes seleccionados
  7. Haga clic en Importar. Revise los resultados de la importación y, a continuación, haga clic en Aceptar.
    Resultados de importación de variable de cálculo

    Note:

    El mensaje de cada objeto puede decir "Inserted" (Insertado) o "Updated" (Actualizado).
  8. 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.

  1. Deje Calculation Manager abierto y vuelva a la ventana del explorador de Planning.
  2. Haga clic en Navegador (Navegador) y, a continuación, en Herramientas, seleccione Conexiones.
    Gestionar Conexiones antes de crear la conexión de Mapas
  3. Haga clic en Crear.
  4. Seleccione Otro proveedor de servicios web.
    Otro proveedor de servicios web resaltado en la página de selección de proveedor
  5. Introduzca los siguientes valores:
    • Nombre de conexión: Maps
    • URL: https://places.googleapis.com/v1/places:searchText
  6. Haga clic en Mostrar Opciones Avanzadas.
    Asigna detalles de conexión con opciones avanzadas mostradas
  7. 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.

  8. Haga clic en Agregar (Agregar) y defina otra cabecera con los siguientes valores:
    • Tipo: Cabecera
    • Seguro: Borrado
    • Nombre: X-Goog-FieldMask
    • Valor: places.formattedAddress
    Asigna la conexión con las cabeceras configuradas y la clave de API enmascarada
  9. Haga clic en Guardar y cerrar para guardar la conexión.
    Gestionar conexiones con la conexión de Mapas guardada

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.

Formulario ManageEmployees para mantener la información de los empleados
  1. Vuelva a la ventana del explorador de Calculation Manager.
  2. 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.
    Vista del sistema ampliada con la opción Nueva seleccionada para la carpeta Reglas Plan2
  3. En Nombre, introduzca Groovy Add or Update Employee Address y, a continuación, haga clic en Aceptar.
    Cuadro de diálogo Nueva regla con el nombre de regla de dirección de empleado
  4. En el editor de reglas, cambie la opción Diseñador a Editar script y defina el tipo de script en Script de Groovy.
    Editor de reglas con el script Edit y Groovy seleccionado
  5. Copiar esta secuencia de comandos y pegarla en el editor:
    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;"""

    Nota de código 1 Defina todas las peticiones de datos en tiempo de ejecución (RTP) utilizadas por esta regla en la primera línea.

    Nota de código 2 Obtenga el objeto Member para el empleado especificado por el RTP de empleado.

    Nota de código 3 Utilice el RTP EmployeeAddress como dirección por defecto cuando no se asigne una dirección con formato.

    Nota de código 4 Utilice la conexión de mapas para enviar una solicitud HTTP POST. Defina el tipo de contenido en application/json y transfiera el valor EmployeeAddress introducido en el campo textQuery de JSON.

    Nota de código 5 Registre el estado HTTP y el cuerpo de respuesta para la resolución de problemas.

    Nota de código 6 Analizar la respuesta de JSON mediante JsonPath. Conecte explícitamente la matriz places a List para que la comprobación de tipo estático pueda resolver isEmpty(). Cuando el estado de la respuesta sea correcto y la lista no esté vacía, lea places[0].formattedAddress, conviértala en un ID de celda de texto y asígnela a address. De lo contrario, mantenga el valor RTP original.

    Nota de código 7 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).
  6. En la barra de herramientas, haga clic en Guardar (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.
    Mensaje de información que confirma que se ha guardado la regla Groovy
    Regla guardada con peticiones de datos en tiempo de ejecución mostradas en el separador Variables
  7. 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.
    Separador Variables con todas las peticiones de datos en tiempo de ejecución excepto EmployeeAddress ocultas
  8. Haga clic en Guardar (Save) nuevamente. Haga clic en OK (Aceptar) para cerrar el mensaje de información.
  9. Haga clic en Validar y desplegar (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
    Cuadro de diálogo Introducir valores de RTP con los miembros de validación y FY26
  10. 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.
  11. Haga clic en Aceptar cuando se le solicite y, a continuación, cierre Calculation Manager.
    Mensaje que confirma el despliegue correcto de la regla

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.

  1. En Planificación, haga clic en Navegador (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.
  2. Haga clic en Crear menú (Crear menú) para crear un menú de acción.
    Cuadro de diálogo Create Menu antes de introducir el nombre del menú
  3. En Nombre de menú, introduzca Manage Employees y, a continuación, haga clic en Aceptar.
    Cuadro de diálogo Crear menú con Gestionar empleados introducidos
  4. Seleccione el menú de acción Gestionar empleados y, a continuación, haga clic en Menú Editar (Menú Editar).
    Menú de acción Gestionar empleados abierto para edición
  5. Haga clic en Agregar hijo (Agregar secundario). Introduzca o seleccione los siguientes valores:
    Campo de opciónValor
    Opción de menúUpdate Employee Address
    EtiquetaUpdate Employee Address
    TipoRegla de negocio
    Parámetros NecesariosEmpleado
    CuboPlan2
    Regla de negocioAgregar o actualizar dirección de empleado de Groovy
    Agregar configuración secundaria para la regla de negocio Actualizar dirección de empleado
  6. Haga clic en Guardar. Cuando aparece el mensaje de confirmación, haga clic en Aceptar.
    Mensaje de información que confirma que la opción de menú se ha guardado
  7. Haga clic en Guardar para guardar el menú de acción. Cuando aparece el mensaje de confirmación, haga clic en Aceptar.
    Mensaje de información que confirma que el menú de acción se ha guardado
    Menú de acción Gestionar empleados guardado que contiene Actualizar dirección de empleado
  8. 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.

  1. Haga clic en Navegador (Navegador) y, a continuación, seleccione Datos.
  2. Haga clic en ManageEmployees para abrir el formulario.
    Formulario ManageEmployees antes de asociar el menú de acciones
  3. 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.

    Menú Acciones con Editar resaltado
  4. Seleccione el separador Otras opciones.
    Separador Other Options en el editor de formularios
  5. Agregue Gestionar empleados a la lista Menús seleccionados y, a continuación, haga clic en Guardar.
    Gestionar empleados agregados a menús seleccionados
  6. Haga clic en Aceptar para cerrar el mensaje de información.
    Mensaje de información que confirma que el formulario se ha guardado
  7. 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.

  1. Haga clic con el botón derecho en Empleado 1 y seleccione Actualizar dirección de empleado.
    Menú contextual Empleado 1 con la opción Actualizar dirección de empleado resaltada
  2. En la petición de datos de dirección del empleado, introduzca Oracle, Redwood Shores y, a continuación, haga clic en Iniciar.
    Petición de datos de dirección de empleado con Oracle, tiendas de Redwood introducidas
  3. Haga clic en Aceptar para cerrar el mensaje de información.
    Mensaje de información que confirma la ejecución correcta de la regla de dirección del empleado

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

    Formulario ManageEmployees con la dirección de empleado formateada guardada para el empleado 1
  4. Haga clic en Navegador (Navegador) y, a continuación, en Aplicación, seleccione Trabajos para abrir la consola de trabajos.
    Página Todos los trabajos en la que se muestra la regla de dirección de empleado completada
  5. Haga clic en Agregar o actualizar dirección de empleado de Groovy para mostrar los detalles del trabajo.
    Detalles de trabajo con valores de petición de datos de tiempo de ejecución contraídos finalizados mostrados
  6. En Estado de ejecución, expanda Completado para ver los mensajes de log impresos por la secuencia de comandos de Groovy.
    Estado Completado ampliado que muestra la respuesta HTTP 200, Google Places y la dirección con formato

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.