Einführung

In diesem Tutorial wird gezeigt, 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.

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 Ihre Cloud EPM Enterprise Service-Instanz importieren. Bevor Sie einen Tutorial-Snapshot importieren können, müssen Sie eine andere Cloud EPM Enterprise Service-Instanz anfordern oder Ihre aktuelle Anwendung und Ihren aktuellen Geschäftsprozess entfernen. Der Tutorial-Snapshot wird weder über Ihre vorhandene Anwendung oder Ihren vorhandenen Geschäftsprozess importiert, noch wird er die Anwendung oder den Geschäftsprozess, mit dem Sie derzeit arbeiten, automatisch ersetzen oder wiederherstellen.

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 das Snapshot zuvor für ein anderes Groovy-Tutorial hochgeladen haben, können Sie den gleichen Snapshot weiterhin verwenden.
  • Bevor Sie mit der Verwendung der Google Maps Platform-APIs beginnen können, die die Places REST-API enthält, 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 werden geladen...

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 oben links auf Navigatorsymbol Navigator, und navigieren Sie zu Regeln (unter "Erstellen und verwalten"), 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.
  3. Suchen Sie unter "Dateiimportdetails", um HP4_Plan2_Variables.xml von Ihrem lokalen Laufwerk zu wählen.
  4. Treffen Sie unter "Standortdetails" die folgende Auswahl:
    • Anwendungstyp: EPM Cloud
    • Anwendung: HP4
    • Cube: Plan2
  5. Wählen Sie unter "Importoptionen" die Option Vorhandene Objekte überschreiben aus.
    6. Variablen importieren
  6. Klicken Sie auf Importieren. Prüfen Sie die Importergebnisse, und klicken Sie auf OK.
    Ergebnisse importieren
  7. Klicken Sie auf Cancel (Abbrechen), um das Dialogfeld "Import" zu schließen.

Benannte Verbindungen in Planning erstellen

In diesem Abschnitt bearbeiten Sie eine vorhandene Verbindung, um den REST-API-Schlüssel "Places" einzuschließen.

  1. Navigieren Sie zu Verbindungen (unter "Tools"), und wählen Sie die Verbindung Plätze aus.
    2. Verbindungen
  2. Bearbeiten Sie die Verbindung, indem Sie den API-Schlüssel in den Schlüsselparameter eingeben. Speichern und schließen Sie die Verbindung.
    3. API-Schlüsselparameter

Groovy-Skript erstellen

In diesem Abschnitt implementieren Sie ein Groovy-Skript, um eine Mitarbeiteradresse zu aktualisieren. Wir arbeiten mit dem vordefinierten ManageEmployees-Formular.

Mitarbeiter verwalten
  1. Erstellen Sie in Calculation Manager eine Regel mit dem Namen Groovy Add or Update Employee Address im Cube Plan2.
    2. Neue Regel
  2. Ändern Sie im Regeleditor die Designeroption in Skript bearbeiten, und setzen Sie den Skripttyp auf Groovy-Skript.
    3. Regeleditoroptionen
  3. Kopieren Sie dieses Skript und fügen Sie es in den Editor ein:
    4. /*RTPS: {Employee} {EmployeeAddress} {Scenario} {Year} {Period} {Entity} {Version}*/ 
Member employee = rtps.Employee.member  

// Get the complete address using the Google maps REST API. Use the original if Google maps can't find the address
def address = rtps.EmployeeAddress  
HttpResponse<String> jsonResponse = operation.application.getConnection("Places")
.get()
.queryParam("input", rtps.EmployeeAddress.enteredValue)
.asString()  
println(jsonResponse.body)  
ReadContext ctx = JsonPath.parse(jsonResponse.body) 
if(ctx.read('$.status') == "OK") 
	address = getTextCellId(ctx.read('$.candidates[0].formatted_address') as String, true) 

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

    Ruft das Member-Objekt für employee ab, das vom Employee RTP angegeben wird.

    Weisen Sie den in EmployeeAddress RTP eingegebenen Text als Standardwert für address zu.

    Rufen Sie die Places-Verbindung ab, um die HTTP-GET-Anforderung für diese Ressource auszuführen, und übergeben Sie den in EmployeeAddress RTP eingegebenen Text als Wert für den Abfrageparameter input.

    Hinweis:

    Das Verbindungsobjekt Places ist eine Kommunikationsverbindung zwischen dem Groovy-Skript und der REST-API-Ressource für Google Places.

    Protokollieren Sie die REST-API-Antwort von Google Maps zum Debugging.

    Parsen Sie die von der API empfangene JSON-Antwort mit der JsonPath-Bibliothek. Wenn der Status == OK ist, lesen Sie das Feld formatted_address aus dem Objekt des ersten Kandidaten im zurückgegebenen Array, rufen Sie die Textzellen-ID für die formatted_address ab, und weisen Sie sie der Adresse zu.

    Generieren Sie das Berechnungsskript, um diese Mitarbeiteradresse zu speichern.

  4. Klicken Sie auf der Symbolleiste auf Speichern (Speichern), um das Skript zu speichern.

    5. Hinweis:

    Wenn Sie das Skript speichern, werden die Variablen in der Registerkarte "Variablen" angezeigt.
  5. Sie möchten, dass Benutzer nur Werte für EmployeeAddress eingeben. Wählen Sie auf der Registerkarte "Variablen" für Mitarbeiter, Entity, Periode, Szenario, Version und Jahr die Option Ausgeblendet.
    6. Ausgeblendete Variablen

    Hinweis:

    Wenn Benutzer das Skript aus dem Formular ausführen, werden diesen ausgeblendeten Variablen Werte aus dem Formularkontext zugewiesen.
  6. Speichern Sie das Skript erneut.
  7. Klicken Sie auf Validieren und Bereitstellen (Validieren und bereitstellen). Geben Sie RTP-Werte für Validierungszwecke ein:
    • Mitarbeiter: Full Time Employees
    • Entität: No Entity
    • Zeitraum: Jan
    • Szenario: Current
    • Version: BU_Version_1
    • Jahr: FY16
    Regeleditoroptionen
  8. Aktivieren Sie Werte auf die Regel anwenden, um diese Werte zu Validierungszwecken als Standardwerte zu speichern, und klicken Sie dann auf OK.

    9. Hinweis:

    In diesem Schritt wird die Regel nicht ausgeführt. Sie müssen jedoch gültige Elemente eingeben, damit der Validierungsprozess erfolgreich verläuft.
  9. Klicken Sie auf OK, wenn Sie dazu aufgefordert werden, und schließen Sie Calculation Manager.

Planning-Aktionsmenüs zum Ausführen von Groovy-Skripten erstellen

In diesem Abschnitt erstellen Sie ein Aktionsmenü namens "Mitarbeiter verwalten" mit einem Kontextmenüeintrag für Aktionen, in dem das Groovy-Skript ausgeführt wird.

  1. Klicken Sie oben links auf den Navigatorsymbol Navigator, und navigieren Sie zu Aktionsmenüs (unter "Erstellen und verwalten"), und erstellen Sie ein Aktionsmenü mit dem Namen Mitarbeiter verwalten.
    2. Aktionsmenü "Mitarbeiter verwalten" erstellen
  2. Bearbeiten Sie das Aktionsmenü "Mitarbeiter verwalten", und fügen Sie eine untergeordnete Menüoption mit dem Namen Mitarbeiteradresse aktualisieren hinzu. Geben Sie die folgenden Optionen ein, oder wählen Sie sie aus, um die Menüoption zu definieren:
    3. Optionsfeld Einzugebender oder auszuwählender Wert
    Menüelement Mitarbeiteradresse aktualisieren
    Beschriftung Mitarbeiteradresse aktualisieren
    Typ Geschäftsregel
    Obligatorische Parameter Mitarbeiter
    Cube Plan2
    Geschäftsregel Groovy Mitarbeiteradresse hinzufügen oder aktualisieren

    Menüoption "Mitarbeiteradresse aktualisieren"

  3. Klicken Sie auf Speichern und dann auf OK, um die Menüoption zu speichern. Klicken Sie schließlich auf Speichern, um das Aktionsmenü zu speichern.
    4. Aktionsmenü "Abgeschlossene Mitarbeiter verwalten"

Planning-Aktionsmenüs Formularen zuordnen

In diesem Schritt verknüpfen Sie das Aktionsmenü mit dem Formular ManageEmployees und testen das Skript.

  1. Navigieren Sie zu Formulare (unter "Erstellen und verwalten"), und bearbeiten Sie das Formular ManageEmployees.
    2. Formular "Mitarbeiter verwalten" bearbeiten
  2. Fügen Sie auf der Registerkarte "Sonstige Optionen" das Kontextmenü Mitarbeiter verwalten zur Liste "Ausgewählte Menüs" hinzu.
    3. Kontextmenü "Mitarbeiter verwalten" hinzufügen
  3. Klicken Sie auf Fertigstellen, um Änderungen am Formular zu speichern.
  4. Schließen Sie den Formularmanager, und kehren Sie zur Homepage zurück.

Groovy-Skript testen

In diesem Schritt testen Sie das Skript. Das Testverfahren umfasst die Eingabe eines gültigen Ortes für den RTP EmployeeAddress, um die vollständige Adresse für den Ort abzurufen.

  1. Klicken Sie oben links auf Navigatorsymbol Navigator, und klicken Sie auf Daten, um die Liste der Eingabeformulare anzuzeigen. Klicken Sie dann auf ManageEmployees, um das Formular "Mitarbeiter verwalten" zu öffnen.
    2. Liste der Dateneingabeformulare
  2. Um das Groovy-Skript zu testen, klicken Sie mit der rechten Maustaste auf Mitarbeiter 1, und wählen Sie die Menüoption Mitarbeiteradresse aktualisieren.
    3. Dialogfeld "Mitarbeiter hinzufügen" mit ungültiger E-Mail und ungültigem Namen
  3. Geben Sie im Prompt "Mitarbeiteradresse" Oracle, San Jose ein, und klicken Sie auf Starten.
    4. Fehlermeldung für ungültigen Mitarbeiternamen

    Nach dem erfolgreichen Start sollte die vollständige Adresse für Oracle, San Jose, als vollständige Adresse für Mitarbeiter 1 gespeichert werden.

    Ungültige E-Mail-Fehlermeldung für Mitarbeiter
  4. Speichern und schließen Sie das Formular. Navigieren Sie zu Jobs (unter "Anwendung"), um die Jobkonsole zu öffnen.
    5. Jobkonsole
  5. Klicken Sie auf Groovy-Mitarbeiteradresse hinzufügen und aktualisieren, um die Jobdetails anzuzeigen. Klicken Sie auf den Status Abgeschlossen, um die Logmeldungen anzuzeigen, die vom Groovy-Skript gedruckt wurden.
    6. Groovy-Skriptprotokollmeldungen

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 Oracle University, um verfügbare Schulungsressourcen anzuzeigen.

Die Produktdokumentation finden Sie im Oracle Help Center.