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.

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 sua instância do Cloud EPM Enterprise Service. Para poder importar um instantâneo de tutorial, você deve solicitar outra instância do Cloud EPM Enterprise Service ou remover seu aplicativo e processo de negócios atuais. O instantâneo do tutorial não será importado sobre seu aplicativo ou processo de negócios existente, nem substituirá ou restaurará automaticamente o aplicativo ou processo de negócios com o qual você está trabalhando no momento.

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 instantâneo para sua instância do Planning. Se você já tiver feito upload do instantâneo para outro tutorial do Groovy, poderá continuar usando o mesmo instantâneo.
  • Antes de começar a usar as APIs do Google Maps Platform que incluem a API REST Places 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 do Planning

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. No canto superior esquerdo, clique no Navegador Ícone Navegador e navegue até Regras (em Criar e Gerenciar) para abrir o Calculation Manager. Na Exibição de Sistema, expanda EPM Cloud > HP4. Clique com o botão direito em Plan2 e selecione Importar.
  3. Em Detalhes da Importação de Arquivos, procure para selecionar HP4_Plan2_Variables.xml da unidade local.
  4. Em Detalhes do local, faça as seguintes seleções:
    • Tipo de Aplicativo: EPM Cloud
    • Aplicação: HP4
    • Cubo: Plan2
  5. Em Opções de Importação, selecione Substituir Objetos Existentes.
    6. Importar Variáveis
  6. Clique em Importar. Revise os resultados da importação e clique em OK.
    Resultado da Importação
  7. Clique em Cancelar para fechar a caixa de diálogo Importar.

Criando uma conexão nomeada no Planning

Nesta seção, você edita uma conexão existente para incluir a chave da API REST Places.

  1. Navegue até Conexões (em Ferramentas) e selecione a conexão Locais.
    2. Conexões
  2. Edite a conexão informando a chave de API no parâmetro de chave. Salve e feche a conexão.
    3. Parâmetro da Chave da API

Criando um script Groovy

Nesta seção, você implementa um script Groovy para atualizar um endereço de funcionário. Trabalharemos com o formulário ManageEmployees predefinido.

Gerenciar Funcionários
  1. No Calculation Manager, crie uma regra chamada Adicionar ou Atualizar Endereço do Funcionário do Groovy no cubo Plan2.
    2. Nova regra
  2. No Editor de Regras, altere a opção Designer para Editar Script e defina o Tipo de Script como Script Groovy.
    3. Opções do Editor de Regras
  3. Copiar este script e colá-lo no 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 todos os prompts de tempo de execução (RTPs) usados por esta regra na primeira linha.

    Obtenha o objeto Membro para employee especificado pelo RTP do Funcionário.

    Atribua o texto informado no RTP EmployeeAddress como o valor padrão para address.

    Obtenha a conexão Places para executar a solicitação HTTP GET neste recurso e informe o texto informado no RTP EmployeeAddress como o valor do parâmetro de consulta input.

    Observação:

    O objeto de conexão Places é um link de comunicação entre o script Groovy e o recurso da API REST do Google Places.

    Registre a resposta da API REST do Google Maps para fins de depuração.

    Faça parse da resposta JSON recebida da API usando a biblioteca JsonPath. Se o status == OK, leia o campo formatted_address do primeiro objeto do candidato no array retornado, obtenha o id da célula de texto para formatted_address e atribua-o ao endereço.

    Gere o script de cálculo para salvar este endereço de funcionário.

  4. Na barra de ferramentas, clique em Salvar (Salvar) para salvar o script.

    5. Observação:

    Salvar o script exibe as variáveis na guia Variáveis.
  5. Você deseja que os usuários informem valores somente para EmployeeAddress. Na guia Variáveis, selecione Is Hidden para Employee, Entity, Period, Scenario, Version e Year.
    6. Variáveis Ocultas

    Observação:

    Quando os usuários executam o script a partir do formulário, essas variáveis ocultas recebem valores do contexto do formulário.
  6. Salve o script novamente.
  7. Clique em Validar e Implantar (Validar e Implantar). Informe valores de RTP para fins de validação:
    • Funcionário: Full Time Employees
    • Entidade: No Entity
    • Período: Jan
    • Cenário: Current
    • Versão: BU_Version_1
    • Ano: FY16
    Opções do Editor de Regras
  8. Marque Aplicar valores à regra para salvar esses valores como padrão para fins de validação e clique em OK.

    9. Observação:

    Durante esta etapa, a regra não é executada; no entanto, você deve informar membros válidos para que o processo de validação seja bem-sucedido.
  9. Clique em OK quando solicitado e feche o Calculation Manager.

Criando menus de ação do Planning para executar scripts Groovy

Nesta seção, você cria um menu de ação chamado Gerenciar Funcionários, com um item de menu de ação de clique com o botão direito que executa o script Groovy.

  1. No canto superior esquerdo, clique no Navegador Ícone Navegador e navegue até Menus de Ação (localizados em Criar e Gerenciar) e crie um menu de ação chamado Gerenciar Funcionários.
    2. Menu Ação Criar Gerenciar Funcionários
  2. Edite o menu de ação Gerenciar Funcionários e adicione um item de menu filho chamado Atualizar Endereço do Funcionário. Insira ou selecione as seguintes opções para definir o item de menu:
    3. Campo de opção Valor a ser Informado ou Selecionar
    Item do Menu Atualizar Endereço do Funcionário
    Label Atualizar Endereço do Funcionário
    Tipo Regra de Negócios
    Parâmetros Obrigatórios Funcionário
    Cubo Plan2
    Regra de Negócios Groovy - Adicionar ou Atualizar Endereço do Funcionário

    Atualizar Item de Menu de Endereço do Funcionário

  3. Clique em Salvar e em OK para salvar o item de menu. Por fim, clique em Salvar para salvar o menu de ação.
    4. Menu Ação Gerenciar Funcionários Concluídos

Associando menus de ação do Planning a formulários

Nesta etapa, você associa o menu de ação ao formulário ManageEmployees e testa seu script.

  1. Navegue até Formulários (localizados em Criar e Gerenciar) e edite o formulário ManageEmployees.
    2. Editar Form Gerenciar Funcionários
  2. Na guia Outras Opções, adicione o menu de contexto Gerenciar Funcionários à lista Menus Selecionados.
    3. Adicionar o menu de contexto Gerenciar funcionários
  3. Clique em Concluir para salvar as alterações no formulário.
  4. Feche o gerenciador de formulários e retorne à Home page.

Testando o script Groovy

Nesta etapa, você testa o script. O procedimento de teste inclui a inserção de um local válido para o RTP EmployeeAddress para recuperar o endereço completo do local.

  1. No canto superior esquerdo, clique em Ícone Navegador Navigator e clique em Dados para exibir a lista de formulários de entrada de dados e, em seguida, clique em ManageEmployees para abrir o formulário Gerenciar Funcionários.
    2. Lista de Formulários de Entrada de Dados
  2. Para testar o script Groovy, clique com o botão direito do mouse em Funcionário 1 e selecione o item de menu Atualizar Endereço do Funcionário.
    3. Caixa de Diálogo Adicionar Funcionário com E-mail e Nome Inválidos
  3. No prompt Employee Address, digite Oracle, San Jose e clique em Launch.
    4. Mensagem de Erro de Nome de Funcionário Inválido

    No lançamento bem-sucedido, você verá o endereço completo da Oracle, San Jose, salvo como o endereço completo do Funcionário 1.

    Mensagem de erro de e-mail de funcionário inválida
  4. Salve e feche o form. Navegue até Jobs (em Aplicativo) para abrir a Console de Jobs.
    5. Console de Jobs
  5. Clique em Adicionar e Atualizar Endereço do Funcionário Groovy para exibir os detalhes do job. Clique no status Concluído para ver as mensagens de log impressas pelo script Groovy.
    6. Mensagens de Log do Script Groovy

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 a Oracle University para ver os recursos de treinamento disponíveis.

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