Introdução

Este tutorial mostra como chamar uma API REST externa de um script Groovy no Oracle EPM Cloud Planning. Você também aprenderá a criar um menu de ação de clique com o botão direito do mouse com um item de menu para chamar o script e a associar o menu de ação a um formulário de dados.

Complete as seções em ordem.

Histórico

O modelo de objeto Groovy EPM fornece uma maneira de chamar APIs REST internas (POD cruzado ou outro Oracle Cloud Services) e externas. Neste exemplo, você cria e executa uma regra do Groovy para chamar uma API REST externa do Google Places para adicionar ou atualizar informações de endereço do funcionário no formulário ManageEmployees.

Pré-requisitos

Os Tutoriais Práticos do Cloud EPM podem exigir que você importe um instantâneo para uma instância do Cloud EPM Enterprise Service. Um instantâneo não pode ser importado em um aplicativo ou processo de negócios existente. Antes de importar o instantâneo, use uma instância separada do Cloud EPM Enterprise Service ou remova o aplicativo ou processo de negócios existente da instância que você planeja usar. A importação do snapshot não substitui nem restaura automaticamente o conteúdo existente.

Antes de iniciar este tutorial, você deve:

  • Tenha acesso do Administrador de Serviço a uma instância do Cloud EPM Enterprise Service.
  • Faça upload e importe este snapshot para sua instância do Planning. Se você já tiver feito upload deste snapshot para outro tutorial do Groovy, poderá continuar usando o mesmo snapshot.
  • Antes de começar a usar as APIs do Google Maps Platform que incluem a API Places (Novo) usada neste tutorial, você deve se inscrever e criar uma conta de faturamento para adquirir uma chave de API. Para saber mais, consulte Conceitos Básicos do Google Maps Platform.

Observação:

Se você encontrar erros de migração importando o snapshot, execute novamente a migração excluindo o componente HSS-Shared Services, bem como os artefatos Segurança e Preferências do Usuário no componente Principal. Para obter mais informações sobre upload e importação de snapshots, consulte a documentação Administrando a Migração para o Oracle Enterprise Performance Management Cloud.

Dica:

Os scripts necessários para este tutorial são vinculados como arquivos de texto em cada seção.

Carregando Variáveis de Cálculo de Planejamento

Nesta seção, você faz upload de variáveis de cálculo de um arquivo XML para uso no script Groovy.

  1. Clique com o botão direito do mouse no link do HP4_Plan2_Variables.xml e salve o arquivo na unidade local.
  2. Clique em Navegador (Navegador) e, em Criar e Gerenciar, selecione Regras para abrir o Calculation Manager.
    Navegador com Regras destacadas em Criar e Gerenciar
  3. Na Exibição de Sistema, expanda EPM Cloud e, em seguida, HP4. Clique com o botão direito do mouse em Plan2 e selecione Importar.
    Hierarquia de Exibição do Sistema Expandida com Importação selecionada para Plan2
  4. Em Detalhes da Importação de Arquivos, procure e selecione HP4_Plan2_Variables.xml na sua unidade local.
    Caixa de diálogo Importar com o arquivo de variáveis de cálculo selecionado
  5. Em Detalhes do local, selecione os seguintes valores:
    • Tipo de Aplicativo: EPM Cloud
    • Aplicativo: HP4
    • Cubo: Plan2
  6. Em Opções de Importação, selecione Substituir Objetos Existentes.
    Caixa de diálogo Importar com o EPM Cloud, HP4, Plan2 e Substituir Objetos Existentes selecionados
  7. Clique em Importar. Verifique os resultados da importação e clique em OK.
    Resultados da importação da variável de cálculo

    Observação:

    A mensagem para cada objeto pode dizer "Inserted" ou "Updated".
  8. Clique em Cancelar para fechar a caixa de diálogo Importar.

Criando uma Conexão Nomeada no Planning

Nesta seção, você cria uma conexão do Maps para a API do Google Places.

  1. Deixe o Calculation Manager aberto e retorne à janela do navegador Planning.
  2. Clique em Navegador (Navegador) e, em Tools, selecione Connections.
    Página Gerenciar Conexões antes de criar a conexão de Mapas
  3. Clique em Criar.
  4. Selecione Outro Provedor de Serviços Web.
    Outro Provedor de Serviços Web destacado na página de seleção do provedor
  5. Informe os seguintes valores:
    • Nome da Conexão: Maps
    • URL: https://places.googleapis.com/v1/places:searchText
  6. Clique em Mostrar Opções Avançadas.
    Mapeia detalhes de conexão com opções avançadas exibidas
  7. Defina o cabeçalho de chave de API usando os seguintes valores:
    • Tipo: Cabeçalho
    • Seguro: Selecionado
    • Nome: X-Goog-Api-Key
    • Valor: Sua chave de API do Google Maps

    Mantenha sua chave de API privada.

  8. Clique em Adicionar (Adicionar) e defina outro cabeçalho usando os seguintes valores:
    • Tipo: Cabeçalho
    • Seguro: Compensado
    • Nome: X-Goog-FieldMask
    • Valor: places.formattedAddress
    Mapeia a conexão com ambos os cabeçalhos configurados e a chave de API mascarada
  9. Clique em Salvar e Fechar para salvar a conexão.
    Página Gerenciar Conexões com a conexão de Mapas salva

Criando um Script Groovy

Nesta seção, você cria uma regra do Groovy para atualizar o endereço de um funcionário usando o formulário predefinido ManageEmployees.

Formulário ManageEmployees para manutenção de informações do funcionário
  1. Retorne à janela do navegador Calculation Manager.
  2. Na guia Exibição de Sistema, expanda EPM Cloud, HP4 e Plan2. Clique com o mouse em Regras e selecione Novo.
    Exibição do Sistema Expandida com Novo selecionado para a pasta Regras Plan2
  3. Para Nome, digite Groovy Add or Update Employee Address e clique em OK.
    Caixa de diálogo Nova Regra com o nome da regra de endereço do funcionário
  4. No Editor de Regras, altere a opção Designer para Editar Script e defina o Tipo de Script como Script Groovy.
    Editor de Regras com Script de Edição e Script Groovy selecionados
  5. Copiar este script e colá-lo no 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 as solicitações de tempo de execução (RTPs) usadas por essa regra na primeira linha.

    Nota de código 2 Obtenha o objeto Member para o funcionário especificado pelo RTP do Funcionário.

    Nota de código 3 Use o RTP EmployeeAddress como o endereço padrão quando um endereço formatado não for atribuído.

    Nota de código 4 Use a Conexão de mapas para enviar uma solicitação HTTP POST. Defina o tipo de conteúdo como application/json e informe o valor EmployeeAddress informado no campo textQuery JSON.

    Nota de código 5 Registre o status HTTP e o corpo da resposta para solucionar problemas.

    Nota de código 6 Faça parse da resposta JSON usando JsonPath. Converta explicitamente o array places em List para que a verificação de tipo estático possa resolver isEmpty(). Quando o status da resposta for bem-sucedido e a lista não estiver vazia, leia places[0].formattedAddress, converta-a em um ID de célula de texto e atribua-a a address. Caso contrário, mantenha o valor RTP original.

    Nota de código 7 Gere o script de cálculo para salvar o endereço do funcionário na interseção especificada pelos RTPs.

    Observação:

    A conexão do Maps é um link de comunicação entre o Script Groovy e o recurso API do Google Places (Novo).
  6. Na barra de ferramentas, clique em Salvar (Salvar). Clique em OK para fechar a mensagem de informações.

    Observação:

    Salvar o script exibe as variáveis na guia Variáveis.
    Mensagem de informação confirmando que a regra Groovy foi salva
    Regra salva com prompts de tempo de execução exibidos na guia Variáveis
  7. Na guia Variáveis, selecione Está Oculto para Funcionário, Entidade, Período, Cenário, Versão e Ano, para que os usuários insiram um valor apenas para EmployeeAddress.

    Observação:

    Quando os usuários executam a regra no formulário, essas variáveis ocultas recebem valores do contexto do formulário.
    Guia Variáveis com todos os prompts de runtime, exceto EmployeeAddress oculto
  8. Clique em Salvar (Salvar) novamente. Clique em OK para fechar a mensagem de informações.
  9. Clique em Validar e Implantar (Validar e Implantar). Informe os seguintes valores de RTP para validação:
    • Funcionário: "Full Time Employees"
    • Entidade: "No Entity"
    • Período: Jan
    • Cenário: Current
    • Versão: "BU Version_1" de
    • Ano: FY26
    Caixa de diálogo Informar Valores de RTP com os membros de validação e FY26
  10. Selecione Aplicar valores à regra para salvar esses valores como padrões para validação e clique em OK.

    Observação:

    A validação não executa a regra, mas são necessários membros válidos para que a validação seja bem-sucedida.
  11. Clique em OK quando solicitado e feche o Calculation Manager.
    Mensagem confirmando implantação de regra bem-sucedida

Criando Menus de Ação de Planejamento para Executar Scripts Groovy

Nesta seção, você cria um menu de ação Gerenciar Funcionários com um item de menu que executa a regra Groovy.

  1. No Planning, clique em Navegador (Navegador) e, em Criar e Gerenciar, selecione Menus de Ação.

    Observação:

    Se você tiver concluído outros tutoriais do Groovy, talvez o menu de ação Gerenciar Funcionários já exista. Se isso acontecer, prossiga para a etapa 4.
  2. Clique em Menu Criar (Criar Menu) para criar um menu de ação.
    Caixa de diálogo Create Menu antes de inserir o nome do menu
  3. Para Nome do Menu, digite Manage Employees e clique em OK.
    Caixa de diálogo Criar Menu com Gerenciar Funcionários informados
  4. Selecione o menu de ação Gerenciar Funcionários e clique em Menu Editar (Menu Editar).
    Menu de ação Gerenciar Funcionários aberto para edição
  5. Em Adicionar Filho (Adicionar Filho). Insira ou selecione os seguintes valores:
    Campo de opçãoValor
    Item do MenuUpdate Employee Address
    LabelUpdate Employee Address
    TipoRegra de Negócios
    Parâmetros ObrigatóriosFuncionário
    CuboPlan2
    Regra de NegóciosGroovy - Adicionar ou Atualizar Endereço do Funcionário
    Adicionar configurações Filho para a regra de negócios Atualizar Endereço do Funcionário
  6. Clique em Salvar. Na mensagem de confirmação, clique em OK.
    Mensagem de informação confirmando que o item de menu foi salvo
  7. Clique em Salvar para salvar o menu de ação. Na mensagem de confirmação, clique em OK.
    Mensagem de informação confirmando que o menu de ação foi salvo
    Menu de ação Gerenciar Funcionários Salvos contendo Atualizar Endereço do Funcionário
  8. Clique em Cancelar para fechar o editor do Menu de Ações.

Associando Menus de Ação de Planejamento a Formulários

Nesta seção, você associa o menu de ação Gerenciar Funcionários ao formulário ManageEmployees.

  1. Clique em Navegador (Navegador) e selecione Dados.
  2. Clique em ManageEmployees para abrir o formulário.
    form ManageEmployees antes de associar o menu de ação
  3. Clique em Ações e, em seguida, selecione Editar para editar o formulário.

    Uma nova guia dinâmica é exibida com o editor de formulários.

    Menu Ações com Editar destacado
  4. Selecione a guia Outras Opções.
    Guia Outras Opções no editor de formulários
  5. Adicione Gerenciar Funcionários à lista Menus Selecionados e clique em Salvar.
    Gerenciar Funcionários adicionados aos Menus Selecionados
  6. Clique em OK para fechar a mensagem de informação.
    Mensagem de informação confirmando que o formulário foi salvo
  7. Na parte inferior da página, feche a guia dinâmica Editar ManageEmployees para retornar ao formulário de dados.

Testando o Script Groovy

Nesta seção, você executa a regra no formulário ManageEmployees aberto para recuperar e salvar um endereço completo e, em seguida, revisar o log de jobs.

  1. Clique com o botão direito do mouse em Funcionário 1 e selecione Atualizar Endereço do Funcionário.
    Menu de contexto Funcionário 1 com Atualizar Endereço do Funcionário destacado
  2. No prompt Employee Address, digite Oracle, Redwood Shores e clique em Launch.
    Prompt Endereço do Funcionário com a Oracle, foi informado o Redwood Shores
  3. Clique em OK para fechar a mensagem de informação.
    Mensagem de informações confirmando a execução bem-sucedida da regra de endereço do funcionário

    Após a conclusão bem-sucedida, o endereço completo retornado pelo Google Maps é salvo como o endereço do Funcionário 1.

    Formulário ManageEmployees com o endereço formatado do funcionário salvo para o Funcionário 1
  4. Clique em Navegador (Navegador) e, em Aplicativo, selecione Jobs para abrir a Console de Jobs.
    Página Todos os Cargos mostrando a regra de endereço de funcionário concluída
  5. Clique em Adicionar ou Atualizar Endereço do Funcionário Groovy para exibir os detalhes do job.
    Detalhes do Job com os valores de prompt de tempo de execução e recolhidos Concluídos mostrados
  6. Em Status de Execução, expanda Concluído para exibir as mensagens de log impressas pelo script Groovy.
    Status Concluído Expandido mostrando a resposta HTTP 200, Google Places e o endereço formatado

Mais Recursos de Aprendizagem

Explore outros laboratórios em docs.oracle.com/learn ou acesse mais conteúdo de aprendizado gratuito no canal do Oracle Learning YouTube. Além disso, acesse education.oracle.com/learning-explorer para se tornar um Oracle Learning Explorer.

Para obter a documentação do produto, visite o Oracle Help Center.