Présentation

Ce tutoriel explique comment appeler une API REST externe à partir d'un script Groovy dans Oracle EPM Cloud Planning. Vous apprendrez également à créer un menu d'actions avec un clic droit avec un élément de menu pour appeler le script et à associer le menu d'actions à un formulaire.

Remplissez les sections dans l'ordre.

Contexte

Le modèle d'objet Groovy EPM permet d'appeler des API REST internes (inter-POD ou autres services Oracle Cloud Services) et externes. Dans cet exemple, vous créez et exécutez une règle Groovy pour appeler une API REST Google Places externe afin d'ajouter ou de mettre à jour les informations d'adresse d'employé dans le formulaire ManageEmployees.

Préalables

Les tutoriels pratiques Cloud EPM peuvent nécessiter l'importation d'un instantané dans une instance Cloud EPM Enterprise Service. Un instantané ne peut pas être importé sur une application ou un processus d'affaires existant. Avant d'importer l'instantané, utilisez une instance distincte du service Cloud EPM Enterprise ou supprimez l'application ou le processus d'affaires existant de l'instance que vous prévoyez d'utiliser. L'importation de l'instantané ne remplace pas ou ne restaure pas automatiquement le contenu existant.

Avant de commencer ce tutoriel, vous devez :

  • Permet à l'administrateur de service d'accéder à une instance Cloud EPM Enterprise Service.
  • Chargez et importez cet instantané dans votre instance Planning. Si vous avez précédemment chargé cet instantané pour un autre tutoriel Groovy, vous pouvez continuer à utiliser le même instantané.
  • Avant de commencer à utiliser les API Google Maps Platform qui incluent l'API Places (Nouveau) utilisée dans ce tutoriel, vous devez vous inscrire et créer un compte de facturation pour acquérir une clé d'API. Pour en savoir plus, voir Introduction à la plate-forme Google Maps.

Note :

Si vous rencontrez des erreurs de migration lors de l'importation de l'instantané, réexécutez la migration à l'exclusion du composant HSS-Shared Services, ainsi que des artefacts Security et User Preferences du composant Core. Pour plus d'informations sur le chargement et l'importation d'instantanés, consultez la documentation sur l'administration de la migration pour Oracle Enterprise Performance Management Cloud.

Conseil :

Les scripts dont vous avez besoin pour ce tutoriel sont liés sous forme de fichiers texte dans chaque section.

Chargement des variables de calcul Planning

Dans cette section, vous allez charger des variables de calcul à partir d'un fichier XML à utiliser dans le script Groovy.

  1. Cliquez avec le bouton droit de la souris sur le lien HP4_Plan2_Variables.xml et enregistrez le fichier sur votre lecteur local.
  2. Cliquez sur Navigateur (Navigateur), puis, sous Créer et gérer, sélectionnez Règles pour ouvrir Calculation Manager.
    Navigateur avec règles mis en surbrillance sous Créer et gérer
  3. Dans la vue du système, développez EPM Cloud, puis HP4. Cliquez avec le bouton droit de la souris sur Plan2 et sélectionnez Importer.
    Hiérarchie de vue du système étendue avec importation sélectionnée pour Plan2
  4. Sous Détails de l'importation de fichiers, naviguez jusqu'à HP4_Plan2_Variables.xml et sélectionnez-le dans votre lecteur local.
    Boîte de dialogue d'importation avec le fichier de variables de calcul sélectionné
  5. Sous Location Details, sélectionnez les valeurs suivantes :
    • Type d'application : EPM Cloud
    • Application : HP4
    • Cube : Plan2
  6. Sous Options d'importation, sélectionnez Remplacer les objets existants.
    Boîte de dialogue d'importation avec EPM Cloud, HP4, Plan2 et Remplacer les objets existants sélectionnés
  7. Cliquez sur Importer. Vérifiez les résultats de l'importation, puis cliquez sur OK.
    Résultats de l'importation de variables de calcul

    Note :

    Le message de chaque objet peut indiquer "Inserted" ou "Updated".
  8. Cliquez sur Annuler pour fermer la boîte de dialogue Importer.

Créer une connexion nommée dans Planning

Dans cette section, vous allez créer une connexion Maps pour l'API Google Places.

  1. Laissez Calculation Manager ouvert et revenez à la fenêtre du navigateur Planning.
  2. Cliquez sur Navigateur (Navigateur), puis, sous Outils, sélectionnez Connexions.
    Page Gérer les connexions avant de créer la connexion Mappages
  3. Cliquez sur Créer.
  4. Sélectionnez Autre fournisseur de services Web.
    Autre fournisseur de services Web mis en évidence dans la page de sélection de fournisseur
  5. Entrez les valeurs suivantes :
    • Nom de la connexion : Maps
    • URL : https://places.googleapis.com/v1/places:searchText
  6. Cliquez sur Afficher les options avancées.
    Mappe les détails de connexion avec les options avancées affichées
  7. Définissez l'en-tête de clé d'API à l'aide des valeurs suivantes :
    • Type : En-tête
    • Sécurisé : Sélectionné
    • Nom : X-Goog-Api-Key
    • Valeur : Votre clé d'API Google Maps

    Conservez votre clé d'API privée.

  8. Cliquez sur Ajouter (Ajouter) et définissez un autre en-tête à l'aide des valeurs suivantes :
    • Type : En-tête
    • Sécurisé : Compensé
    • Nom : X-Goog-FieldMask
    • Valeur : places.formattedAddress
    Mappe la connexion avec les deux en-têtes configurés et la clé d'API masquée
  9. Cliquez sur Enregistrer et fermer pour enregistrer la connexion.
    Page Gérer les connexions avec la connexion Mappages enregistrée

Création d'un script Groovy

Dans cette section, vous créez une règle Groovy pour mettre à jour l'adresse d'un employé à l'aide du formulaire ManageEmployees prédéfini.

Formulaire ManageEmployees pour tenir à jour les renseignements sur les employés
  1. Revenez à la fenêtre de navigateur Calculation Manager.
  2. Dans l'onglet Vue du système, développez EPM Cloud, HP4, puis Plan2. Cliquez avec le bouton droit de la souris sur Règles, puis sélectionnez Nouveau.
    Vue système étendue avec la valeur Nouveau sélectionnée pour le dossier Règles Plan2
  3. Pour Nom, entrez Groovy Add or Update Employee Address, puis cliquez sur OK.
    Boîte de dialogue Nouvelle règle avec le nom de la règle d'adresse de l'employé
  4. Dans l'éditeur de règle, remplacez l'option Concepteur par Modifier le script et réglez le type de script à Script Groovy.
    Éditeur de règle avec le script de modification et le script Groovy sélectionnés
  5. Copiez ce script et collez-le dans l'éditeur :
    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;"""

    Note de code 1 Définissez toutes les invites d'exécution (invites d'exécution) utilisées par cette règle sur la première ligne.

    Note de code 2 Obtenez l'objet Member pour l'employé spécifié par l'invite d'exécution d'employé.

    Note de code 3 Utilisez l'invite d'exécution EmployeeAddress comme adresse par défaut lorsqu'aucune adresse formatée n'est affectée.

    Note de code 4 Utilisez la connexion au mappage pour envoyer une demande HTTP POST. Réglez le type de contenu à application/json et transmettez la valeur EmployeeAddress entrée dans le champ JSON textQuery.

    Note de code 5 Enregistrez le statut HTTP et le corps de la réponse pour le dépannage.

    Note de code 6 Analysez la réponse JSON à l'aide de JsonPath. Replacez explicitement le tableau places vers List afin que la vérification de type statique puisse résoudre isEmpty(). Lorsque le statut de la réponse est Réussite et que la liste n'est pas vide, lisez places[0].formattedAddress, convertissez-la en ID cellule de texte et affectez-la à address. Sinon, conservez la valeur initiale de l'invite d'exécution.

    Note de code 7 Générez le script de calcul pour enregistrer l'adresse de l'employé à l'intersection spécifiée par les invite d'exécution.

    Note :

    La connexion Maps est un lien de communication entre le script Groovy et la ressource API Google Places (New).
  6. Cliquez sur Enregistrer (enregistrer) dans la barre d'outils. Cliquez sur OK pour fermer le message d'information.

    Note :

    L'enregistrement du script affiche les variables dans l'onglet Variables.
    Message d'information confirmant que la règle Groovy a été enregistrée
    Règle enregistrée avec les invites d'exécution affichées dans l'onglet Variables
  7. Dans l'onglet Variables, sélectionnez Est masqué pour Employé, Entité, Période, Scénario, Version et Année, de sorte que les utilisateurs n'entrent une valeur que pour EmployeeAddress.

    Note :

    Lorsque les utilisateurs exécutent la règle à partir du formulaire, ces variables masquées reçoivent des valeurs du contexte du formulaire.
    Onglet Variables avec toutes les invites d'exécution sauf EmployeeAddress masqué
  8. Cliquez de nouveau sur Enregistrer (Enregistrer). Cliquez sur OK pour fermer le message d'information.
  9. Cliquez sur Valider et déployer (Valider et déployer). Entrez les valeurs d'invite d'exécution suivantes pour validation :
    • Employé : "Full Time Employees"
    • Entité : "No Entity"
    • Période : Jan
    • Scénario : Current
    • Version : "BU Version_1"
    • Année : FY26
    Boîte de dialogue Entrer les valeurs d'invite d'exécution avec les membres de validation et FY26
  10. Sélectionnez Appliquer des valeurs à la règle pour enregistrer ces valeurs en tant que valeurs par défaut pour la validation, puis cliquez sur OK.

    Note :

    La validation n'exécute pas la règle, mais des membres valides sont requis pour que la validation réussisse.
  11. Cliquez sur OK lorsque vous y êtes invité, puis fermez Calculation Manager.
    Message confirmant le déploiement de la règle réussi

Création de menus d'actions de planification pour exécuter des scripts Groovy

Dans cette section, vous allez créer un menu d'actions Manage Employees avec un élément de menu qui exécute la règle Groovy.

  1. Dans Planning, cliquez sur Navigateur (Navigateur), puis, sous Create and Manage (Créer et gérer), sélectionnez Action Menus (Menus d'actions).

    Note :

    Si vous avez terminé d'autres tutoriels Groovy, le menu d'actions Gérer les employés existe peut-être déjà. Si c'est le cas, passez à l'étape 4.
  2. Cliquez sur Menu Créer (menu Créer) pour créer un menu d'actions.
    Boîte de dialogue Créer un menu avant d'entrer le nom du menu
  3. Pour le nom du menu, entrez Manage Employees, puis cliquez sur OK.
    Boîte de dialogue Créer un menu avec Gérer les employés entrée
  4. Sélectionnez le menu d'actions Manage Employees (Gestion des employés), puis cliquez sur Modifier le menu (Menu Edit).
    Menu d'actions Gérer les employés ouvert pour modification
  5. Cliquez sur Ajouter un enfant (Ajouter un enfant). Entrez ou sélectionnez les valeurs suivantes :
    Champ d'optionValeur
    Option de menuUpdate Employee Address
    ÉtiquetteUpdate Employee Address
    TypeRègle d'affaires
    Paramètres requis Employé
    Cube Plan2
    Règle d'affaires Groovy - Ajouter ou mettre à jour l'adresse de l'employé
    Ajouter des paramètres enfants pour la règle d'affaires Mettre à jour l'adresse de l'employé
  6. Cliquez sur Enregistrer. Dans le message de confirmation, cliquez sur OK.
    Message d'information confirmant que l'élément de menu a été enregistré
  7. Cliquez sur Enregistrer pour enregistrer le menu d'actions. Dans le message de confirmation, cliquez sur OK.
    Message d'informations confirmant que le menu d'actions a été enregistré
    Menu d'actions Gérer les employés enregistré contenant Mettre à jour l'adresse de l'employé
  8. Cliquez sur Annuler pour fermer l'éditeur de menu d'actions.

Association de menus d'actions de planification à des formulaires

Dans cette section, vous associez le menu d'actions Gérer les employés au formulaire ManageEmployees.

  1. Cliquez sur Navigateur (Navigateur), puis sélectionnez Données.
  2. Cliquez sur ManageEmployees pour ouvrir le formulaire.
    Formulaire ManageEmployees avant d'associer le menu d'actions
  3. Cliquez sur Actions, puis sélectionnez Modifier pour modifier le formulaire.

    Un nouvel onglet dynamique s'affiche avec l'éditeur de formulaire.

    Menu Actions avec modification mise en surbrillance
  4. Sélectionnez l'onglet Autres options.
    Onglet Autres options dans l'éditeur de formulaire
  5. Ajoutez Manage Employees (Gérer les employés) à la liste Selected Menus (Menus sélectionnés), puis cliquez sur Save (Enregistrer).
    Gérer les employés ajoutés aux menus sélectionnés
  6. Cliquez sur OK pour fermer le message d'informations.
    Message d'information confirmant que le formulaire a été enregistré
  7. Au bas de la page, fermez l'onglet dynamique Modifier ManageEmployees pour retourner au formulaire.

Test du script Groovy

Dans cette section, vous exécutez la règle à partir du formulaire ManageEmployees ouvert pour extraire et enregistrer une adresse complète, puis consultez le journal des travaux.

  1. Cliquez avec le bouton droit de la souris sur Employé 1 et sélectionnez Mettre à jour l'adresse de l'employé.
    Menu contextuel Employé 1 avec mise à jour de l'adresse de l'employé en surbrillance
  2. Dans l'invite Adresse de l'employé, entrez Oracle, Redwood Shores, puis cliquez sur Lancer.
    Invite d'adresse d'employé avec Oracle, Redwood Shores entré
  3. Cliquez sur OK pour fermer le message d'informations.
    Message d'informations confirmant l'exécution réussie de la règle d'adresse de l'employé

    Une fois l'opération terminée, l'adresse complète retournée par Google Maps est enregistrée en tant qu'adresse de l'employé 1.

    Formulaire ManageEmployees avec l'adresse d'employé formatée enregistrée pour l'employé 1
  4. Cliquez sur Navigateur (Navigateur), puis, sous Application, sélectionnez Tâches pour ouvrir la console des tâches.
    Page Tous les emplois affichant la règle d'adresse d'employé terminée
  5. Cliquez sur Groovy Add or Update Employee Address (Ajouter ou mettre à jour l'adresse de l'employé) pour afficher les détails de l'emploi.
    Détails de la tâche avec valeurs d'invite réduites et d'exécution terminées affichés
  6. Sous Run Status (Statut d'exécution), développez Completed (Terminé) pour voir les messages de journal imprimés par le script Groovy.
    Statut Développé Terminé affichant la réponse HTTP 200, Google Places et l'adresse formatée

Autres ressources d'apprentissage

Explorez d'autres laboratoires sur le site docs.oracle.com/learn ou accédez à plus de contenu d'apprentissage gratuit sur le canal Oracle Learning YouTube. De plus, visitez education.oracle.com/learning-explorer pour devenir un explorateur Oracle Learning.

Pour obtenir la documentation sur le produit, visitez Oracle Help Center.