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.

  1. Fare clic con il pulsante destro del mouse sul collegamento HP4_Plan2_Variables.xml e salvare il file nell'unità locale.
  2. Fare clic su Navigator (Navigator), quindi selezionare Regole in Crea e gestisci per aprire Gestione calcoli.
    Navigator con regole evidenziate in Crea e gestisci
  3. In Vista sistema espandere EPM Cloud, quindi HP4. Fare clic con il pulsante destro del mouse su Plan2 e selezionare Importa.
    Gerarchia vista sistema espansa con importazione selezionata per Plan2
  4. In Dettagli importazione file, individuare e selezionare HP4_Plan2_Variables.xml dall'unità locale.
    Finestra di dialogo Importa con il file delle variabili di calcolo selezionato
  5. In Dettagli ubicazione selezionare i valori riportati di seguito.
    • Tipo di applicazione: EPM Cloud
    • Applicazione: HP4
    • Cubo: Plan2
  6. In Opzioni di importazione selezionare Sostituisci oggetti esistenti.
    Finestra di dialogo Importa con EPM Cloud, HP4, Plan2 e Sostituisci oggetti esistenti selezionata
  7. Fare clic su Importa. Esaminare i risultati dell'importazione, quindi fare clic su OK.
    Risultati importazione variabili calcolo

    Nota

    Il messaggio per ciascun oggetto può indicare "Inserito" o "Aggiornato".
  8. 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.

  1. Lasciare aperto Gestione calcoli e tornare alla finestra del browser Pianificazione.
  2. Fare clic su Navigator (Navigator), quindi selezionare Connessioni in Strumenti.
    Pagina Gestisci connessioni prima di creare la connessione Maps
  3. Fare clic su Crea.
  4. Selezionare Altro provider di servizi Web.
    Altro provider di servizi Web evidenziato nella pagina di selezione del provider
  5. Immettere i valori riportati di seguito.
    • Nome connessione: Maps
    • URL: https://places.googleapis.com/v1/places:searchText
  6. Fare clic su Mostra opzioni avanzate.
    Mappa i dettagli di connessione con le opzioni avanzate visualizzate
  7. 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.

  8. Fare clic su Aggiungi (Aggiungi) e definire un'altra intestazione utilizzando i seguenti valori:
    • Tipo: intestazione
    • Sicuro: cancellato
    • Nome: X-Goog-FieldMask
    • Valore: places.formattedAddress
    Associa la connessione con entrambe le intestazioni configurate e la chiave API mascherata
  9. Per salvare la connessione, fare clic su Salva e chiudi.
    Pagina Gestisci connessioni con la connessione Mappe salvata

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.

Modulo ManageEmployees per la gestione delle informazioni sui dipendenti
  1. Tornare alla finestra del browser Gestione calcoli.
  2. Nella scheda Vista sistema, espandere EPM Cloud, HP4, quindi Plan2. fare clic con il pulsante destro del mouse su Regole, quindi selezionare Nuovo.
    Visualizzazione sistema espansa con nuova selezionata per la cartella Regole Plan2
  3. Per Nome, immettere Groovy Add or Update Employee Address, quindi fare clic su OK.
    Finestra di dialogo Nuova regola con nome regola indirizzo dipendente
  4. Nell'Editor regole, modificare l'opzione Designer in Modifica script e impostare il tipo di script su Script Groovy.
    Editor regole con script di modifica e script Groovy selezionato
  5. Copiare lo script e incollarlo nell'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 codice 1 Definire tutti i prompt runtime (RTP) utilizzati da questa regola nella prima riga.

    Nota codice 2 Recupera l'oggetto Member per il dipendente specificato dall'RTP dipendente.

    Nota di codice 3 Utilizzare l'RTP EmployeeAddress come indirizzo predefinito quando non viene assegnato un indirizzo formattato.

    Nota codice 4 Utilizzare la connessione con le mappe per inviare una richiesta POST HTTP. Impostare il tipo di contenuto su application/json e passare il valore EmployeeAddress immesso nel campo textQuery JSON.

    Nota di codice 5 Registrare lo stato HTTP e il corpo della risposta per la risoluzione dei problemi.

    Nota codice 6 Analizza la risposta JSON utilizzando JsonPath. Includere esplicitamente l'array places in List in modo che il controllo del tipo statico possa risolvere isEmpty(). Quando lo stato della risposta è riuscito e l'elenco non è vuoto, leggere places[0].formattedAddress, convertirlo in un ID cella di testo e assegnarlo a address. In caso contrario, mantenere il valore RTP originale.

    Nota di codice 7 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).
  6. Nella barra degli strumenti, fare clic su Salva (Salva). Per chiudere il messaggio informativo, fare clic su OK.

    Nota

    Se si salva lo script, le variabili vengono visualizzate nella scheda Variabili.
    Messaggio informativo che conferma il salvataggio della regola Groovy
    Regola salvata con prompt runtime visualizzati nella scheda Variabili
  7. 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.
    Scheda Variabili con tutti i prompt runtime ad eccezione di EmployeeAddress nascosto
  8. Fare nuovamente clic su Salva (Salva). Per chiudere il messaggio informativo, fare clic su OK.
  9. Fare clic su Convalida e distribuisci (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
    Finestra di dialogo Immettere i valori RTP con i membri di convalida e FY26
  10. 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.
  11. Quando richiesto, fare clic su OK, quindi chiudere Gestione calcoli.
    Messaggio di conferma della corretta distribuzione della regola

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.

  1. In Planning fare clic su Navigator (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.
  2. Fare clic su Crea menu (Menu Crea) per creare un menu azioni.
    Finestra di dialogo Crea menu prima di immettere il nome del menu
  3. Per Nome menu, immettere Manage Employees, quindi fare clic su OK.
    Finestra di dialogo Crea menu con Gestisci dipendenti inserita
  4. Selezionare il menu azioni Gestisci dipendenti, quindi fare clic su Menu Modifica (menu Modifica).
    Menu azioni Gestisci dipendenti aperto per la modifica
  5. Fare clic su Aggiungi figlio (Aggiungi figlio). Immettere o selezionare i valori seguenti:
    Campo opzioneValore
    Voce di menuUpdate Employee Address
    EtichettaUpdate Employee Address
    TypeRegola business
    Parametri obbligatoriDipendente
    CuboPlan2
    Regola businessGroovy Aggiungi o aggiorna indirizzo dipendente
    Aggiungi impostazioni figlio per la regola business Aggiorna indirizzo dipendente
  6. Fare clic su Salva. Nel messaggio di conferma, fare clic su OK.
    Messaggio informativo che conferma che la voce di menu è stata salvata
  7. Fare clic su Salva per salvare il menu delle azioni. Nel messaggio di conferma, fare clic su OK.
    Messaggio informativo che conferma che il menu azioni è stato salvato
    Menu azione Gestisci dipendenti salvato contenente Aggiorna indirizzo dipendente
  8. 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.

  1. Fare clic su Navigator (Navigator), quindi selezionare Dati.
  2. Fare clic su ManageEmployees per aprire il form.
    Modulo ManageEmployees prima di associare il menu azioni
  3. Fare clic su Azioni, quindi selezionare Modifica per modificare il form.

    Viene visualizzata una nuova scheda dinamica con l'editor di moduli.

    Menu Azioni con Modifica evidenziata
  4. Selezionare la scheda Altre opzioni.
    Scheda Altre opzioni nell'editor di moduli
  5. Aggiungere Gestisci dipendenti all'elenco Menu selezionati, quindi fare clic su Salva.
    Gestisci dipendenti aggiunti ai menu selezionati
  6. Fare clic su OK per chiudere il messaggio informativo.
    Messaggio informativo che conferma il salvataggio del modulo
  7. 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.

  1. Fare clic con il pulsante destro del mouse su Dipendente 1 e selezionare Aggiorna indirizzo dipendente.
    Menu di scelta rapida Dipendente 1 con Aggiornamento indirizzo dipendente evidenziato
  2. Nel prompt Indirizzo dipendente immettere Oracle, Redwood Shores, quindi fare clic su Avvia.
    Prompt indirizzo dipendente con Oracle, Redwood Shores inserito
  3. Fare clic su OK per chiudere il messaggio informativo.
    Messaggio informativo che conferma l'esecuzione riuscita della regola indirizzo dipendente

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

    Modulo ManageEmployees con l'indirizzo del dipendente formattato salvato per il dipendente 1
  4. Fare clic su Navigator (Navigator), quindi in Applicazione selezionare Job per aprire la console dei job.
    Pagina Tutti i job con la regola indirizzo dipendente completata
  5. Fare clic su Aggiungi o aggiorna indirizzo dipendente Groovy per visualizzare i dettagli della mansione.
    Dettagli job con valori compressi completati e prompt runtime visualizzati
  6. In Stato esecuzione, espandere Completato per visualizzare i messaggi di log stampati dallo script Groovy.
    Stato Completato Espanso che mostra HTTP 200, risposta Google Places e indirizzo formattato

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.