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.

  1. Klicken Sie mit der rechten Maustaste auf den Link für HP4_Plan2_Variables.xml, und speichern Sie die Datei auf dem lokalen Laufwerk.
  2. Klicken Sie auf Navigator (Navigator), und wählen Sie unter "Erstellen und verwalten" die Option Regeln aus, um Calculation Manager zu öffnen.
    Navigator mit unter "Erstellen" und "Verwalten" hervorgehobenen Regeln
  3. Blenden Sie in der Systemansicht EPM Cloud, HP4 ein. Klicken Sie mit der rechten Maustaste auf Plan2, und wählen Sie Importieren aus.
    Erweiterte Systemansichtshierarchie mit ausgewähltem Import für Plan2
  4. Navigieren Sie unter "Dateiimportdetails" zu HP4_Plan2_Variables.xml, und wählen Sie es auf Ihrem lokalen Laufwerk aus.
    Dialogfeld "Importieren" mit ausgewählter Datei für Berechnungsvariablen
  5. Wählen Sie unter "Standortdetails" die folgenden Werte aus:
    • Anwendungstyp: EPM Cloud
    • Anwendung: HP4
    • Cube: Plan2
  6. Wählen Sie unter "Importoptionen" die Option Vorhandene Objekte überschreiben aus.
    Dialogfeld "Importieren" mit ausgewählten EPM Cloud-, HP4-, Plan2- und Override-Vorhandenen Objekten
  7. Klicken Sie auf Importieren. Prüfen Sie die Importergebnisse, und klicken Sie auf OK.
    Ergebnisse des Imports von Berechnungsvariablen

    Hinweis:

    Die Nachricht für jedes Objekt kann "Eingefügt" oder "Aktualisiert" lauten.
  8. 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.

  1. Lassen Sie Calculation Manager geöffnet, und kehren Sie zum Planning-Browserfenster zurück.
  2. Klicken Sie auf Navigator (Navigator), und wählen Sie unter "Tools" die Option Verbindungen aus.
    Seite "Verbindungen verwalten", bevor die Maps-Verbindung erstellt wird
  3. Klicken Sie auf Erstellen.
  4. Wählen Sie Anderer Webserviceprovider aus.
    Anderer Webserviceprovider, der auf der Seite zur Providerauswahl hervorgehoben ist
  5. Geben Sie folgende Werte ein:
    • Verbindungsname: Maps
    • URL: https://places.googleapis.com/v1/places:searchText
  6. Klicken Sie auf Erweiterte Einstellungen anzeigen.
    Ordnet Verbindungsdetails mit erweiterten Optionen zu
  7. 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.

  8. Klicken Sie auf Hinzufügen (Hinzufügen), und definieren Sie einen anderen Header mit den folgenden Werten:
    • Typ: Header
    • Sicher: Gelöscht
    • Name: X-Goog-FieldMask
    • Wert: places.formattedAddress
    Ordnet Verbindung sowohl mit konfigurierten Headern als auch mit maskiertem API-Schlüssel zu
  9. Klicken Sie auf Speichern und schließen, um die Verbindung zu speichern.
    Seite "Verbindungen verwalten" mit der gespeicherten Maps-Verbindung

Groovy-Skripte erstellen

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

ManageEmployees-Formular zur Verwaltung von Mitarbeiterinformationen
  1. Kehren Sie zum Browserfenster von Calculation Manager zurück.
  2. 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.
    Erweiterte Systemansicht mit Neu ausgewählt für den Ordner Plan2 Rules
  3. Geben Sie als Namen Groovy Add or Update Employee Address ein, und klicken Sie auf OK.
    Dialogfeld "Neue Regel" mit dem Namen der Mitarbeiteradressregel
  4. Ändern Sie im Regeleditor die Designeroption in Skript bearbeiten, und setzen Sie den Skripttyp auf Groovy-Skript.
    Regeleditor mit ausgewähltem Bearbeitungsskript und Groovy-Skript
  5. Kopieren Sie dieses Skript und fügen Sie es in den Editor ein:
    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;"""

    Codehinweis 1 Definieren Sie alle Runtime Prompts (RTPs), die von dieser Regel in der ersten Zeile verwendet werden.

    Codehinweis 2 Rufen Sie das Objekt Member für den vom Mitarbeiter-RTP angegebenen Mitarbeiter ab.

    Codehinweis 3 Verwenden Sie den RTP EmployeeAddress als Standardadresse, wenn keine formatierte Adresse zugewiesen ist.

    Codehinweis 4 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-Feld textQuery.

    Codehinweis 5 Protokollieren Sie den HTTP-Status und den Antwortbody zur Fehlerbehebung.

    Codehinweis 6 Parsen Sie die JSON-Antwort mit JsonPath. Setzen Sie das Array places explizit in List, damit die statische Typprüfung isEmpty() auflösen kann. Wenn der Antwortstatus erfolgreich ist und die Liste nicht leer ist, lesen Sie places[0].formattedAddress, konvertieren Sie ihn in eine Textzellen-ID, und weisen Sie ihn address zu. Andernfalls behalten Sie den ursprünglichen RTP-Wert bei.

    Codehinweis 7 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.
  6. Klicken Sie in der Symbolleiste auf Speichern (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.
    Informationsmeldung, die bestätigt, dass die Groovy-Regel gespeichert wurde
    Gespeicherte Regel mit Laufzeit-Prompts, die auf der Registerkarte "Variablen" angezeigt werden
  7. 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.
    Registerkarte "Variablen" mit allen Runtime Prompts außer EmployeeAddress ausgeblendet
  8. Klicken Sie erneut auf Speichern (Speichern). Klicken Sie auf OK, um die Informationsmeldung zu schließen.
  9. Klicken Sie auf Validieren und Bereitstellen (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
    Dialogfeld "RTP-Werte" mit den Validierungselementen und FY26 eingeben
  10. 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.
  11. Klicken Sie auf OK, wenn Sie dazu aufgefordert werden, und schließen Sie Calculation Manager.
    Meldung zur Bestätigung des erfolgreichen Regel-Deployments

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.

  1. Klicken Sie in Planning auf Navigator (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.
  2. Klicken Sie auf Menü erstellen (Menü erstellen), um ein Aktionsmenü zu erstellen.
    Dialogfeld "Menü erstellen" vor Eingabe des Menünamens
  3. Geben Sie als Menüname Manage Employees ein, und klicken Sie auf OK.
    Dialogfeld "Menü erstellen" mit Eingabe von "Mitarbeiter verwalten"
  4. Wählen Sie das Aktionsmenü Mitarbeiter verwalten aus, und klicken Sie auf Menü Bearbeiten (Menü "Bearbeiten").
    Aktionsmenü "Mitarbeiter verwalten", das zur Bearbeitung geöffnet ist
  5. Klicken Sie auf Untergeordnetes Element hinzufügen (Untergeordnetes Element hinzufügen). Geben Sie die folgenden Werte ein, oder wählen Sie sie aus:
    OptionsfeldWert
    MenüelementUpdate Employee Address
    BeschriftungUpdate Employee Address
    TypGeschäftsregel
    Obligatorische ParameterMitarbeiter
    CubePlan2
    GeschäftsregelGroovy Mitarbeiteradresse hinzufügen oder aktualisieren
    Untergeordnete Einstellungen für die Geschäftsregel "Mitarbeiteradresse aktualisieren" hinzufügen
  6. Klicken Sie auf Speichern. Klicken Sie in der Bestätigungsmeldung auf OK.
    Informationsmeldung, die bestätigt, dass der Artikel gespeichert wurde
  7. Klicken Sie auf Speichern, um das Aktionsmenü zu speichern. Klicken Sie in der Bestätigungsmeldung auf OK.
    Informationsmeldung, die bestätigt, dass das Aktionsmenü gespeichert wurde
    Aktionsmenü "Mitarbeiter verwalten" mit "Mitarbeiteradresse aktualisieren"
  8. 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.

  1. Klicken Sie auf Navigator (Navigator) und wählen Sie Daten aus.
  2. Klicken Sie auf ManageEmployees, um das Formular zu öffnen.
    Formular ManageEmployees, bevor das Aktionsmenü zugeordnet wird
  3. Klicken Sie auf Aktionen, und wählen Sie Bearbeiten aus, um das Formular zu bearbeiten.

    Im Formulareditor wird eine neue dynamische Registerkarte angezeigt.

    Menü "Aktionen" mit hervorgehobener Option "Bearbeiten"
  4. Wählen Sie die Registerkarte Sonstige Optionen.
    Registerkarte "Sonstige Optionen" im Formulareditor
  5. Fügen Sie der Liste "Ausgewählte Menüs" Mitarbeiter verwalten hinzu, und klicken Sie auf Speichern.
    Mitarbeiter verwalten, die ausgewählten Menüs hinzugefügt wurden
  6. Klicken Sie auf OK, um die Informationsmeldung zu schließen.
    Informationsmeldung, die bestätigt, dass das Formular gespeichert wurde
  7. 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.

  1. Klicken Sie mit der rechten Maustaste auf Mitarbeiter 1, und wählen Sie Mitarbeiteradresse aktualisieren aus.
    Kontextmenü "Mitarbeiter 1", wobei "Mitarbeiteradresse aktualisieren" hervorgehoben ist
  2. Geben Sie im Prompt "Mitarbeiteradresse" Oracle, Redwood Shores ein, und klicken Sie auf Starten.
    Prompt für Mitarbeiteradresse mit Eingabe von Oracle, Redwood Shores
  3. Klicken Sie auf OK, um die Informationsmeldung zu schließen.
    Informationsmeldung zur Bestätigung der erfolgreichen Ausführung der Mitarbeiteradressregel

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

    Formular ManageEmployees mit der formatierten Mitarbeiteradresse, die für Mitarbeiter 1 gespeichert ist
  4. Klicken Sie auf Navigator (Navigator), und wählen Sie unter "Anwendung" die Option Jobs aus, um die Jobkonsole zu öffnen.
    Seite "Alle Tätigkeiten" mit der abgeschlossenen Mitarbeiteradressregel
  5. Klicken Sie auf Mitarbeiteradresse hinzufügen oder aktualisieren, um die Jobdetails anzuzeigen.
    Jobdetails mit ausgeblendeten und angezeigten Runtime Prompt-Werten
  6. Blenden Sie unter "Ausführungsstatus" die Option Abgeschlossen ein, um die Logmeldungen anzuzeigen, die vom Groovy-Skript gedruckt werden.
    Erweiterter Status "Abgeschlossen" mit HTTP 200, Google Places-Antwort und der formatierten Adresse

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.