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.

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
• C’est le fichier Excel qui contiendra les données décrivant les équipements de notre environnement.
• Le script Excel d’automatisation à cette adresse : XXX
• C’est un script Excel permettant de formatter le fichier de descriptions d’équipements dans un format pouvant être importé dans le Back Office.

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.osts > 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.

Ajouts 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 en rouge représentent les données obligatoires à déclarer pour une variable, les autres en noir restent tout à fait 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.

Exemple : 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
• Proprieté: Température
• Référence Proprieté: 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
• Proprieté : Hygrométrie
• Référence Proprieté : 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 en rouge représentent les données obligatoires à déclarer pour un équipement, les autres en noir restent tout à fait 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.

Pour exécuter le script, assurez vous d’être dans l’onglet « Automatiser » et cliquer sur « Executer ».

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ée les variables correspondantes de cette instance en remplaçant les chaines de caractères {REFERENCE} par la valeur correspodante.

On se retrouve ainsi avec 4 handles au total.

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. Lors de la génration, le nom de la colonne sera utilisé en tant que clef de remplacement pour les chaines de caractères {NOM_COLONNE} présente dans la définition des variables dans la feuille des familles.

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écifier 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.

Il n’y a pas de limite au nombre de colonnes définies dans le fichier. Si une famille n’a pas besoin de cette valeur, il n’est pas nécessaire de remplir la cellule de cette colonne, cependant il est possible que plusieurs familles l’utilisent.