Utilisation des APIs dans Planning Analytics

Le manque d’accessibilité par des outils tiers fut longtemps une complainte vis-à-vis de Planning Analytics.

Depuis quelques temps, IBM améliore l’interopérabilité en proposant un ensemble d’APIs permettant à tout un chacun d’interagir avec Planning Analytics, que ce soit pour :

• Piloter l’exploitation
• Extraire des données au travers de vues préexistantes
• Extraire des données au travers de MDX
• Gérer le référentiel des objets (cubes, vues, règles, processus, etc ….)
• D’intégrer des widget TM1 dans vos propres sites web

Ces APIs sont basées (entre autres) sur l’utilisation du protocole Odata (Open Data protocol)

Nous allons étudier, au travers d’exemples, quelques-unes de ces fonctionnalités. Nous utiliserons pour cela la base IBM SData. 

Préparation et prérequis

1/ Configurer la base TM1 pour accepter les API

Le paramètre HTTPPortNumber doit être renseigné (pour nous 12348) dans tm1s.cfg

2/ Préparer une vue d’extraction préconfigurée 

Cette vue ne comporte qu’une seule colonne qui est "year" et permet de vider toutes les valeurs des sales pour le réel et le world, pour quelques véhicules….

3/ Préparer un processus de test

Ce processus de test n’a d’autres intérêts que de ne rien faire pendant longtemps ;-)

4/ Préparer une belle requête MDX de lecture (extraction)

Utilisation de Curl

Nous aurions pu utiliser Podman, PowerShell, Python, pour tester nos différents appels, mais le plus simple reste encore l’utilisation de curl.exe, utilitaire que l’on peut copier sur son poste de travail (pas de setup)

(Dans notre article, curl.exe est déposé dans C:\Logiciels\CURL)

Nos appels seront de la forme :

Nous pouvons directement, dans notre navigateur, tester l’URL suivante :

https://MachineTM1:12348/api/v1/$metadata :

Quelques exemples des fonctionnalités offertes

Lister les cubes existant (les 5 premiers)

https://machinetm1:12348/api/v1/Cubes?$select=Name&$top=5

Nous sommes obligés de nous connecter avec le compte admin / apple

Différentes adaptations sont envisageables :

Un peu mieux formaté

La liste des cubes avec leurs dimensions

https ://machinetm1:12348/api/v1/Cubes?$select=Name&$expand=Dimensions($select=Name;$orderby=Name)&
$orderby=Name&$top=5&$format=application/json;odata.metadata=none

Nous allons maintenant utiliser CURL avec la commande suivante :

Le résultat... a le mérite d’exister !

En nous aidant de Powershell, nous pouvons transformer le Json en tableau :

( | de redirection vers la commande ConvertFrom-Json)

Le résultat est bien plus sympa :

Remarque :

Nous utilisons ici une authentification "basic" avec user et password.

Si nous étions dans une configuration avec une authentification déléguée à Cognos (CAM authentification), nous devrions au préalable nous authentifier auprès de Cognos et préserver le cookie obtenu pour nous connecter à TM1 et enfin pour .exécuter notre requête

• Obtention du CAM Passeport dans un fichier cam_cookies.txt

• Obtention d’un cookie de connexion à tm1

Listons enfin nos cubes :

Démarrer un processus / lister les processus vivants

Pour lister les processus en cours d’exécution :

Et, en le formatant grâce à PowerShell

Aucun processus ne s’exécute actuellement :-(

Démarrons alors l’exécution de notre processus de test :

Cette fois ci, nous avons bien notre processus qui tourne !

Remarque :

Pour exécuter un processus avec passage de paramètres : 

Créons notre processus recevant des paramètres

Exécutons-le avec comme paramètres : Next Decision et 2026

Résultat conforme aux attentes

Tuer un processus

Nous allons pouvoir tuer notre processus - qui dure vraiment trop longtemps ;-) - avec la commande suivante :

Et... victoire !

Remarque :

Bien-sûr l’utilitaire tm1top nous permettrait de faire la même chose, sauf lorsque l’authentification est déléguée à CAM (très embêtant, cette impossibilité de tuer un processus)

Grâce au paragraphe précédent, vous saurez écrire un script qui : 

• Reçoit les paramètres : user, password NumProcessus
• Se connecte à CAM puis TM1 puis tue le processus

Exporter une vue

Nous allons requêter pour extraire les données de notre fameuse vue :

Le résultat est là, mais comment l’exploiter ?

Une solution consiste à passer par PowerShell qui va utiliser :

• L’axe 0 : colonne "Year"
• L’axe 1 : les 4 dimensions en lignes (region, actvsbud, account1, model)
• Les 8 lignes de résultat

Toutes choses qu’un ETL professionnel saurait effectuer pour générer un ResultSet propre et exploitable. (à des fins de chargement dans un datawarehouse par exemple)

Power BI (via Power Query), Qlik Sense (Rest Connector en deux étapes), Microsoft Fabric (DataFlow Gen2, Data Pipelines, Notebook Spark) sauraient utiliser cette "extraction de vue" et transcrire ce resultset en quelque chose d’utilisable par chacun.

Exporter une requête MDX

Nous pouvons également construire une requête MDX (contenant des paramètres comme l’année, le mois, la phase Reel ou Budget... et appeler l’extraction de cette requête, comme si nous avions une vue idoine pour ce faire.

Pour écrire le MDX, inspirons-nous de l’éditeur de vue du plugin PAFE

Nous pourrons alors, à la demande, modifier les critères d’extraction, passant par exemple de "Actual" à "Budget".

Essayons d’abord avec Curl.exe : (il faut écrire la requête puis la passer à curl (avec le |)

Le résultat ne se fait pas attendre. Il faudra bien évidement le traduire en format tabulaire (mais ça, nous savons faire, en Powershell, Power BI, Qlik Sense, Fabric, …)

Conclusion

Planning Analytics commence à s’ouvrir aux outils tierces (non IBM) aux fins de pilotage, d’extraction, d’accès aux informations, voir de modélisation et design.

Il est maintenant parfaitement possible de concevoir :

• Des alimentations de datawarehouse, datalake
• Des reportings
• Des scripts d’exploitation
• De la modélisation (création de cubes, de règles, de processus, d’attributs, …)

Tout cela en utilisant les APIs Planning analytics, que notre implémentation soit en local ou dans le cloud (un peu plus complexe, mais opérationnel), sans avoir besoin d’installer les outils clients.

Documentation IBM : IBM Planning Analytics TM1 REST API

"Fonctionnalités" utilisées dans cet article :

• $metadata
• Cubes
• Threads
• Process() tm1.ExecuteWithReturn
• Threads() tm1.CancelOperation
• Cubes() Views() tm1.Execute
• ExecuteMDX

Pour aller plus loin

IBM fournit également d’autres jeux d’APIs, permettant d’interargir avec :

• PaaS (Planning Analytics as a Service)

Managing Planning Analytics as a Service Files using API requests

Introduction – API Reference

• Workspace 

Introduction – IBM Planning Analytics Workspace UI API

Introduction – API Reference

• Tm1Web 

API URL de TM1 Web - Documentation IBM

• Excel Pafe

IBM Planning Analytics for Microsoft Excel API - IBM Documentation

Retour page précédente Retour au Wiki

Vous souhaitez bénéficier d'experts, de développeurs, ou d'une formation sur TM1 / Planning Analytics ? Rendez-vous sur la page Contact !