Import d'équipements en masse à l'aide d'Office 365 et Excel

• Formation

Ce chapitre explique comment préparer un fichier Excel pour créer en masse des équipements dans Immersive. L’objectif est d’accélérer l’onboarding d’un site (ou d’un périmètre) en décrivant familles, variables et instances dans un tableur, puis en générant automatiquement les fichiers attendus par le Back Office (Enhancer). Suivez l’ordre : prérequis → préparation des données → déclaration des instances → exécution du script → colonnes personnalisées.

Rappel : principe du handle ou variable

Un handle (ou variable ), représente une propriété d’un équipement. Il constitue le lien entre une donnée issue d’un capteur ou une donnée statique et son affichage dans l’interface.

Pour définir un handle, il est indispensable de renseigner au moins quatre informations :

• Son nom : le texte affiché dans l’interface pour référencer la variable.
• Son type : par exemple un Boolean pour un contact sec, un Single pour une donnée numérique telle qu’un capteur de température, ou une String pour un état.
• Son path : la chaîne de connexion permettant de définir la manière dont la variable récupère sa valeur dans l’application (exemple : BuildingSensor://temp/Temperature).
• Sa catégorie (par défaut Information) :
  • Information : correspond à l’affichage par défaut d’une variable. Elle ne déclenche aucun comportement spécifique autre que l’affichage de sa valeur dans le bloc Information dédié.
  • Défaut : affichée dans le bloc dédié de l’équipement. Lorsque la variable prend les valeurs true, 1 ou ko, elle est affichée en rouge et l’équipement est considéré comme étant en défaut dans l’application.
  • Maintenance : affichée dans le bloc dédié de l’équipement. Lorsque la variable prend les valeurs true, 1 ou ko, elle est affichée en orange et l’équipement est considéré comme étant en maintenance dans l’application.
  • Connectivité : affichée dans le bloc dédié de l’équipement. Lorsque la variable prend les valeurs true, 1 ou ko, elle entraîne la déconnexion complète de l’équipement dans l’application.

Spécification par famille via le scripting Office et Excel 365

Bien qu’il soit possible de définir des handles différents pour des équipements au sein d’une même famille, il n’est pas rare de souhaiter formaliser un schéma de données identique pour des équipements appartenant à cette famille.

Dans ce tutoriel, nous allons voir comment, à l’aide d’un script Office (prérequis : accès à un abonnement Office), il est possible de simplifier la définition des familles d’équipements ainsi que la création de différentes instances d’équipements d’une même famille, tout en pouvant spécifier les particularités de chacune.

Prérequis : Importer dans Excel le script d’automatisation d’instanciation

Afin de pouvoir utiliser les fonctionnalités présentées dans la suite de ce tutoriel, il faut télécharger :

• Le fichier de déclaration Excel Immersive de base : Immersive-FichierExemple.xlsx
• Le script Excel d’automatisation

Une fois téléchargés, ouvrez le fichier Excel Immersive de base puis importez le script d’automatisation en cliquant sur Automatiser > Tous les scripts > Afficher plus de Scripts > Immersive – Instanciation > Ouvrir.

Le script est maintenant ajouté à votre classeur et pourra être exécuté plus tard.

Déclaration d’une nouvelle famille d’équipement

Une famille d’équipement représente un groupe d’équipements qui partagent une même structure ou comportement.

Par exemple, tous les capteurs de température d’un bâtiment avoir une variable de température et une autre d’hygrométrie tant que les portes ont une variable représentant si elles sont ouvertes ou fermées.

Exemple : Définition d’une nouvelle famille d’équipement

Dans notre exemple nous allons donc déclarer une nouvelle famille « Capteur de température », pour cela il suffit de dupliquer la feuille New Family de notre Excel Immersive de base et la renommer en « Capteur de température ».

Une fois dupliquée et renommée, notre feuille Excel expose les différentes colonnes permettant de déclarer de nouvelles variables associées aux différents capteurs.

Ajout de variables à une famille

Chaque ligne dans la feuille d’une famille représente une variable et chaque colonne représente une donnée associée à cette variable. (Les valeurs suffixées par * représentent les données obligatoires à déclarer pour une variable, les autres restent optionnelles).

• Propriété * : Le nom de la variable (exemple : Température)
• Référence propriété : Un code métier pour référencer la variable dans les scripts (exemple : TEMP)
• Identifiant d’interopérabilité : Un identifiant métier associé à la variable déclaré dans un autre environnement.
• Path / Chemin * : La chaine de connexion permettant de définir la façon dont la variable récupère sa valeur dans l’application (exemple : BuildingSensor://temp/Temperature). Voir le tutoriel associé au hub pour plus d’information. Pour définir une valeur d’une variable en dur sans être connecté au hub, il suffit de la préfixer par « Value:// » (exemple : Value://35)
• Type * : Le type de la variable, (exemple Single pour une variable de type numérique, String pour une chaine de caractère ou Boolean pour une variable à 2 états).
• Grandeur Physique : La grandeur physique remontée par cette variable. (exemple : Temperature)
• Unité : L’unité de mesure. (exemple : C°)
• Etat automatique : La catégorie de la variable. Voir le tutorial associé aux catégories de variables pour plus d’information.
• Options : Différentes options permettant d’affiner le comportement de cette variable dans l’interface. Notamment pour cacher la variable aux utilisateurs.
• Badge / Criticité : Un nom de badge. Voir le tutorial associé aux badges de criticité pour plus d’information.
• Priorité : Une priorité permettant de mettre en avant une variable par rapport aux autres.

Définition de 2 variables

Dans notre exemple, nous allons créer 2 variables Températures et Hygrométrie. Pour cela nous allons simplement ajouter 2 lignes à notre feuille Excel « Capteur de température » et remplir les colonnes obligatoires « Propriété », « Path/Chemin » et « Type », et remplir « Référence propriété » pour simplifier l’accès aux variables plus tard dans le Scripting :

• Définition d’une variable pour récupérer la température d’un Capteur de température
  • Propriété : Température
  • Référence Propriété : TEMP
  • Path : BuildingSensor://{REFERENCE}/Temperature
  • Type : Single
• Définition d’une variable pour récupérer l’hygrométrie d’un Capteur de température
  • Propriété : Hygrométrie
  • Référence Propriété : HYGRO
  • Path : BuildingSensor://{REFERENCE}/Humidity
  • Type : Single

Création d’instances d’équipements

Une instance d’équipement représente un équipement d’une famille, par exemple le capteur de température de la chambre ou le capteur de température du salon. On a ainsi 2 instances de la famille Capteur de température.

Pour spécifier de nouvelle instance, il suffit de se rendre dans la feuille Excel « Instances »

Chaque ligne dans la feuille d’instances représente une nouvelle instance d’équipement et chaque colonne représente une donnée associée à cet équipement. (Les valeurs suffixées par * représentent les données obligatoires à déclarer pour un équipement, les autres restent optionnelles).

• Scope * : Le scope correspond dans la majorité des cas au bâtiment ou carte dans lequel se trouve notre équipement (exemple : MyBuilding). Dans le cas où votre environnement possède plusieurs bâtiments, on définira un scope par bâtiment. Généralement, on crée un fichier Excel par Scope afin de bien séparer les équipements. Il est possible d’organiser les équipements sous forme de hiérarchie en séparant les sous-scopes avec le caractère >. Cette organisation est particulièrement utile si le bâtiment possède énormément d’équipements et que l’on souhaite mieux organiser la liste d’équipements dans son application. (exemple : MyBuilding > Main room).
• Famille * : La famille de l’équipement représente le type. Il correspond à un nom de famille que l’on a précédemment créé en tant que feuille Excel. (exemple : Capteur de température).
• Nom équipement * : Le nom de l’équipement qui sera affiché dans l’interface. (exemple : Capteur de la chambre).
• Reference équipement * : L’identifiant unique métier de notre équipement. Attention, celui-ci sera utilisé en tant que clef pour toute futur modification dans notre environnement. Il n’est pas possible de modifier cette référence dans le fichier Excel, si une référence est modifiée elle sera considérée comme un nouvel équipement. La chaine de caractère {REFERENCE} dans la définition d’une variable dans une famille sera automatiquement remplacée par la valeur de cette colonne.
• Description : Une description optionnelle qui apparaitra dans la fiche de l’équipement de l’application.
• Localisation : Une information optionnelle sur localisation de l’équipement. Elle apparaitra dans la fiche de l’équipement et est utilisée généralement pour aider à placer l’équipement lors de la création de la carte.
• Identifiant d’interopérabilité : Un identifiant métier associé à l’équipement déclaré dans un autre environnement.
• XXX : Il est possible d’ajouter autant de colonnes supplémentaires pour décrire les instances. Ces colonnes pourront être utilisées pour remplacer les chaines de caractère {XXX} dans la définition d’une variable.

Exemple : Création de 2 instances d’équipements

Dans notre exemple, nous allons créer 2 instances de Capteurs de températures. Pour cela nous allons simplement ajouter 2 lignes à notre feuille Excel Instances et remplir les colonnes obligatoires Scope, Famille, Nom équipement et Reference équipement.

• Définition d’une instance d’un capteur de température pour la chambre
  • Scope : MyBuilding
  • Famille : Capteur de température
  • Nom équipement : Température chambre
  • Référence équipement : TEMP_01
• Définition d’une instance d’un capteur de température pour le salon
  • Scope : MyBuilding
  • Famille : Capteur de température
  • Nom équipement : Température salon
  • Référence équipement : TEMP_02

Exécution du script

Une fois les familles et les instances définies, il suffit d’exécuter le script d’automatisation, qui va merger les définitions d’instances avec les définitions des familles et créer une liste de « handles » qui pourront être importés dans le Back office d’Immersive : Enhancer.

Le résultat de la génération se trouve dans l’onglet « Data ». Le script a automatiquement parcouru la liste des instances, retrouvé la famille associée. Pour chaque instance il a parcouru la liste des variables définies dans la feuille de la famille et a créé les variables correspondantes de cette instance en remplaçant les chaines de caractères {REFERENCE} par la valeur correspondante.

On se retrouve ainsi avec 4 handles au total.

Une fois cette étape effectuée, il est maintenance possible d’importer les équipements depuis le back office immersive comme expliqué dans ce tutoriel : lien vers import excel

Spécification de colonne supplémentaires

Il est assez fréquent de devoir paramétrer des valeurs spécifiques des instances. Afin de répondre à ce besoin, il suffit de rajouter une colonne dans la feuille d’instances.

Imaginons que l’on souhaite associer un numéro de série à chaque instance, et que ce numéro de série soit visible en tant que variable d’un équipement.

Nous rajoutons ainsi la colonne SERIAL dans la feuille d’instances, et remplissons les valeurs.

Dans la feuille de la famille Capteur de température, nous rajoutons une ligne pour définir une nouvelle variable. Dans la colonne du Path, nous spécifions la chaine de caractère Value://{SERIAL}.

Une fois le script exécuté, l’export a bien rajouté 2 variables (1 par instance) et a remplacé la chaine {SERIAL} par la valeur correspondante à chaque instance.