Introducción

En este tutorial se muestra cómo llamar a una API de Rest externa desde un script de 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.

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 su instancia de Cloud EPM Enterprise Service. Antes de importar una instantánea de tutorial, debe solicitar otra instancia de Cloud EPM Enterprise Service o eliminar la aplicación y el proceso de negocio actuales. La instantánea del tutorial no se importará a través de su aplicación o proceso de negocio existente, ni reemplazará o restaurará automáticamente la aplicación o el proceso de negocio con el que está trabajando actualmente.

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 la instantánea de 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 REST Places 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.

Cargando variables de cálculo de Planning

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. En la parte superior izquierda, haga clic en Icono de Navegador Navigator y vaya a Rules (Reglas) (en Crear y gestionar) para abrir Calculation Manager. En la vista de sistema, amplíe EPM Cloud > HP4. Haga clic con el botón derecho en Plan2 y seleccione Importar.
  3. En Detalles de importación de archivos, examine para seleccionar HP4_Plan2_Variables.xml en la unidad local.
  4. En Detalles de ubicación, realice las siguientes selecciones:
    • Tipo de aplicación: EPM Cloud
    • Aplicación: HP4
    • Cubo: Plan2
  5. En Opciones de importación, seleccione Sustituir objetos existentes.
    6. Importar variables
  6. Haga clic en Importar. Revise los resultados de importación y, a continuación, haga clic en Aceptar.
    Resultados de Importación
  7. Haga clic en Cancel (Cancelar) para cerrar el cuadro de diálogo Import (Importar).

Creación de una conexión con nombre en Planning

En esta sección, edita una conexión existente para incluir la clave de API de REST Places.

  1. Vaya a Conexiones (en Herramientas) y seleccione la conexión Lugares.
    2. Conexiones
  2. Edite la conexión introduciendo la clave de API en el parámetro de clave. Guarde y cierre la conexión.
    3. Parámetro de clave de API

Creación de un script Groovy

En esta sección, se implementa un script Groovy para actualizar la dirección de un empleado. Trabajaremos con el formulario ManageEmployees predefinido.

Gestionar Empleados
  1. En Calculation Manager, cree una regla denominada Agregar o actualizar dirección de empleado de Groovy en el cubo Plan2.
    2. Nueva regla
  2. En el editor de reglas, cambie la opción Diseñador a Editar script y defina el tipo de script en Script de Groovy.
    3. Opciones del editor de reglas
  3. Copiar esta secuencia de comandos y pegarla en el editor:
    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;"""

    Defina todas las peticiones de datos en tiempo de ejecución (RTP) que utiliza esta regla en la primera línea.

    Obtenga el objeto Member para employee especificado por el RTP de empleado.

    Asigne el texto introducido en el RTP EmployeeAddress como valor por defecto para address.

    Obtenga la conexión Places para ejecutar la solicitud HTTP GET en este recurso y transfiera el texto introducido en el RTP EmployeeAddress como valor para el parámetro de consulta input.

    Note:

    El objeto de conexión Places es un enlace de comunicación entre el script Groovy y el recurso de la API REST de Google Places.

    Registre la respuesta de la API de REST de Google Maps con fines de depuración.

    Analizar la respuesta de JSON recibida de la API mediante la biblioteca JsonPath. Si el estado es == OK, lea el campo formatted_address del primer objeto del candidato en la matriz devuelta, obtenga el ID de celda de texto para formatted_address y asígnelo a la dirección.

    Genere el script de cálculo para guardar esta dirección de empleado.

  4. En la barra de herramientas, haga clic en Guardar (Guardar) para guardar el script.

    5. Note:

    Al guardar el script, se muestran las variables en el separador Variables.
  5. Desea que los usuarios introduzcan valores solo para EmployeeAddress. En el separador Variables, seleccione Is Hidden (Es oculto) para Employee (Empleado), Entity (Entidad), Period (Período), Scenario (Escenario), Version (Versión) y Año.
    6. Variables ocultas

    Note:

    Cuando los usuarios ejecutan el script desde el formulario, a estas variables ocultas se les asignan valores desde el contexto del formulario.
  6. Vuelva a guardar el script.
  7. Haga clic en Validar y desplegar (Validar y desplegar). Introduzca valores de RTP con fines de validación:
    • Empleado: Full Time Employees
    • Entidad: No Entity
    • Periodo: Jan
    • Escenario: Current
    • Versión: BU_Version_1
    • Año: FY16
    Opciones del editor de reglas
  8. Marque Aplicar valores a la regla para guardar estos valores como valores por defecto con fines de validación y, a continuación, haga clic en Aceptar.

    9. Note:

    Durante este paso, la regla no se ejecuta; sin embargo, debe introducir miembros válidos para que el proceso de validación se realice correctamente.
  9. Haga clic en Aceptar cuando se le solicite y, a continuación, cierre Calculation Manager.

Creación de menús de acción Planning para ejecutar scripts Groovy

En esta sección, se crea un menú de acción denominado Gestionar empleados, con una opción de menú de acción de botón derecho que ejecuta el script Groovy.

  1. En la parte superior izquierda, haga clic en Icono de Navegador Navigator y vaya a Action Menus (Menús de acción) (ubicado en Create and Manage) y cree un menú de acción denominado Manage Employees.
    2. Menú de acción Crear gestión de empleados
  2. Edite el menú de acción Gestionar empleados y agregue una opción de menú secundaria denominada Actualizar dirección de empleado. Introduzca o seleccione las siguientes opciones para definir la opción de menú:
    3. Campo de opción Valor que se debe introducir o seleccionar
    Opción de menú Actualizar dirección de empleado
    Etiqueta Actualizar dirección de empleado
    Tipo Regla de negocio
    Parámetros Necesarios Empleado
    Cubo Plan2
    Regla de negocio Agregar o actualizar dirección de empleado de Groovy

    Actualizar opción de menú de dirección de empleado

  3. Haga clic en Save (Guardar) y, a continuación, en OK (Aceptar) para guardar el elemento de menú. Por último, haga clic en Guardar para guardar el menú de acción.
    4. Menú de acción Gestionar empleados completado

Asociación de menús de acción de Planning con formularios

En este paso, asocie el menú de acciones al formulario ManageEmployees y pruebe el script.

  1. Vaya a Formularios (situado en Crear y gestionar) y edite el formulario ManageEmployees.
    2. Editar formulario Gestionar empleados
  2. En el separador Otras opciones, agregue el menú contextual Gestionar empleados a la lista Menús seleccionados.
    3. Agregar el menú contextual Gestionar empleados
  3. Haga clic en Terminar para guardar los cambios en el formulario.
  4. Cierre el gestor de formularios y vuelva a la página Inicio.

Prueba del script Groovy

En este paso, probará el script. El procedimiento de prueba incluye introducir un lugar válido para que el RTP EmployeeAddress recupere la dirección completa del lugar.

  1. En la parte superior izquierda, haga clic en Icono de Navegador Navigator y, a continuación, en Datos para mostrar la lista de formularios de entrada de datos y, a continuación, en ManageEmployees para abrir el formulario Gestionar empleados.
    2. Lista de formularios de entrada de datos
  2. Para probar el script Groovy, haga clic con el botón derecho en Empleado 1 y seleccione la opción de menú Actualizar dirección de empleado.
    3. Cuadro de diálogo Agregar empleado con correo electrónico y nombre no válidos
  3. En la petición de datos de dirección del empleado, escriba Oracle, San José y, a continuación, haga clic en Iniciar.
    4. Mensaje de error de nombre de empleado no válido

    Cuando se inicie correctamente, debería ver la dirección completa de Oracle, San José, guardada como la dirección completa del Empleado 1.

    Mensaje de error de correo electrónico de empleado no válido
  4. Guarde y cierre el formulario. Vaya a Trabajos (en Aplicación) para abrir la consola de trabajos.
    5. Consola de trabajos
  5. Haga clic en Agregar y actualizar dirección de empleado de Groovy para mostrar los detalles del trabajo. Haga clic en el estado Completado para ver los mensajes de log impresos por el script de Groovy.
    6. Mensajes de registro de script de Groovy

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 Oracle University para ver los recursos de formación disponibles.

Para obtener documentación sobre el producto, visite Oracle Help Center.