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.

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 votre instance Cloud EPM Enterprise Service. Pour pouvoir importer un instantané de tutoriel, vous devez demander une autre instance Cloud EPM Enterprise Service ou supprimer l'application et le processus métier en cours. L'instantané du tutoriel ne sera pas importé sur votre application ou processus métier existant, ni remplacé ou restauré automatiquement l'application ou le processus métier que vous utilisez actuellement.

Avant de commencer ce tutoriel, vous devez :

  • Demandez à 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 déjà téléchargé le 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 REST Places 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. En haut à gauche, cliquez sur le navigateur Icône Navigateur et accédez à Règles (sous Créer et gérer) pour ouvrir Calculation Manager. Dans la vue système, développez EPM Cloud > HP4. Cliquez avec le bouton droit de la souris sur Plan2 et sélectionnez Importer.
  3. Sous Détails de l'importation de fichiers, accédez à HP4_Plan2_Variables.xml à partir de votre lecteur local.
  4. Sous Détails de l'emplacement, effectuez les sélections suivantes :
    • Type d'application : EPM Cloud
    • Application : HP4
    • Cube : Plan2
  5. Sous Options d'import, sélectionnez Remplacer les objets existants.
    6. Importer des variables
  6. Conseil : par défaut, le portlet Jeu de transport - Services d'import est situé dans l'onglet Portail de l'onglet Administrer de la page Portal Builder. Vérifiez les résultats de l'importation, puis cliquez sur OK.
    Résultats d'import
  7. Cliquez sur Annuler pour fermer la boîte de dialogue Importer.

Créer une connexion nommée dans Planning

Dans cette section, vous allez modifier une connexion existante pour inclure la clé d'API REST Places.

  1. Accédez à Connexions (sous Outils), puis sélectionnez la connexion Lieux.
    2. Connexions
  2. Modifiez la connexion en entrant la clé d'API dans le paramètre de clé. Enregistrez et fermez la connexion.
    3. Paramètre de clé d'API

Création d'un script Groovy

Dans cette section, vous allez implémenter un script Groovy pour mettre à jour l'adresse d'un employé. Nous allons travailler avec le formulaire ManageEmployees prédéfini.

Gérer les employés
  1. Dans Calculation Manager, créez une règle nommée Adresse d'employé Groovy Add ou Update dans le cube Plan2.
    2. Nouvelle règle
  2. Dans l'éditeur de règles, remplacez l'option Designer par Modifier le script et définissez le type de script sur Script Groovy.
    3. Options d'éditeur de règles
  3. Copiez le script et collez-le dans l'éditeur :
    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;"""

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

    Obtenez l'objet Member pour employee indiqué par le RTP Employee.

    Affectez le texte saisi dans le RTP EmployeeAddress comme valeur par défaut pour address.

    Obtenez la connexion Places pour exécuter la demande HTTP GET sur cette ressource et transmettez le texte saisi dans le RTP EmployeeAddress en tant que valeur pour le paramètre de requête input.

    Remarques :

    L'objet de connexion Places est un lien de communication entre le script Groovy et la ressource d'API REST Google Places.

    Consignez la réponse de l'API REST Google Maps à des fins de débogage.

    Analysez la réponse JSON reçue de l'API à l'aide de la bibliothèque JsonPath. Si le statut == OK, lisez le champ formatted_address à partir du premier objet du candidat dans le tableau renvoyé, obtenez l'ID de cellule de texte pour formatted_address et affectez-le à l'adresse.

    Générez le script de calcul pour enregistrer l'adresse de cet employé.

  4. Dans la barre d'outils, cliquez sur Enregistrement (Enregistrer) pour enregistrer le script.

    5. Remarques :

    L'enregistrement du script affiche les variables dans l'onglet Variables.
  5. Vous voulez que les utilisateurs ne saisissent des valeurs que pour EmployeeAddress. Dans l'onglet Variables, sélectionnez Est masqué pour Employé, Entité, Période, Scénario, Version et Année.
    6. Variables masquées

    Remarques :

    Lorsque les utilisateurs exécutent le script à partir du formulaire, les valeurs de ces variables masquées sont affectées à partir du contexte du formulaire.
  6. Enregistrez à nouveau le script.
  7. Cliquez sur Valider et déployer (Valider et déployer). Entrez des valeurs RTP à des fins de validation :
    • Employé : Full Time Employees
    • Entité : No Entity
    • Période : Jan
    • Scénario : Current
    • Version : BU_Version_1
    • Année : FY16
    Options d'éditeur de règles
  8. Cochez la case Appliquer des valeurs à la règle pour enregistrer ces valeurs comme valeurs par défaut à des fins de validation, puis cliquez sur OK.

    9. Remarques :

    Au cours de cette étape, la règle n'est pas exécutée. Toutefois, vous devez entrer des membres valides pour que le processus de validation réussisse.
  9. Cliquez sur OK lorsque vous y êtes invité, puis fermez Calculation Manager.

Créer des menus d'actions Planning pour exécuter des scripts Groovy

Dans cette section, vous créez un menu d'actions appelé Gérer les employés, avec une option de menu d'actions en cliquant avec le bouton droit de la souris qui exécute le script Groovy.

  1. En haut à gauche, cliquez sur le navigateur Icône Navigateur, accédez aux menus d'action (situés sous Créer et gérer) et créez un menu d'action nommé Gérer les employés.
    2. Créer le menu d'action Gérer les employés
  2. Modifiez le menu d'actions Gérer les employés et ajoutez une option de menu enfant nommée Mettre à jour l'adresse des employés. Saisissez ou sélectionnez les options suivantes pour définir l'option de menu :
    3. Champ d'option Valeur à saisir ou à sélectionner
    Option de menu Mettre à jour l'adresse du salarié
    Intitulé Mettre à jour l'adresse du salarié
    Type Règle métier
    Paramètres requis Employé
    Cube Plan2
    Règle métier Groovy - Ajouter ou mettre à jour l'adresse de l'employé

    Mettre à jour l'élément de menu Adresse de l'employé

  3. Cliquez sur Enregistrer, puis sur OK pour enregistrer l'option de menu. Enfin, cliquez sur Enregistrer pour enregistrer le menu d'actions.
    4. Menu d'action Gérer les employés terminé

Associer des menus d'actions Planning à des panneaux

Cette étape consiste à associer le menu d'actions au formulaire ManageEmployees et à tester le script.

  1. Accédez à Formulaires (situé sous Créer et gérer) et modifiez le formulaire ManageEmployees.
    2. Modifier le formulaire Gérer les employés
  2. Dans l'onglet Autres options, ajoutez le menu contextuel Gérer les employés à la liste Menus sélectionnés.
    3. Ajouter le menu contextuel Gérer les employés
  3. Cliquez sur Terminer pour enregistrer les modifications apportées au formulaire.
  4. Fermez le gestionnaire de formulaires et revenez à la page d'accueil.

Tester le script Groovy

Cette étape consiste à tester le script. La procédure de test inclut la saisie d'un emplacement valide pour le RTP EmployeeAddress afin de récupérer l'adresse complète de l'emplacement.

  1. En haut à gauche, cliquez sur Icône Navigateur Navigateur et sur Données pour afficher la liste des formulaires de saisie de données, puis cliquez sur ManageEmployees pour ouvrir le formulaire Gérer les employés.
    2. Liste des formulaires de saisie de données
  2. Pour tester le script Groovy, cliquez avec le bouton droit de la souris sur Employé 1 et sélectionnez l'option de menu Mettre à jour l'adresse de l'employé.
    3. Boîte de dialogue Ajouter un employé avec un nom et un courriel non valides
  3. Dans l'invite Adresse de l'employé, saisissez Oracle, San Jose, puis cliquez sur Lancer.
    4. Message d'erreur de nom d'employé non valide

    Une fois le lancement réussi, vous devez voir l'adresse complète d'Oracle, San Jose, enregistrée en tant qu'adresse complète pour Employee 1.

    Message d'erreur de courriel d'employé non valide
  4. Enregistrez et fermez le formulaire. Accédez à Travaux (sous Application) pour ouvrir la console des travaux.
    5. Console de jobs
  5. Cliquez sur Ajouter et mettre à jour une adresse d'employé Groovy pour afficher les détails de l'emploi. Cliquez sur le statut Terminé pour afficher les messages de journal imprimés par le script Groovy.
    6. Messages du journal de script Groovy

Ressources de formation supplémentaires

Explorez d'autres ateliers sur le site docs.oracle.com/learn ou accédez à d'autres contenus d'apprentissage gratuits sur le canal Oracle Learning YouTube. En outre, visitez Oracle University pour consulter les ressources de formation disponibles.

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