Introduzione
Questa esercitazione descrive come chiamare un'API REST esterna da uno script Groovy in Oracle EPM Cloud Planning. Vengono fornite istruzioni anche per creare un menu azioni attivabili con un pulsante destro del mouse con una voce di menu per richiamare lo script e per associare tale menu a un form di dati.
Completare le sezioni in ordine.
Presupposto
Il modello a oggetti Groovy EPM offre un modo per chiamare API REST interne (cross-POD o altri Oracle Cloud Services) ed esterne. In questo esempio, è possibile creare ed eseguire una regola Groovy per chiamare un'API REST Google Places esterna per aggiungere o aggiornare le informazioni sull'indirizzo dei dipendenti nel modulo ManageEmployees.
Prerequisiti
Le esercitazioni pratiche su Cloud EPM potrebbero richiedere l'importazione di uno snapshot in un'istanza di Cloud EPM Enterprise Service. Impossibile importare uno snapshot su un'applicazione o un processo aziendale esistente. Prima di importare lo snapshot, utilizzare un'istanza separata di Cloud EPM Enterprise Service o rimuovere l'applicazione o il processo aziendale esistente dall'istanza che si prevede di utilizzare. L'importazione dello snapshot non sostituisce o ripristina automaticamente il contenuto esistente.
Prima di iniziare questo tutorial, è necessario:
- Consente all'amministratore dei servizi di accedere a un'istanza di Cloud EPM Enterprise Service.
- Caricare e importare questo snapshot nell'istanza di Planning. Se questa istantanea è stata caricata in precedenza per un'altra esercitazione Groovy, è possibile continuare a utilizzare la stessa istantanea.
- Prima di poter iniziare a utilizzare le API di Google Maps Platform che includono l'API Places (New) utilizzata in questa esercitazione, è necessario registrarsi e creare un account di fatturazione per acquisire una chiave API. Per ulteriori informazioni, vedere Introduzione a Google Maps Platform.
Nota
Se si verificano errori di migrazione durante l'importazione dello snapshot, eseguire di nuovo la migrazione escludendo il componente HSS-Shared Services e gli artifact delle preferenze di sicurezza e utente nel componente Core. Per ulteriori informazioni sul caricamento e l'importazione degli snapshot, fare riferimento alla documentazione Amministrazione della migrazione per Oracle Enterprise Performance Management Cloud.Suggerimento
Gli script necessari per questa esercitazione sono collegati come file di testo all'interno di ciascuna sezione.Caricamento delle variabili di calcolo pianificazione
In questa sezione è possibile caricare variabili di calcolo da un file XML da utilizzare nello script Groovy.
- Fare clic con il pulsante destro del mouse sul collegamento HP4_Plan2_Variables.xml e salvare il file nell'unità locale.
- Fare clic su
(Navigator), quindi selezionare Regole in Crea e gestisci per aprire Gestione calcoli.
- In Vista sistema espandere EPM Cloud, quindi HP4. Fare clic con il pulsante destro del mouse su Plan2 e selezionare Importa.

- In Dettagli importazione file, individuare e selezionare
HP4_Plan2_Variables.xmldall'unità locale.
- In Dettagli ubicazione selezionare i valori riportati di seguito.
- Tipo di applicazione: EPM Cloud
- Applicazione: HP4
- Cubo: Plan2
- In Opzioni di importazione selezionare Sostituisci oggetti esistenti.

- Fare clic su Importa. Esaminare i risultati dell'importazione, quindi fare clic su OK.

Nota
Il messaggio per ciascun oggetto può indicare "Inserito" o "Aggiornato". - Fare clic su Annulla per chiudere la finestra di dialogo Importa.
Creazione di una connessione denominata in Planning
In questa sezione è possibile creare una connessione Maps per l'API Google Places.
- Lasciare aperto Gestione calcoli e tornare alla finestra del browser Pianificazione.
- Fare clic su
(Navigator), quindi selezionare Connessioni in Strumenti.
- Fare clic su Crea.
- Selezionare Altro provider di servizi Web.

- Immettere i valori riportati di seguito.
- Nome connessione:
Maps - URL:
https://places.googleapis.com/v1/places:searchText
- Nome connessione:
- Fare clic su Mostra opzioni avanzate.

- Definire l'intestazione della chiave API utilizzando i seguenti valori:
- Tipo: intestazione
- Sicuro: selezionato
- Nome:
X-Goog-Api-Key - Valore: La tua chiave API di Google Maps
Mantieni la tua API key privata.
- Fare clic su
(Aggiungi) e definire un'altra intestazione utilizzando i seguenti valori:- Tipo: intestazione
- Sicuro: cancellato
- Nome:
X-Goog-FieldMask - Valore:
places.formattedAddress

- Per salvare la connessione, fare clic su Salva e chiudi.

Creazione di uno script Groovy
In questa sezione è possibile creare una regola Groovy per aggiornare l'indirizzo di un dipendente utilizzando il form ManageEmployees predefinito.

- Tornare alla finestra del browser Gestione calcoli.
- Nella scheda Vista sistema, espandere EPM Cloud, HP4, quindi Plan2. fare clic con il pulsante destro del mouse su Regole, quindi selezionare Nuovo.

- Per Nome, immettere
Groovy Add or Update Employee Address, quindi fare clic su OK.
- Nell'Editor regole, modificare l'opzione Designer in Modifica script e impostare il tipo di script su Script Groovy.

- Copiare lo script e incollarlo nell'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;"""
Definire tutti i prompt runtime (RTP) utilizzati da questa regola nella prima riga.
Recupera l'oggetto Memberper il dipendente specificato dall'RTP dipendente.
Utilizzare l'RTP EmployeeAddress come indirizzo predefinito quando non viene assegnato un indirizzo formattato.
Utilizzare la connessione con le mappe per inviare una richiesta POST HTTP. Impostare il tipo di contenuto su application/jsone passare il valore EmployeeAddress immesso nel campotextQueryJSON.
Registrare lo stato HTTP e il corpo della risposta per la risoluzione dei problemi.
Analizza la risposta JSON utilizzando JsonPath. Includere esplicitamente l'array placesinListin modo che il controllo del tipo statico possa risolvereisEmpty(). Quando lo stato della risposta è riuscito e l'elenco non è vuoto, leggereplaces[0].formattedAddress, convertirlo in un ID cella di testo e assegnarlo aaddress. In caso contrario, mantenere il valore RTP originale.
Generare lo script di calcolo per salvare l'indirizzo del dipendente all'intersezione specificata dagli RTP.Nota
La connessione Maps è un collegamento di comunicazione tra lo script Groovy e la risorsa API Google Places (New). - Nella barra degli strumenti, fare clic su
(Salva). Per chiudere il messaggio informativo, fare clic su OK.Nota
Se si salva lo script, le variabili vengono visualizzate nella scheda Variabili.

- Nella scheda Variabili selezionare Nascosto per Dipendente, Entità, Periodo, Scenario, Versione e Anno, in modo che gli utenti immettano un valore solo per EmployeeAddress.
Nota
Quando gli utenti eseguono la regola dal form, queste variabili nascoste ricevono valori dal contesto del form.
- Fare nuovamente clic su
(Salva). Per chiudere il messaggio informativo, fare clic su OK. - Fare clic su
(Convalida e distribuisci). Immettere i seguenti valori RTP per la convalida:- Dipendente:
"Full Time Employees" - Entità:
"No Entity" - Periodo:
Jan - Scenario:
Current - Versione:
"BU Version_1" - Anno:
FY26

- Dipendente:
- Selezionare Applica valori alla regola per salvare questi valori come valori predefiniti per la convalida, quindi fare clic su OK.
Nota
La convalida non esegue la regola, ma sono necessari membri validi affinché la convalida riesca. - Quando richiesto, fare clic su OK, quindi chiudere Gestione calcoli.

Creazione di menu azione di pianificazione per l'esecuzione di script Groovy
In questa sezione è possibile creare un menu azioni Gestisci dipendenti con una voce di menu che esegue la regola Groovy.
- In Planning fare clic su
(Navigator), quindi selezionare Menu azioni in Crea e gestisci.Nota
Se sono state completate altre esercitazioni di Groovy, è possibile che il menu azioni Gestisci dipendenti esista già. In tal caso, procedere al punto 4. - Fare clic su
(Menu Crea) per creare un menu azioni.
- Per Nome menu, immettere
Manage Employees, quindi fare clic su OK.
- Selezionare il menu azioni Gestisci dipendenti, quindi fare clic su
(menu Modifica).
- Fare clic su
(Aggiungi figlio). Immettere o selezionare i valori seguenti:Campo opzione Valore Voce di menu Update Employee AddressEtichetta Update Employee AddressType Regola business Parametri obbligatori Dipendente Cubo Plan2 Regola business Groovy Aggiungi o aggiorna indirizzo dipendente 
- Fare clic su Salva. Nel messaggio di conferma, fare clic su OK.

- Fare clic su Salva per salvare il menu delle azioni. Nel messaggio di conferma, fare clic su OK.


- Fare clic su Annulla per chiudere l'editor del menu Azione.
Associazione dei menu delle azioni di pianificazione ai form
In questa sezione è possibile associare il menu azioni Gestisci dipendenti al form ManageEmployees.
- Fare clic su
(Navigator), quindi selezionare Dati. - Fare clic su ManageEmployees per aprire il form.

- Fare clic su Azioni, quindi selezionare Modifica per modificare il form.
Viene visualizzata una nuova scheda dinamica con l'editor di moduli.

- Selezionare la scheda Altre opzioni.

- Aggiungere Gestisci dipendenti all'elenco Menu selezionati, quindi fare clic su Salva.

- Fare clic su OK per chiudere il messaggio informativo.

- Nella parte inferiore della pagina, chiudere la scheda dinamica Modifica ManageEmployees per tornare al form dati.
Test dello script Groovy
In questa sezione, eseguire la regola dal form ManageEmployees aperto per recuperare e salvare un indirizzo completo, quindi rivedere il log dei job.
- Fare clic con il pulsante destro del mouse su Dipendente 1 e selezionare Aggiorna indirizzo dipendente.

- Nel prompt Indirizzo dipendente immettere
Oracle, Redwood Shores, quindi fare clic su Avvia.
- Fare clic su OK per chiudere il messaggio informativo.

Al completamento, l'indirizzo completo restituito da Google Maps viene salvato come indirizzo per il dipendente 1.

- Fare clic su
(Navigator), quindi in Applicazione selezionare Job per aprire la console dei job.
- Fare clic su Aggiungi o aggiorna indirizzo dipendente Groovy per visualizzare i dettagli della mansione.

- In Stato esecuzione, espandere Completato per visualizzare i messaggi di log stampati dallo script Groovy.

Collegamenti correlati
- Esercitazioni sulla pianificazione: selezionare Implementazione di Groovy dall'elenco delle aree di interesse per esplorare ulteriori esercitazioni su Groovy.
- Java API Reference for Groovy Rules: esplora le API di Groovy disponibili per lo sviluppo di regole e modelli Groovy.
- API REST per Oracle Fusion Cloud EPM: consente di esplorare le API REST disponibili per la gestione e l'automazione dei task di Cloud EPM.
Altre risorse di apprendimento
Esplora altri laboratori su docs.oracle.com/learn o accedi a più contenuti di formazione gratuiti sul canale YouTube di Oracle Learning. Inoltre, visitare education.oracle.com/learning-explorer per diventare Oracle Learning Explorer.
Per la documentazione del prodotto, visitare Oracle Help Center.
Chiamata di un'API REST esterna mediante Groovy
G43154-02
Novembre 2026