Modélisation UML & SysML

Le déploiement d’un référentiel de modélisation conduit souvent à des demandes utilisateurs pour des fonctionnalités spécifiques liées à leur utilisation d’Enterprise Architect (EA). Bien que EA soit un outil très riche et puissant, il fournit une API pour étendre ses capacités. 

L’API peut être exploitée de différentes manières :

• Scripts EA : gérés et stockés dans le référentiel (projet EA), les scripts peuvent être exécutés par les utilisateurs disposant de la permission nécessaire. Cette approche permet s'affranchir d'installation sur les postes clients. EA peut être utilisé comme environnement de développement (IDE) pour développer, tester et exécuter les scripts en VBScript, JScript ou JavaScript.
  • Ce sujet a été abordé lors de ma présentation à l'EA User Group 2018.
• Add-ins EA : un add-in est une application à installer sur chaque poste client pour être disponible sous Enterprise Architect. Un add-in peut être implémenté avec la plupart des langages de programmation (C#, Java, C++...).  Par rapport aux scripts, les add-ins permettent de réaliser des interfaces utilisateur avancées et de gérer les "broadcast events EA" pour déclencher une fonction lors de la création par exemple d’un élément ou d’un connecteur.
  • eaUtils est un exemple d'add-in disponible gratuitement.
• Solutions tierces : l'API EA peut être intégrée avec des outils externes tels qu'un script PowerShell ou un outil en ligne de commande développé en C#, compatibles avec le planificateur de tâches pour la mise à jour régulière du référentiel si besoin. Exemple : mise à jour des applications à partir de l'extraction Excel hebdomadaire de la CMDB. 
• Model-based add-ins : gérés dans le référentiel, aucune installation n'est nécessaire sur les postes clients. Développés en JavaScript, l'avantage des add-ins "model-based" est leur support des broadcast events EA.
  • Ce sujet est abordé dans cet article.

Le tableau suivant est une comparaison non-exhaustive des principales différences entre ces alternatives :

Introduction

Cet article est un retour d'expérience inspiré d'un model-based add-in réalisé pour un cas concret afin d'identifier les avantages et contraintes en termes d’implémentation et d'usage.

Contexte initial : une équipe d’architectes techniques en charge depuis peu d'un référentiel EA centralisé (Architecture d'Enterprise avec un MDG basé sur ArchiMate) a exprimé le besoin d'une solution pour limiter le risque de créer des connecteurs en doublon. Lors de la création d’un connecteur, un avertissement doit être affiché lorsque des connecteurs du même type et stéréotype existent déjà entre ces deux éléments. La création de plusieurs connecteurs du même type entre deux éléments étant valide dans certains cas (exemple : flux entre applications), un utilisateur doit pouvoir choisir d’annuler ou de confirmer ce nouveau connecteur. Le scénario nominal identifié est la détection d'un doublon lorsqu'une relation a été masquée dans le diagramme ; l'utilisateur doit pouvoir annuler la création du connecteur et choisir d'afficher la relation masquée. Les contraintes étant la gestion des broadcast events et l'absence dinstallation sur les postes clients, unmodel-based add-in a été identifiié comme solution possible.

Les fonctionnalités du model-based add-in ModelHelper sont les suivantes :

• Un contrôle est déclenché lors de la création d'un connecteur entre deux éléments, sans aucune restriction sur le type et stéréotype.
  • Dans une version améliorée, l'utilisateur pourrait définir des règles avec le type et stéréotype du connecteur, élément source, élément cible, ainsi que les multiplicités et rôles (optionnels). 
• Si l'utilisateur décide d'annuler la création du connecteur, l'add-in doit rechercher et proposer d'afficher les connecteurs masqués dans le diagramme.

Environnement technique : Enterprise Architect 15.2 build 1560.

Implémentation

Création de la classe pour le model-based add-in

La première étape consiste à créer le package dédié au nouvel add-in. Si la gestion des utilisateurs est activée (EA security), un verrou est recommandé pour limiter l'accès en écriture aux administrateurs.

Une fois le package cible sélectionné, utiliser la fonction "new model from pattern" du Browser, sélectionner Management > Model Add-ins > Broadcast Types, et cliquer sur Create Patterns.

Cette étape permet de générer tous les événements "broadcast events" nécessaires pour l'add-in.

Créer une classe UML et modifier son stéréotype avec Model Add-Ins::JavascriptAddin. Elle sera reconnue par EA comme add-in du modèle.

Les évènements suivants doivent être déclarés comme réceptions dans la classe : EA_Connect, EA_GetMenuItems, EA_MenuClick :

• Ouvrir la vue Features > Receptions.
• Créer une nouvelle réception et sélectionner l'élément sous Broadcast Types > Add-in Events, par exemple EA_Connect.
• Répéter ces étapes pour obtenir le résultat suivant.

L'évènement EA_OnPreNewConnector doit être ajouté pour déclencher l'exécution d'une fonction de l'add-in lorsqu'un nouveau connecteur est sur le point d'être créé dans un diagramme. Si la fonction renvoie la valeur Vrai, le connecteur est créé, sinon il est supprimé (valeur renvoyée : Faux). Créer une réception dans la classe de l'add-in, et sélectionner Broadcast Events > Pre New-Object Events > EA_OnPreNewConnector.

Des fonctions peuvent être créées dans la liste des opérations. ProcessHiddenConnectors a été créée avec 2 paramètres : connectorsList et diagramID. Cette fonction est exécutée à partir de la réception EA_OnPreNewConnector afin de vérifier s'il existe des connecteurs masqués dans ce diagramme, et dans ce cas propose à l'utilisateur de les rendre visibles. Exemple de code pour exécuter cette opération :

this.ProcessHiddenConnectors(connectorList, Info.Get("DiagramID").Value);

La variable globale AddinName a été définie en tant que nouvel attribut de la classe avec comme valeur initiale "ModelHelper". Cette variable est accessible avec la déclaration this.AddinName.

Librairies JavaScript

Pour éviter de définir toutes les fonctions dans la classe du model-based add-in et permettre leur réutilisation, il est possible d'utiliser des classes dédiées, accessibles par l'add-in grâce à un lien de dépendance :

• xmlHelper.GetNodesfromQueryResult(queryres, colname)
  • Entrées
    • queryres: résultat de la fonction Repository.SQLQuery (API EA)
    • colname : nom de la colonne de la requête, ex : ea_guid
  • Sortie : liste des XML Nodes (résultats de la requête exécutée)
• JSdialog.MsgBox(prompt, title, style)
  • Problématique : la fonction Session.Prompt (API EA) ne fonctionnait pas correctement avec l'add-in ModelHelper. Cette fonction permet d'afficher une fenêtre pour demander à l'utilisateur de conserver ou supprimer le connecteur, de choisir d'afficher les connecteurs masqués. Cette fonction simple a donc été mise en place (solution de contournement).
  • Entrées
    • prompt : texte affiché pour l'utilisateur
    • title : titre de la fenêtre (this.AddinName = ModelHelper)
    • style : l'une des valeurs suivantes.
      • 0 -> OK 
      • 1 -> OK/Cancel
      • 3 -> Yes/No/Cancel
      • 4 -> Yes/No
  • Retour : valeur correspondant au bouton utilisé
    • 1 -> OK
    • 2 -> Cancel
    • 6 -> Yes
    • 7 -> No
  • Code :

    style += 4096; // active window
    var WSH = new COMObject("WScript.Shell");
    return WSH.Popup(prompt, 0, title, style);

Exemples de code pour utiliser cette fonction :

    var dialogHelper = new JSdialog();

       --> instanciation de la classe JSDialog.

    dialogHelper.MsgBox("This Model Addin displays a popup when creating a connector between 2 elements when at least one matching connector (type, stereotype) already exists.\n\nThe user is prompted to confirm the new connector or cancel it. If the connector is cancelled, the user can choose to show any hidden connector(s) on the diagram.\n\nAuthor: Guillaume FINANCE (guillaume...umlchannel.com)", this.AddinName, 0);

       --> affiche une popup avec le message et le bouton OK (style = 0).

    if (dialogHelper.MsgBox(message + " found with the same type/stereotype.\nClick YES to confirm creating the new connector,\nNO to cancel/delete this connector.", this.AddinName, 4) == 6);

       --> affiche une popup avec le message et les boutons Yes et No (style = 4), et test si l'utilisateur a répondu Yes (6).

Finaliser le code de l'add-in

Le code source (JavaScript) d'une classe (model-based add-in ou librairie) est accessible avec le menu Develop > Behavior > Edit Internal Code (alternative : clic droit sur la classe > Features > Edit Internal Code).

L'arborescence permet d'accéder au code de chaque opération ou réception. Voici un exemple de code pour créer le menu dans EA (About) en utilisant la variable globale AddinName.

Menu obtenu :

Démonstration

La fenêtre Manage Add-Ins affiche les add-ins EA installés ainsi que les model-based add-ins. Identifié comme add-in optionnel, chaque utilisateur peut faire le choix de l'activer ou le désactiver :

Le diagramme ArchiMate suivant est initialisé pour tester l'add-in ModelHelper :

La création d'un lien de composition entre ces applications déclenche l'affichage de la popup suivante :

La création du connecteur est confirmée (choix : Oui).

Les connecteurs sont masqués.

La tentative de créer un nouveau lien de composition déclenche l'affichage de la popup suivante :

L'annulation du connecteur (choix : Non) et la détection de connecteurs masqués donne lieu à la fenêtre suivante :

Résultat (choix : Oui = afficher les connecteurs masqués).

Résultats

Problématique traitée : en contournement d'une anomalie avec la fonction Session.Prompt utilisée par le model-based add-in, une fonction JavaScript générique a été créée pour gérer les fenêtres popup avec plusieurs choix possibles de boutons (Ok, Yes/No, etc.).

Inconvénients

• Le code source étant accessible pour chaque opération de la classe, il n’y a pas de vue globale ce qui n'est pas idéal.
• Il n'est pas possible de naviguer de l'appel d'une fonction vers sa définition, contrairement aux scripts ("Search in Scripts" sur un texte sélectionné).
• Tout changement du code source nécessite de recharger le projet EA avant de tester à nouveau l'add-in.
• Le mode Debug avec des points d'arrêts ne semble pas être disponible.

Avantages

• Gestion des EA broadcast events.
  
  • Remarque : il est recommandé d'informer les utilisateurs de l'existence de ces tâches automatiquement déclenchées selon des règles définies. Cela est important pour éviter des erreurs ou le sentiment d'anomalies dans l'outil liées à des comportements inattendus.
• Chaque utilisateur peut activer ou désactiver l'add-in.
• Dans un projet EA centralisé, un model-based add-in peut être associé avec un groupe d'utilisateurs pour restreindre son accès.
• Comme avec les scripts EA, le code est maintenu dans le référentiel et mis à jour de façon transparente pour tous les utilisateurs (évolutions, corrections...).
• Des fonctions JavaScript peuvent être définies au travers de classes utilisées comme librairies.
• Une fois qu'il fonctionne, un model-based addin est très utile !