Introduction

Ce tutoriel vous 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 contextuel comportant une option d'appel du script et comment l'associer à un formulaire.

Renseignez les sections dans l'ordre.

Contexte

Le modèle objet EPM Groovy permet d'appeler des API REST internes (inter-POD ou autres services Oracle Cloud) 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 de l'employé dans le formulaire ManageEmployees.

Prérequis

Les tutoriels pratiques Cloud EPM peuvent vous obliger à importer un cliché dans une instance Cloud EPM Enterprise Service. Un cliché ne peut pas être importé sur une application ou un processus métier existant. Avant d'importer le cliché, utilisez une instance Cloud EPM Enterprise Service distincte ou enlevez l'application ou le processus métier existant de l'instance que vous prévoyez d'utiliser. L'import de l'instantané ne remplace ni ne restaure automatiquement le contenu existant.

Avant de commencer ce tutoriel, vous devez :

  • Demandez à l'administrateur de service d'accéder à une instance Cloud EPM Enterprise Service.
  • Téléchargez et importez ce cliché dans l'instance Planning. Si vous avez déjà téléchargé ce cliché pour un autre tutoriel Groovy, vous pouvez continuer à utiliser le même cliché.
  • 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, reportez-vous à Introduction à Google Maps Platform.

Remarques :

Si vous rencontrez des erreurs de migration lors de l'importation du cliché, réexécutez la migration en excluant le composant HSS-Shared Services, ainsi que les artefacts de sécurité et de préférences utilisateur du composant de base. Pour plus d'informations sur le téléchargement et l'import de clichés, reportez-vous à la documentation Administration de la migration pour Oracle Enterprise Performance Management Cloud.

Conseil :

Les scripts dont vous avez besoin pour ce tutoriel sont liés en tant que fichiers texte dans chaque section.

Charger des variables de calcul Planning

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

  1. Cliquez avec le bouton droit de la souris sur le lien de HP4_Plan2_Variables.xml et enregistrez le fichier sur votre disque 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 mises en évidence sous Créer et gérer
  3. Dans la vue 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 système développée avec l'option Import sélectionnée pour Plan2
  4. Sous Détails de l'importation de fichiers, accédez à HP4_Plan2_Variables.xml et sélectionnez-le à partir de votre lecteur local.
    Boîte de dialogue Import avec le fichier de variables de calcul sélectionné
  5. Sous Détails de l'emplacement, sélectionnez les valeurs suivantes :
    • Type d'application : EPM Cloud
    • Application : HP4
    • Cube : Plan2
  6. Sous Options d'import, sélectionnez Remplacer les objets existants.
    Boîte de dialogue Importer 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 d'importation de variables de calcul

    Remarques :

    Le message pour chaque objet peut dire "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 créez 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 Maps
  3. Cliquez sur Créer.
  4. Sélectionnez Autre fournisseur de services Web.
    Autre fournisseur de services Web mis en surbrillance sur la page de sélection de fournisseur
  5. Entrez les valeurs suivantes :
    • Nom de 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 :
    • Saisissez : Header
    • Sécurisé : sélectionné
    • Nom : X-Goog-Api-Key
    • Valeur : Votre clé d'API Google Maps

    Gardez votre clé d'API privée.

  8. Cliquez sur Ajouter (Ajouter) et définissez un autre en-tête à l'aide des valeurs suivantes :
    • Saisissez : Header
    • Sécurisé : effacé
    • Nom : X-Goog-FieldMask
    • Valeur : places.formattedAddress
    Mappe la connexion avec les 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 Maps enregistrée

Création d'un script Groovy

Dans cette section, vous allez créer 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 informations sur les employés
  1. Revenez à la fenêtre du navigateur Calculation Manager.
  2. Dans l'onglet Vue système, développez EPM Cloud, HP4, puis Plan2. Cliquez avec le lien droit sur Règles, puis sélectionnez Nouveau.
    Vue système développée avec Nouveau sélectionné 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ègles, remplacez l'option Concepteur par Modifier le script et définissez le type de script sur Script Groovy.
    Editeur de règles avec l'option Modifier le script et Groovy Script sélectionnée
  5. Copiez le 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 (RTP) 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 le RTP de l'employé.

    Note de code 3 Utilisez le RTP EmployeeAddress comme adresse par défaut lorsqu'aucune adresse formatée n'est affectée.

    Note de code 4 Utilisez la connexion Mappes pour envoyer une demande HTTP POST. Définissez le type de contenu sur application/json et transmettez la valeur EmployeeAddress entrée dans le champ textQuery JSON.

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

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

    Note de code 7 Générez le script de calcul pour enregistrer l'adresse de l'employé au croisement spécifié par les RTP.

    Remarques :

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

    Remarques :

    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 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 afin que les utilisateurs n'entrent une valeur que pour EmployeeAddress.

    Remarques :

    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 à nouveau sur Enregistrer (Enregistrer). Pour fermer le message d'information, cliquez sur OK.
  9. Cliquez sur Valider et déployer (Valider et déployer). Entrez les valeurs RTP suivantes pour la 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 des valeurs RTP avec les membres de validation et FY26
  10. Sélectionnez Appliquer des valeurs à la règle pour enregistrer ces valeurs comme valeurs par défaut pour la validation, puis cliquez sur OK.

    Remarques :

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

Créer des menus d'action de planification pour exécuter des scripts Groovy

Dans cette section, vous créez un menu d'actions Gérer les employés avec une option de menu qui exécute la règle Groovy.

  1. Dans Planning, cliquez sur Navigateur (Navigateur), puis, sous Créer et gérer, sélectionnez Menus d'action.

    Remarques :

    Si vous avez terminé d'autres tutoriels Groovy, le menu d'action Gérer les employés peut déjà exister. Si tel est le cas, passez à l'étape 4.
  2. Cliquez sur Créer un menu (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 Nom de menu, entrez Manage Employees, puis cliquez sur OK.
    Boîte de dialogue Créer un menu avec Gérer les employés saisie
  4. Sélectionnez le menu d'actions Manage Employees, puis cliquez sur Menu Modifier (menu Edit)
    Menu d'action 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
    IntituléUpdate Employee Address
    TypeRègle métier
    Paramètres requis Employé
    CubePlan2
    Règle métierGroovy - Ajouter ou mettre à jour l'adresse de l'employé
    Ajouter des paramètres enfant pour la règle métier Mettre à jour l'adresse de l'employé
  6. Cliquez sur Enregistrer. Lorsque le message confirmant la confirmation s'affiche, cliquez sur OK.
    Message d'information confirmant que l'option de menu a été enregistrée
  7. Cliquez sur Enregistrer pour enregistrer le menu d'actions. Lorsque le message confirmant la confirmation s'affiche, cliquez sur OK.
    Message d'information confirmant que le menu d'actions a été enregistré
    Menu d'action Gérer les employés enregistré contenant Mettre à jour l'adresse de l'employé
  8. Cliquez sur Annuler pour fermer l'éditeur de menu Action.

Associer des menus d'action de planification à des panneaux

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 en surbrillance
  4. Sélectionnez l'onglet Autres options.
    Onglet Autres options dans l'éditeur de formulaire
  5. Ajoutez Gérer les employés à la liste Menus sélectionnés, puis cliquez sur Enregistrer.
    Gérer les employés ajoutés aux menus sélectionnés
  6. Cliquez sur OK pour fermer le message d'information.
    Message d'information confirmant que le formulaire a été enregistré
  7. En bas de la page, fermez l'onglet dynamique Modifier ManageEmployees pour revenir 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 du travail.

  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 Adresse de l'employé avec Oracle, Redwood Shores saisie
  3. Cliquez sur OK pour fermer le message d'information.
    Message d'information confirmant l'exécution réussie de la règle d'adresse de l'employé

    Une fois terminée, l'adresse complète renvoyée par Google Maps est enregistrée comme adresse pour 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 Travaux pour ouvrir la console de jobs.
    Page Tous les travaux affichant la règle d'adresse de l'employé terminée
  5. Cliquez sur Ajouter ou mettre à jour l'adresse de l'employé Groovy pour afficher les détails du travail.
    Détails du travail avec des valeurs d'invite d'exécution réduites et terminées affichées
  6. Sous Statut d'exécution, développez Terminé pour afficher les messages de journal imprimés par le script Groovy.
    Statut Terminé étendu affichant la réponse HTTP 200, Google Places et l'adresse formatée

Ressources de formation supplémentaires

Explorez d'autres ateliers sur docs.oracle.com/learn ou accédez à d'autres contenus d'apprentissage gratuits sur le canal Oracle Learning YouTube. En outre, visitez le site education.oracle.com/learning-explorer pour devenir un explorateur Oracle Learning.

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