Einführung
In diesem Tutorial erfahren Sie, wie Sie eine externe REST-API aus einem Groovy-Skript in Oracle EPM Cloud Planning aufrufen. Außerdem erfahren Sie, wie ein Kontextmenü mit einer Menüoption zum Aufrufen des Skripts erstellt und das Aktionsmenü einem Eingabeformular zugeordnet wird.
Füllen Sie die Abschnitte in der Reihenfolge aus.
Hintergrund
Das Groovy EPM-Objektmodell bietet eine Möglichkeit, interne (Cross-POD oder andere Oracle Cloud Services) und externe REST-APIs aufzurufen. In diesem Beispiel erstellen Sie eine Groovy-Regel zum Aufrufen einer externen REST-API für Google Places, um Mitarbeiteradressinformationen im Formular ManageEmployees hinzuzufügen oder zu aktualisieren.
Voraussetzungen
Für praktische Tutorials zu Cloud EPM müssen Sie möglicherweise einen Snapshot in eine Cloud EPM Enterprise Service-Instanz importieren. Ein Snapshot kann nicht über eine vorhandene Anwendung oder einen vorhandenen Geschäftsprozess importiert werden. Verwenden Sie vor dem Import des Snapshots eine separate Cloud EPM Enterprise Service-Instanz, oder entfernen Sie die vorhandene Anwendung oder den vorhandenen Geschäftsprozess aus der Instanz, die Sie verwenden möchten. Beim Importieren des Snapshots wird der vorhandene Inhalt nicht automatisch ersetzt oder wiederhergestellt.
Bevor Sie mit diesem Tutorial beginnen, müssen Sie:
- Haben Sie Serviceadministratorzugriff auf eine Cloud EPM Enterprise Service-Instanz.
- Laden Sie diesen Snapshot hoch, und importieren Sie ihn in Ihre Planning-Instanz. Wenn Sie diesen Snapshot zuvor für ein anderes Groovy-Tutorial hochgeladen haben, können Sie mit dem gleichen Snapshot fortfahren.
- Bevor Sie mit der Verwendung der Google Maps Platform-APIs beginnen können, die die Places API (Neu) enthalten, die in diesem Tutorial verwendet wird, müssen Sie sich registrieren und ein Abrechnungskonto erstellen, um einen API-Schlüssel zu erwerben. Weitere Informationen finden Sie unter Erste Schritte mit Google Maps Platform.
Hinweis:
Wenn beim Importieren des Snapshots Migrationsfehler auftreten, führen Sie die Migration erneut aus, ausgenommen die HSS-Shared Services-Komponente sowie die Artefakte der Sicherheits- und Benutzervoreinstellungen in der Core-Komponente. Weitere Informationen zum Hochladen und Importieren von Snapshots finden Sie in der Dokumentation Migration für Oracle Enterprise Performance Management Cloud verwalten.Tipp:
Die Skripte, die Sie für dieses Tutorial benötigen, sind in jedem Abschnitt als Textdateien verknüpft.Planungsberechnungsvariablen laden
In diesem Abschnitt laden Sie Berechnungsvariablen aus einer XML-Datei zur Verwendung im Groovy-Skript hoch.
- Klicken Sie mit der rechten Maustaste auf den Link für HP4_Plan2_Variables.xml, und speichern Sie die Datei auf dem lokalen Laufwerk.
- Klicken Sie auf
(Navigator), und wählen Sie unter "Erstellen und verwalten" die Option Regeln aus, um Calculation Manager zu öffnen.
- Blenden Sie in der Systemansicht EPM Cloud, HP4 ein. Klicken Sie mit der rechten Maustaste auf Plan2, und wählen Sie Importieren aus.

- Navigieren Sie unter "Dateiimportdetails" zu
HP4_Plan2_Variables.xml, und wählen Sie es auf Ihrem lokalen Laufwerk aus.
- Wählen Sie unter "Standortdetails" die folgenden Werte aus:
- Anwendungstyp: EPM Cloud
- Anwendung: HP4
- Cube: Plan2
- Wählen Sie unter "Importoptionen" die Option Vorhandene Objekte überschreiben aus.

- Klicken Sie auf Importieren. Prüfen Sie die Importergebnisse, und klicken Sie auf OK.

Hinweis:
Die Nachricht für jedes Objekt kann "Eingefügt" oder "Aktualisiert" lauten. - Klicken Sie auf Abbrechen, um das Dialogfeld "Importieren" zu schließen.
Benannte Verbindungen in Planning erstellen
In diesem Abschnitt erstellen Sie eine Maps-Verbindung für die Google Places API.
- Lassen Sie Calculation Manager geöffnet, und kehren Sie zum Planning-Browserfenster zurück.
- Klicken Sie auf
(Navigator), und wählen Sie unter "Tools" die Option Verbindungen aus.
- Klicken Sie auf Erstellen.
- Wählen Sie Anderer Webserviceprovider aus.

- Geben Sie folgende Werte ein:
- Verbindungsname:
Maps - URL:
https://places.googleapis.com/v1/places:searchText
- Verbindungsname:
- Klicken Sie auf Erweiterte Einstellungen anzeigen.

- Definieren Sie den API-Schlüsselheader mit den folgenden Werten:
- Typ: Header
- Sicher: Ausgewählt
- Name:
X-Goog-Api-Key - Wert: Ihr Google Maps-API-Schlüssel
Schützen Sie Ihren API-Schlüssel.
- Klicken Sie auf
(Hinzufügen), und definieren Sie einen anderen Header mit den folgenden Werten:- Typ: Header
- Sicher: Gelöscht
- Name:
X-Goog-FieldMask - Wert:
places.formattedAddress

- Klicken Sie auf Speichern und schließen, um die Verbindung zu speichern.

Groovy-Skripte erstellen
In diesem Abschnitt erstellen Sie eine Groovy-Regel, um die Adresse eines Mitarbeiters mit dem vordefinierten Formular ManageEmployees zu aktualisieren.

- Kehren Sie zum Browserfenster von Calculation Manager zurück.
- Blenden Sie auf der Registerkarte "Systemansicht" EPM Cloud, HP4, Plan2 ein. Klicken Sie mit die rechte Maustaste auf Regeln, und wählen Sie Neu aus.

- Geben Sie als Namen
Groovy Add or Update Employee Addressein, und klicken Sie auf OK.
- Ändern Sie im Regeleditor die Designeroption in Skript bearbeiten, und setzen Sie den Skripttyp auf Groovy-Skript.

- Kopieren Sie dieses Skript und fügen Sie es in den Editor ein:
/*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;"""
Definieren Sie alle Runtime Prompts (RTPs), die von dieser Regel in der ersten Zeile verwendet werden.
Rufen Sie das Objekt Memberfür den vom Mitarbeiter-RTP angegebenen Mitarbeiter ab.
Verwenden Sie den RTP EmployeeAddress als Standardadresse, wenn keine formatierte Adresse zugewiesen ist.
Verwenden Sie die Maps-Verbindung, um eine HTTP POST-Anforderung zu senden. Setzen Sie den Inhaltstyp auf application/json, und übergeben Sie den eingegebenen Wert EmployeeAddress im JSON-FeldtextQuery.
Protokollieren Sie den HTTP-Status und den Antwortbody zur Fehlerbehebung.
Parsen Sie die JSON-Antwort mit JsonPath. Setzen Sie das Array placesexplizit inList, damit die statische TypprüfungisEmpty()auflösen kann. Wenn der Antwortstatus erfolgreich ist und die Liste nicht leer ist, lesen Sieplaces[0].formattedAddress, konvertieren Sie ihn in eine Textzellen-ID, und weisen Sie ihnaddresszu. Andernfalls behalten Sie den ursprünglichen RTP-Wert bei.
Generieren Sie das Berechnungsskript, um die Mitarbeiteradresse an der von den RTPs angegebenen Schnittmenge zu speichern.Hinweis:
Die Maps-Verbindung ist eine Kommunikationsverbindung zwischen dem Groovy Script und der Google Places API (New) Ressource. - Klicken Sie in der Symbolleiste auf
(Speichern). Klicken Sie auf OK, um die Informationsmeldung zu schließen.Hinweis:
Wenn Sie das Skript speichern, werden die Variablen in der Registerkarte "Variablen" angezeigt.

- Wählen Sie auf der Registerkarte "Variablen" die Option Ausgeblendet für Mitarbeiter, Entity, Periode, Szenario, Version und Jahr aus, sodass Benutzer nur für EmployeeAddress einen Wert eingeben.
Hinweis:
Wenn Benutzer die Regel aus dem Formular ausführen, erhalten diese ausgeblendeten Variablen Werte aus dem Formularkontext.
- Klicken Sie erneut auf
(Speichern). Klicken Sie auf OK, um die Informationsmeldung zu schließen. - Klicken Sie auf
(Validieren und bereitstellen). Geben Sie die folgenden RTP-Werte für die Validierung ein:- Mitarbeiter:
"Full Time Employees" - Entität:
"No Entity" - Zeitraum:
Jan - Szenario:
Current - Version:
"BU Version_1" - Jahr:
FY26

- Mitarbeiter:
- Wählen Sie Werte auf die Regel anwenden aus, um diese Werte als Standardwerte für die Validierung zu speichern, und klicken Sie auf OK.
Hinweis:
Bei der Validierung wird die Regel nicht ausgeführt. Gültige Elemente sind jedoch erforderlich, damit die Validierung erfolgreich verläuft. - Klicken Sie auf OK, wenn Sie dazu aufgefordert werden, und schließen Sie Calculation Manager.

Planungsaktionsmenüs zum Ausführen von Groovy-Skripten erstellen
In diesem Abschnitt erstellen Sie ein Aktionsmenü "Mitarbeiter verwalten" mit einer Menüoption, in der die Groovy-Regel ausgeführt wird.
- Klicken Sie in Planning auf
(Navigator), und wählen Sie unter "Erstellen und verwalten" die Option Aktionsmenüs aus.Hinweis:
Wenn Sie andere Groovy-Tutorials abgeschlossen haben, ist das Aktionsmenü "Mitarbeiter verwalten" möglicherweise bereits vorhanden. Wenn dies der Fall ist, fahren Sie mit Schritt 4 fort. - Klicken Sie auf
(Menü erstellen), um ein Aktionsmenü zu erstellen.
- Geben Sie als Menüname
Manage Employeesein, und klicken Sie auf OK.
- Wählen Sie das Aktionsmenü Mitarbeiter verwalten aus, und klicken Sie auf
(Menü "Bearbeiten").
- Klicken Sie auf
(Untergeordnetes Element hinzufügen). Geben Sie die folgenden Werte ein, oder wählen Sie sie aus:Optionsfeld Wert Menüelement Update Employee AddressBeschriftung Update Employee AddressTyp Geschäftsregel Obligatorische Parameter Mitarbeiter Cube Plan2 Geschäftsregel Groovy Mitarbeiteradresse hinzufügen oder aktualisieren 
- Klicken Sie auf Speichern. Klicken Sie in der Bestätigungsmeldung auf OK.

- Klicken Sie auf Speichern, um das Aktionsmenü zu speichern. Klicken Sie in der Bestätigungsmeldung auf OK.


- Klicken Sie auf Abbrechen, um den Editor für das Aktionsmenü zu schließen.
Planungsaktionsmenüs mit Formularen verknüpfen
In diesem Abschnitt verknüpfen Sie das Aktionsmenü "Mitarbeiter verwalten" mit dem Formular ManageEmployees.
- Klicken Sie auf
(Navigator) und wählen Sie Daten aus. - Klicken Sie auf ManageEmployees, um das Formular zu öffnen.

- Klicken Sie auf Aktionen, und wählen Sie Bearbeiten aus, um das Formular zu bearbeiten.
Im Formulareditor wird eine neue dynamische Registerkarte angezeigt.

- Wählen Sie die Registerkarte Sonstige Optionen.

- Fügen Sie der Liste "Ausgewählte Menüs" Mitarbeiter verwalten hinzu, und klicken Sie auf Speichern.

- Klicken Sie auf OK, um die Informationsmeldung zu schließen.

- Schließen Sie unten auf der Seite die dynamische Registerkarte ManageEmployees bearbeiten, um zum Eingabeformular zurückzukehren.
Groovy-Skript testen
In diesem Abschnitt führen Sie die Regel aus dem geöffneten ManageEmployees-Formular aus, um eine vollständige Adresse abzurufen und zu speichern, und prüfen dann das Joblog.
- Klicken Sie mit der rechten Maustaste auf Mitarbeiter 1, und wählen Sie Mitarbeiteradresse aktualisieren aus.

- Geben Sie im Prompt "Mitarbeiteradresse"
Oracle, Redwood Shoresein, und klicken Sie auf Starten.
- Klicken Sie auf OK, um die Informationsmeldung zu schließen.

Nach erfolgreichem Abschluss wird die von Google Maps zurückgegebene vollständige Adresse als Adresse für Mitarbeiter 1 gespeichert.

- Klicken Sie auf
(Navigator), und wählen Sie unter "Anwendung" die Option Jobs aus, um die Jobkonsole zu öffnen.
- Klicken Sie auf Mitarbeiteradresse hinzufügen oder aktualisieren, um die Jobdetails anzuzeigen.

- Blenden Sie unter "Ausführungsstatus" die Option Abgeschlossen ein, um die Logmeldungen anzuzeigen, die vom Groovy-Skript gedruckt werden.

Verwandte Links
- Planning-Tutorials – Wählen Sie Implementing Groovy aus der Liste der gewünschten Bereiche aus, um zusätzliche Groovy-Tutorials zu erkunden.
- Java-API-Referenz für Groovy-Regeln – Erkunden Sie die Groovy-APIs, die für die Entwicklung von Groovy-Regeln und -Vorlagen verfügbar sind.
- REST-APIs für Oracle Fusion Cloud EPM - Lernen Sie die REST-APIs kennen, die für die Verwaltung und Automatisierung von Cloud EPM-Aufgaben verfügbar sind.
Weitere Lernressourcen
Sehen Sie sich weitere Übungen zu docs.oracle.com/learn an, oder greifen Sie auf weitere kostenlose Lerninhalte im Oracle Learning YouTube-Kanal zu. Besuchen Sie außerdem education.oracle.com/learning-explorer, um ein Oracle Learning Explorer zu werden.
Die Produktdokumentation finden Sie im Oracle Help Center.
Externe REST-APIs mit Groovy aufrufen
G43143-02
November 2026