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.
- Clique com o botão direito do mouse no link do HP4_Plan2_Variables.xml e salve o arquivo na unidade local.
- Clique em
(Navegador) e, em Criar e Gerenciar, selecione Regras para abrir o Calculation Manager.
- 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.

- Em Detalhes da Importação de Arquivos, procure e selecione
HP4_Plan2_Variables.xmlna sua unidade local.
- Em Detalhes do local, selecione os seguintes valores:
- Tipo de Aplicativo: EPM Cloud
- Aplicativo: HP4
- Cubo: Plan2
- Em Opções de Importação, selecione Substituir Objetos Existentes.

- Clique em Importar. Verifique os resultados da importação e clique em OK.

Observação:
A mensagem para cada objeto pode dizer "Inserted" ou "Updated". - 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.
- Deixe o Calculation Manager aberto e retorne à janela do navegador Planning.
- Clique em
(Navegador) e, em Tools, selecione Connections.
- Clique em Criar.
- Selecione Outro Provedor de Serviços Web.

- Informe os seguintes valores:
- Nome da Conexão:
Maps - URL:
https://places.googleapis.com/v1/places:searchText
- Nome da Conexão:
- Clique em Mostrar Opções Avançadas.

- 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.
- Clique em
(Adicionar) e defina outro cabeçalho usando os seguintes valores:- Tipo: Cabeçalho
- Seguro: Compensado
- Nome:
X-Goog-FieldMask - Valor:
places.formattedAddress

- Clique em Salvar e Fechar para salvar a conexão.

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.

- Retorne à janela do navegador Calculation Manager.
- Na guia Exibição de Sistema, expanda EPM Cloud, HP4 e Plan2. Clique com o mouse em Regras e selecione Novo.

- Para Nome, digite
Groovy Add or Update Employee Addresse clique em OK.
- No Editor de Regras, altere a opção Designer para Editar Script e defina o Tipo de Script como Script Groovy.

- Copiar este script e colá-lo no 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 as solicitações de tempo de execução (RTPs) usadas por essa regra na primeira linha.
Obtenha o objeto Memberpara o funcionário especificado pelo RTP do Funcionário.
Use o RTP EmployeeAddress como o endereço padrão quando um endereço formatado não for atribuído.
Use a Conexão de mapas para enviar uma solicitação HTTP POST. Defina o tipo de conteúdo como application/jsone informe o valor EmployeeAddress informado no campotextQueryJSON.
Registre o status HTTP e o corpo da resposta para solucionar problemas.
Faça parse da resposta JSON usando JsonPath. Converta explicitamente o array placesemListpara que a verificação de tipo estático possa resolverisEmpty(). Quando o status da resposta for bem-sucedido e a lista não estiver vazia, leiaplaces[0].formattedAddress, converta-a em um ID de célula de texto e atribua-a aaddress. Caso contrário, mantenha o valor RTP original.
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). - Na barra de ferramentas, clique em
(Salvar). Clique em OK para fechar a mensagem de informações.Observação:
Salvar o script exibe as variáveis na guia Variáveis.

- 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.
- Clique em
(Salvar) novamente. Clique em OK para fechar a mensagem de informações. - Clique em
(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

- Funcionário:
- 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. - Clique em OK quando solicitado e feche o Calculation Manager.

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.
- No Planning, clique em
(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. - Clique em
(Criar Menu) para criar um menu de ação.
- Para Nome do Menu, digite
Manage Employeese clique em OK.
- Selecione o menu de ação Gerenciar Funcionários e clique em
(Menu Editar).
- Em
(Adicionar Filho). Insira ou selecione os seguintes valores:Campo de opção Valor Item do Menu Update Employee AddressLabel Update Employee AddressTipo 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 
- Clique em Salvar. Na mensagem de confirmação, clique em OK.

- Clique em Salvar para salvar o menu de ação. Na mensagem de confirmação, clique em OK.


- 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.
- Clique em
(Navegador) e selecione Dados. - Clique em ManageEmployees para abrir o formulário.

- 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.

- Selecione a guia Outras Opções.

- Adicione Gerenciar Funcionários à lista Menus Selecionados e clique em Salvar.

- Clique em OK para fechar a mensagem de informação.

- 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.
- Clique com o botão direito do mouse em Funcionário 1 e selecione Atualizar Endereço do Funcionário.

- No prompt Employee Address, digite
Oracle, Redwood Shorese clique em Launch.
- Clique em OK para fechar a mensagem de informação.

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

- Clique em
(Navegador) e, em Aplicativo, selecione Jobs para abrir a Console de Jobs.
- Clique em Adicionar ou Atualizar Endereço do Funcionário Groovy para exibir os detalhes do job.

- Em Status de Execução, expanda Concluído para exibir as mensagens de log impressas pelo script Groovy.

Links Relacionados
- Tutoriais do Planning — Selecione Implementando o Groovy na lista de áreas de interesse para explorar tutoriais adicionais do Groovy.
- Referência de API Java para Regras Groovy — Explore as APIs Groovy disponíveis para desenvolver regras e modelos Groovy.
- APIs REST para o Oracle Fusion Cloud EPM — Explore as APIs REST disponíveis para gerenciar e automatizar tarefas do Cloud EPM.
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.
Chamando uma API REST Externa usando o Groovy
G43159-02
Novembro de 2026