Module de script

Le module de script intègre les moteurs Octave et Python, permettant aux utilisateurs d’écrire et d’exécuter des calculs dans l’un ou l’autre langage au sein de Requirements & Systems Portal. Le module est conçu pour effectuer des calculs complexes qui ne sont pas possibles via le ValiEngine standard.

Si les utilisateurs souhaitent manipuler d’autres objets que des Valis numériques, ils doivent utiliser l’API Python de Requirements & Systems Portal. Exemples de cas d’usage :

• Créer une valeur et l’ajouter en masse à plusieurs Blocks

• Effectuer des modifications en masse des identifiants d’exigences

• Exécuter des simulations avec Python

• Convertir des unités de valeurs de puissance en kW.

• Exécuter un comportement de workflow personnalisé basé sur des déclencheurs automatisés

Flux du module de script

Pour utiliser le module, l’utilisateur crée un nouveau script, ajoute des entrées/sorties, écrit du code en .m ou .py, puis exécute le code pour obtenir le résultat souhaité.

Workflow du module de script.

Création d’un nouveau script

Pour créer un nouveau script, cliquez sur l’option « + Script » (1) dans les modules de script.

Une boîte de dialogue apparaît, vous permettant de saisir le nom du script, de sélectionner le moteur (Octave ou Python) et d’accéder à des options supplémentaires à utiliser/réutiliser à partir des modèles.

Option Créer un nouveau script

Une fois un nouveau script créé, les utilisateurs peuvent également créer des fichiers Text, JSON et YAML supplémentaires pour leurs scripts. Pour ajouter un nouveau fichier, cliquez sur l’option « +Add file » (1), ajoutez un nom et sélectionnez un type de fichier dans la boîte de dialogue. Cela ajoute un fichier au script.

Pour utiliser l’un des fichiers supplémentaires créés, les utilisateurs doivent inclure les deux lignes de code suivantes en haut du fichier main.py :

import site
site.addsitedir('script_code/')

Après ces deux lignes, tous les fichiers supplémentaires peuvent être appelés à l’aide de l’instruction standard import.

Gestion des secrets :

Afin de ne pas exposer l’utilisation des identifiants nécessaires lors de l’utilisation de scripts qui se connectent soit à notre API, soit à celle d’autres outils, il est possible de définir des variables secrètes personnelles qui peuvent être appelées à l’exécution du script, sans risquer de les exposer aux autres utilisateurs du déploiement en les stockant dans des fichiers de script.

Comment et où les ajouter

Les secrets peuvent être définis dans le panneau Settings, sous User Secrets. Ces secrets peuvent être réutilisés dans le script pour se connecter à Requirements & Systems Portal. Voici une courte vidéo montrant comment créer des secrets utilisateur.

Comme leur nom l’indique, ces secrets sont propres à chaque utilisateur et accessibles uniquement par ceux qui les ont définis.

Comment utiliser les secrets dans un script

En important le nom du secret depuis le module « .settings », les utilisateurs peuvent utiliser les secrets pour l’authentification dans les scripts.

from .settings import USERNAME, PASSWORD  #case sensitive, use the same word used in the user secrets.

LOGIN_DATA = {
    'domain': 'API_URL',
    'username': USERNAME,
    'password': PASSWORD
}

À l’exécution, les scripts récupéreront la valeur de ces variables à partir des secrets définis dans les paramètres utilisateur de l’utilisateur qui déclenche le script, et elles dépendent des autorisations de cet utilisateur. Les scripts ne doivent contenir aucune fonction de sortie de ces variables afin de ne pas exposer les secrets utilisateur.

Les scripts d’usage général configurés pour être déclenchés par des automatisations peuvent être mis en place avec une authentification par un utilisateur de niveau Admin, qui peut supprimer les autorisations de lecture pour tous les autres utilisateurs, gardant ainsi le script masqué.

Système de file d’attente

Grâce au système de file d’attente, les utilisateurs peuvent être certains que leurs scripts s’exécuteront toujours, en particulier si des automatisations prédéfinies déclenchent régulièrement des scripts de workflow personnalisés. Pour cela, accédez à la section « Runs ». Vous pouvez consulter soit toutes les exécutions de tous les scripts, soit les exécutions d’un script spécifique.

Toutes les exécutions de scripts seront désormais enregistrées sur le déploiement et pourront être consultées par script ou pour tous les scripts en sélectionnant l’option « All scripting » en haut de l’arborescence du module Script.

Vous pouvez arrêter un script en cours d’exécution en cliquant sur le bouton « Stop » dans le menu déroulant Actions.

Action d’arrêt pour un script.

Gestion des autorisations

Les scripts disposent de leurs propres autorisations, qui peuvent être gérées soit directement depuis le module de script, soit depuis le module Project sous « Permissions ».

Exécuter des scripts depuis un tableau de bord

Les utilisateurs peuvent également créer des tableaux de bord d’interaction personnalisés à l’aide de boutons « Run Script ». Ceux-ci sont similaires aux boutons Request précédemment disponibles, utilisés pour déclencher des appels REST, mais peuvent être configurés pour exécuter un ou plusieurs scripts d’une simple pression sur un bouton.

En utilisant l’API Python dans les scripts appelés, il est possible de configurer des tableaux de bord d’interaction personnalisés dans lesquels des éléments tels que des zones de texte standard peuvent être utilisés comme champs d’entrée et de sortie pour un script, lequel peut ensuite également affecter, directement ou indirectement, d’autres éléments affichés.

Pour cela, allez dans le module Project puis dans « Dashboards ». Ensuite, ouvrez votre tableau de bord personnalisé et cliquez sur l’icône Plus dans le coin inférieur droit. Sélectionnez ensuite l’option « Run script » dans le menu déroulant « Actions ».

Cela crée un bouton à partir duquel vous pouvez exécuter des scripts qui mettent à jour des blocs spécifiques de votre tableau de bord.

Un cas d’usage intéressant consiste à compter les exécutions de test réussies et échouées et à les afficher dans un bloc de texte sur le même tableau de bord.

Script & automatisations

Des automatisations prédéfinies peuvent déclencher des scripts. Par exemple, un calcul complexe peut être configuré pour s’exécuter automatiquement si ses entrées définies sont modifiées. De plus, en utilisant l’API Python de Requirements & Systems Portal, il est également possible de programmer des comportements complexes sur mesure afin de créer des workflows personnalisés.

Les automatisations ne se contentent pas de déclencher des scripts ; elles transmettent également les informations sur les objets qui les ont déclenchées afin que les scripts puissent agir directement sur ces objets. Les informations sur l’objet sont disponibles dans la variable dictionnaire « kwargs », sous la clé ‘triggered_objects’, comme dans l’exemple suivant :

object_data = kwargs['triggered_objects'][0]

Les automatisations exécuteront également des scripts si elles sont déclenchées par des utilisateurs qui n’ont pas l’autorisation de voir ces scripts, permettant ainsi la personnalisation des workflows et des calculs par des utilisateurs admin tout en limitant l’accès au code sous-jacent, comme des modèles mathématiques et physiques propriétaires.

Des exemples de scripts de workflow sont disponibles dans le dossier templates du dépôt public valifn.

Images valifn personnalisées

Les utilisateurs on-prem disposent en plus de la possibilité de personnaliser leur instance valifn pour exécuter n’importe quel package Python, à condition que le matériel de leur serveur puisse le supporter. Les utilisateurs on-prem auront également la possibilité de gérer quelle image valifn doit être utilisée au moment de l’exécution du script.

Comme indiqué, cette option est disponible sous forme de champ texte dans les General Settings de chaque script individuel.

Comment créer une image personnalisée

Des instructions supplémentaires sur la manière de configurer vos propres images valifn sont disponibles dans les pages de documentation du dépôt public :

• Usage · valispace/valifn-octave Wiki (github.com)

• Usage · valispace/valifn-python Wiki (github.com)

Exemples de scripts Python

Des exemples de scripts utilisables sont disponibles à la fois dans le projet d’exemple Valicopter 5000 d’un déploiement (nouveaux déploiements) et dans le dépôt public Github de ValiFn.

Ces exemples peuvent être déclenchés manuellement ou par des automatisations (exclusivement dans certains cas) et peuvent être utilisés tels quels ou modifiés par les utilisateurs pour réaliser tout type de comportement sur mesure.

Beaucoup de ces exemples ont été créés pour démontrer les possibilités du module de script et des automatisations dans la création de workflows automatisés sur mesure. Les utilisateurs sont encouragés à personnaliser tout script existant selon leurs besoins et à partager tout script à usage général ainsi que les améliorations apportées au dépôt public de ValiFn.

Avertissement de suspicion sur les enfants (Automation)

Justification

Ce script est déclenché par une automatisation qui doit être configurée pour se déclencher lors d’une modification d’une exigence existante, car le script agit sur les propriétés de l’exigence modifiée. Son action actuellement définie consiste à publier une discussion dans chacun de ses enfants (s’il y en a) avec un message personnalisé concernant le statut de modification de l’exigence parente.

Personnalisation suggérée

D’autres actions possibles pourraient être de créer une tâche ou d’ajouter l’exigence modifiée à une revue.

Actions actuelles

• Vérifie si l’exigence qui a déclenché l’automatisation prédéfinie a des enfants

• Si elle a des enfants, publie une discussion dans chaque exigence enfant indiquant que le parent a été mis à jour.

• La discussion inclut l’identité de l’utilisateur qui a modifié l’exigence, déclenchant ainsi l’automatisation.

Nouvelle tâche (Automation)

Justification

Lors de la création d’un nouveau Block, un prospect a demandé que des tâches soient automatiquement créées et attribuées à un utilisateur spécifique. Dans cet exemple, une automatisation prédéfinie déclenchée par la création d’un nouveau Block créera une nouvelle tâche et lui attribuera un utilisateur. Il avait été envisagé d’ajouter l’objet déclencheur comme entrée, mais ce développement n’a pas été finalisé.

Personnalisation suggérée

Utilisez le kwargs['triggered_objects'][0] pour extraire les informations de l’objet qui a déclenché l’automatisation et les ajouter au champ d’entrée de la tâche.

Actions actuelles

• Publie une nouvelle tâche assignée à un utilisateur spécifié.

Statistiques des exigences

Justification

Un exemple simple montrant comment créer un compteur plus personnalisé avec davantage de valeurs statistiques que celles fournies dans les blocs par défaut disponibles dans les documents Dashboards et Analysis. Il peut être exécuté manuellement ou configuré pour être lancé par une automatisation chaque fois qu’une exigence est créée, modifiée ou supprimée.

Personnalisations suggérées

1. Prenez les informations extraites sur les exigences et dérivez-en des statistiques plus complexes en les comparant à des valeurs précédemment mises à jour. Chaque valeur peut indiquer de combien elle a augmenté/diminué, exprimé en pourcentage.

2. Comparez les statistiques de déploiement en exécutant individuellement le script dans chaque projet et en ajoutant une instance spéciale qui récupère les statistiques de chaque projet pour les afficher dans un tableau de bord.

3. Définissez un avertissement personnalisé pour les administrateurs du projet si les statistiques montrent une baisse soudaine du nombre d’exigences, signalant un possible changement radical dans le projet.

Actions actuelles

• Construit les statistiques globales des exigences pour un seul projet sur le déploiement.

• Met à jour des Valis précréés avec les résultats.

Génération de spécifications

Justification

Un exemple de script qui démontre la puissance de l’API Python pour créer des rapports entièrement automatisés. Bien que le script principal soit également disponible sur la page de documentation des intégrations, cette version particulière a été adaptée pour être exécutée depuis le module de script du déploiement.

Il peut être déclenché par une automatisation ou manuellement.

Personnalisations suggérées

1. Créez un rapport complet en adaptant le processus actuel de récupération des exigences afin d’extraire les blocs et autres objets à renseigner dans le rapport.

2. Ajoutez d’autres champs personnalisables, qui peuvent être récupérés à partir de blocs de texte personnalisés d’un tableau de bord, depuis lesquels il peut également être déclenché.

3. Modifiez le fichier de sortie final pour obtenir un PDF au lieu d’un fichier Word modifiable.

Actions actuelles

• Prend un fichier Word comme modèle, à partir d’un déploiement donné, et renvoie en sortie des fichiers générés, en autant d’exemplaires qu’il y a de spécifications, placés dans la gestion des fichiers du déploiement (voir Export de spécifications basé sur un modèle Microsoft Word pour plus de détails).

Tableau de bord de test

Justification

Les compteurs de tableau de bord n’ont pas encore rattrapé le module Testing, et il n’existe pas encore de compteurs automatisés pour les tests. Ce script a été développé comme preuve de concept pour un compteur personnalisé qui n’a pas encore été implémenté. Il a été initialement conçu pour être exécuté via un déclenchement manuel depuis un bouton Run Script dans un tableau de bord.

Personnalisations suggérées

1. Étendez les statistiques de test qui sont renvoyées vers les tableaux de bord.

2. Si une exécution de test réussit, publiez le résultat dans une tâche connectée et changez son état en « Done ».

Actions actuelles

• Renvoie une chaîne, placée dans des blocs de texte prédéfinis du tableau de bord, contenant des statistiques calculées sur les exécutions de test.

• Il peut recevoir une entrée depuis une automatisation ou être déclenché manuellement.