Présentation

Ce tutoriel explique comment appeler une API de repos 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.

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 votre instance Cloud EPM Enterprise Service. Avant d'importer un instantané de tutoriel, vous devez demander une autre instance du service Cloud EPM Enterprise ou supprimer l'application et le processus d'affaires courants. L'instantané du tutoriel ne sera pas importé sur votre application ou processus d'affaires existant, et il ne remplacera pas ou ne restaurera pas automatiquement l'application ou le processus d'affaires avec lequel vous travaillez actuellement.

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é l'instantané pour un autre tutoriel Groovy, vous pouvez continuer à utiliser le même instantané.
  • Avant de commencer à utiliser les API de la plate-forme Google Maps, 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, 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. En haut à gauche, cliquez sur le navigateur Icône de navigateur et naviguez jusqu'à 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, naviguez jusqu'à sélectionner HP4_Plan2_Variables.xml dans votre lecteur local.
  4. Sous Location Details, effectuez les sélections suivantes :
    • Type d'application : EPM Cloud
    • Application : HP4
    • Cube : Plan2
  5. Sous Options d'importation, sélectionnez Remplacer les objets existants.
    6. Importer des variables
  6. Cliquez sur Importer. Vérifiez les résultats de l'importation, puis cliquez sur OK.
    Résultats d'importation
  7. Cliquez sur Annuler pour fermer la boîte de dialogue Importer.

Créer une connexion nommée dans Planning

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

  1. Naviguez jusqu'à Connexions (sous Outils), puis sélectionnez la connexion Places.
    2. Connexions
  2. Modifiez la connexion en entrant la clé d'API dans le paramètre de clé. Enregistrer et fermer 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 travaillerons avec le formulaire ManageEmployees prédéfini.

Gérer les employés
  1. Dans Calculation Manager, créez une règle nommée Groovy Add or Update Employee Address (Ajouter ou mettre à jour l'adresse de l'employé) dans le cube Plan2.
    2. Nouvelle règle
  2. Dans l'éditeur de règle, remplacez l'option Concepteur par Modifier le script et réglez le type de script à Script Groovy.
    3. Options de l'éditeur de règle
  3. Copiez ce 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 (invites d'exécution) utilisées par cette règle sur la première ligne.

    Obtenez l'objet Membre pour employee spécifié par l'invite d'exécution d'employé.

    Affectez le texte entré dans l'invite d'exécution 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 entré dans l'invite d'exécution EmployeeAddress en tant que valeur pour le paramètre d'interrogation input.

    Note :

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

    Enregistrez 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 de l'objet du premier candidat dans le tableau retourné, obtenez l'ID 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 Enregistrer (enregistrer) pour enregistrer le script.

    5. Note :

    L'enregistrement du script affiche les variables dans l'onglet Variables.
  5. Vous voulez que les utilisateurs n'entrent des valeurs que pour EmployeeAddress. Dans l'onglet Variables, sélectionnez Is Hidden (Est masqué) pour Employee (Employé), Entity (Entité), Period (Période), Scenario (Scénario), Version et Year (Année).
    6. Variables masquées

    Note :

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

    9. Note :

    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éation de menus d'actions Planning pour exécuter des scripts Groovy

Dans cette section, vous allez créer un menu d'actions nommé Manage Employees, avec un clic droit sur l'élément de menu d'actions qui exécute le script Groovy.

  1. En haut à gauche, cliquez sur Icône de navigateur Navigateur et naviguez jusqu'à Menus d'actions (situés sous Créer et gérer) et créez un menu d'actions nommé Gérer les employés.
    2. Menu Action Créer une gestion des employés
  2. Modifiez le menu d'actions Gérer les employés et ajoutez un élément de menu enfant nommé Update Employee Address (Mettre à jour l'adresse de l'employé). Entrez ou sélectionnez les options suivantes pour définir l'élément de menu :
    3. Champ d'option Valeur à entrer ou à sélectionner
    Option de menu Mettre à jour l'adresse de l'employé
    Étiquette Mettre à jour l'adresse de l'employé
    Type Règle d'affaires
    Paramètres requis Employé
    Cube Plan2
    Règle d'affaires 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'élément de menu. Enfin, cliquez sur Enregistrer pour enregistrer le menu d'actions.
    4. Menu Action Gérer les employés - Terminé

Association de menus d'actions Planning à des formulaires

Dans cette étape, vous associez le menu d'actions au formulaire ManageEmployees et vous testez votre script.

  1. Naviguez jusqu'à Formulaires (situés sous Créer et gérer) et modifiez le formulaire ManageEmployees.
    2. Modifier l'écran 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 retournez à la page d'accueil.

Test du script Groovy

Dans cette étape, vous allez tester le script. La procédure de test consiste à entrer un emplacement valide pour l'invite d'exécution EmployeeAddress afin d'extraire l'adresse complète du lieu.

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

    Une fois le lancement réussi, l'adresse complète d'Oracle et de San Jose doit être enregistrée en tant qu'adresse complète de l'employé 1.

    Message d'erreur de courriel d'employé non valide
  4. Enregistrer et fermer le formulaire. Naviguez jusqu'à Tâches (sous Application) pour ouvrir la console des tâches.
    5. Console de tâches
  5. Cliquez sur Groovy Add and Update Employee Address (Ajouter et mettre à jour l'adresse de l'employé) pour afficher les détails de l'emploi. Cliquez sur le statut Terminé pour voir les messages du journal imprimés par le script Groovy.
    6. Messages du journal de script Groovy

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 Oracle University pour voir les ressources de formation disponibles.

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