Créer des scripts Python et HCL dans Robots

L'application Robots fournit des scripts natifs, basés sur le cloud, que vous pouvez utiliser pour l'analyse des données ou pour automatiser des parties du flux de travail Diligent One de votre organisation. La rédaction de scripts dans Robots associe toute la puissance de Python à toutes ses bibliothèques prises en charge avec HighBond Command Language (HCL), notre bibliothèque Python personnalisée pour les analyses de données axées sur le domaine et l'automatisation Diligent One.

Robots continue de prendre en charge l'analyse et l'automatisation des données à l'aide d'ACLScript et de scripts chargés depuis Analytics. Vous pouvez ainsi profiter des investissements existants dans ACL (Audit Command Language) et de toutes les possibilités offertes par Python, langage de programmation standard dans le secteur, et HCL.

Trois types de robots

L'application Robots contient trois types de robots. Bien que similaires à bien des égards, les différents types de robots prennent en charge différents scénarios de script :

• Robot ACL Prend en charge l'analyse des données à grande échelle grâce à des scripts que vous téléchargez à partir d'Analytics et grâce à des tâches planifiées. Les scripts peuvent s'exécuter dans le Cloud ou sur site.

• Robot HighBond Prend en charge l'analyse de données à grande échelle avec des scripts Python/HCL créés directement dans le robot et des tâches planifiées. Les scripts peuvent s'exécuter dans le cloud uniquement.

• Robot Flux de travail prend en charge les analyses de données légères ou permet d'automatiser certaines parties de votre flux de travail Diligent One à l'aide de scripts Python/HCL créés directement dans le robot et de tâches planifiées ou basées sur des événements. Les scripts peuvent s'exécuter dans le cloud uniquement.

  Remarque

  Pour accéder aux robots de flux de travail, vous devez avoir le type d'utilisateur administrateur système avec abonnement professionnel.

  En effet, un admin système disposant de l'abonnement Professionnel sera en mesure de configurer des tâches dans les robots de flux de travail déclenchés par les événements Diligent One. Cette fonctionnalité est en cours de développement, elle n'est pas encore disponible.

Comparaison des types de robots

Les trois types de robots sont destinés à des fins différentes et sont fonctionnellement distincts les uns des autres. Vous ne pouvez pas mélanger ACLScript et Python/HCL dans un seul robot.

Caractéristique du robot	Robot ACL	Robot HighBond	Robot de flux de travail
Objectif visé	Analyse et automatisation des données		Automatisation de la plateforme Diligent One
Langue prise en charge	ACLScript	Python Pandas, NumPy, Requests et autres bibliothèques Python standard Bibliothèque Python HCL personnalisée (HighBond Command Language)
Emplacement de création du script	Analytics	Robots
Emplacement d'exécution du script	cloud sur site ;	cloud
Options d'exécution d'une tâche	planifiées exécution ad-hoc (manuelle)		déclenchée par un événement Diligent One planifiées exécution ad-hoc (manuelle)
Durée d'exécution maximale de la tâche	Agent Robots basé dans le cloud : 60 minutes Agent Robots sur site : contrôlé par un réseau client	Aucune limite Remarque Une limite de 12 heures est prévue, mais pas encore mise en œuvre. Si vous devez arrêter une tâche qui s'exécute depuis trop longtemps, vous pouvez cliquer sur Annuler l'exécution de la tâche dans l'onglet Exécution de tâche.	15 minutes
Nombre maximal de tâches qui s'exécutent simultanément	5	5	50
Autorisations requises	être un collaborateur pour le robot degré d'accès contrôlé par le rôle de robot du collaborateur (propriétaire, éditeur, examinateur)		Type d'utilisateur administrateur système avec un abonnement professionnel

Éditeur de scripts Robots

Les robots HighBond et les robots Workflow contiennent un éditeur de script intégré permettant de créer des scripts Python/HCL et de les exécuter de manière interactive (manuelle). L'éditeur de script est modélisé sur l'application Jupyter Notebook, un environnement de développement populaire dans la communauté de la science des données. L'éditeur de script utilise un Approche de la création de scripts basée sur les cellules.

Numéro	Description
1	Numéro de version et message de transmission du script ouvert dans l'éditeur de script
2	Nom du robot contenant le script
3	Commandes des cellules : Exécuter la cellule Ajouter une nouvelle cellule ci-dessus (non affiché) Ajouter une nouvelle cellule ci-dessous (non affiché) Exécuter la cellule en cours et toutes les cellules ci-dessus (non affiché) Exécuter la cellule en cours et toutes les cellules ci-dessous (non affiché) Supprimer la cellule (non affiché)
4	Indicateurs de séquence affichant l'ordre dans lequel chaque cellule a été exécutée. Pour plus d'informations, consultez la section Caractéristiques clés de la création de scripts à partir de cellules.
5	Cellules pour l'écriture de code de script Pour plus d'informations, consultez la section Approche de la création de scripts basée sur les cellules.
6	Sortie affichée d'une cellule
7	Barre d'outils supérieure : Ajouter une nouvelle cellule sous la cellule sélectionnée Déplacer la cellule sélectionnée vers le haut Déplacer la cellule sélectionnée vers le bas Exécuter la cellule sélectionnée Exécuter toutes les cellules en séquence de haut en bas Arrêter l'exécution du script Supprimer la cellule sélectionnée Retourner le script à la version précédemment validée
8	Bouton Variables : ouvre la fenêtre Variables pour définir des variables HCL Pour plus d'informations, consultez la section Utiliser des variables dans un script Python/HCL.
9	Bouton Fichiers de la session, avec le nombre de fichiers en cours : ouvre ou ferme le panneau Fichiers de la session
10	Bouton Enregistrer et transmettre : enregistre le script et le transmet en tant que nouvelle version

Approche de la création de scripts basée sur les cellules

La fonctionnalité la plus évidente de l'éditeur de script est la capacité d'utiliser plusieurs cellules pour contenir les blocs de code individuels qui composent un seul script. Si vous n'êtes pas familiarisé à Jupyter Notebook, l'approche de la création de scripts basée sur les cellules peut sembler compliquée au premier abord. En fait, il est facile à utiliser et il présente des avantages que vous apprécierez rapidement.

Caractéristiques clés de la création de scripts à partir de cellules

• Plusieurs cellules sont facultatives Vous n'avez pas l'obligation d'utiliser plusieurs cellules si vous ne le souhaitez pas. Vous pouvez créer et exécuter un script entier à l'aide d'une seule cellule.

• Divisions logiques Les cellules vous permettent de diviser un script en blocs logiques de votre choix et d'exécuter manuellement les blocs individuellement, dans n'importe quel ordre ou en tant que séquence entière.

  Par exemple, une disposition de base de quatre cellules pour un script pourrait être :

  • première cellule importer des bibliothèques Python

  • deuxième cellule importer des données

  • troisième cellule effectuer des analyses sur les données

  • quatrième cellule sortir les résultats de l'analyse

• Avantage des cellules L'utilisation de cellules pour le développement de scripts présente les avantages suivants :

  • Vous pouvez travailler sur des cellules individuelles de manière isolée, les tester et les améliorer, tout en ignorant temporairement la logique de script contenue dans d'autres cellules.

  • Après avoir exécuté une fois les cellules d'importation initiales, il n'est pas nécessaire de continuer à les exécuter pendant que vous développez et testez à plusieurs reprises les cellules suivantes.

  • Vous pouvez utiliser les cellules pour imposer un ordre visuel à vos scripts, en rendant la relation entre les différents blocs logiques plus facile à voir et à comprendre pour vous, ou pour quelqu'un d'autre.

• Indicateur de séquence À côté de chaque cellule se trouve un indicateur numérique qui affiche l'ordre dans lequel la cellule a été exécutée pendant une session de script. Par exemple : [7].

  Lorsque vous exécutez une cellule, le code s'incrémente, en tenant compte de toutes les autres cellules que vous avez exécutées entre-temps. Ainsi, par exemple, un indicateur pourrait passer de [7] à [10] si vous avez exécuté deux autres cellules entre-temps ou une autre cellule deux fois.

• Mémoire de la session et valeurs stockées Les cadres de données et les valeurs des variables conservés en mémoire pendant une session de script sont mis à jour en fonction de l'ordre dans lequel vous exécutez les cellules.

  En général, vous structurez les cellules pour qu'elles s'exécutent séquentiellement de haut en bas pendant l'exécution programmée et sans assistance du script. Certains cadres de données ou certaines valeurs de variables peuvent être mis à jour progressivement sur la base d'une logique de script. Si vous exécutez manuellement des cellules dans le désordre, l'état actuel d'un cadre de données ou d'une valeur de variable peut ne pas correspondre à ce que vous supposez et une erreur ou un résultat inexact peut se produire. Pour rétablir le cadre de données ou la valeur de la variable à son état initial, il suffit de ré-exécuter toutes les cellules faisant référence au cadre de données ou à la variable dans l'ordre prévu.

• Affichage d'une sortie de cellule Par défaut, l'exécution d'une cellule affiche uniquement la sortie de la dernière expression de la cellule. Si vous voulez voir le résultat de plusieurs expressions dans une cellule, vous pouvez placer les expressions dans des cellules séparées. Cependant, une approche plus pratique consiste à définir une option de configuration dans l'éditeur de script.

  • Configurer les cellules pour afficher la sortie de toutes les expressions :

    from IPython.core.interactiveshell import InteractiveShell
    InteractiveShell.ast_node_interactivity = "all"

  • Réinitialiser les cellules pour afficher le résultat de la dernière expression seulement :

    from IPython.core.interactiveshell import InteractiveShell
    InteractiveShell.ast_node_interactivity = "last_expr"

  Astuce

  Vous pouvez utiliser le paramètre de configuration pour passer d'un mode à l'autre selon vos besoins. Pour des options de configuration supplémentaires pour la sortie des cellules, consultez la documentation Jupyter ou IPython en ligne.

Raccourcis clavier dans l'éditeur de script Robots

Les raccourcis clavier dans l'éditeur de script vous permettent de développer un script de manière pratique et rapide. Dans l'éditeur de script, affichez la liste des raccourcis disponibles de l'une des façons suivantes :

• Appuyez sur Ctrl+/

• Cliquez sur l'icône Raccourci clavier dans la barre de titre

Les raccourcis disponibles sont indiqués ci-dessous.

Raccourci clavier	Action
Ctrl + Maj + Entrée	Exécuter la cellule sélectionnée
Ctrl + Maj + M	Exécuter toutes les cellules de manière séquentielle
Ctrl + Maj + Y	Exécuter la cellule sélectionnée et toutes les cellules au-dessus
Ctrl + Maj + U	Exécuter la cellule sélectionnée et toutes les cellules en dessous
Ctrl + Maj + I	Arrêter l'exécution du script
Ctrl + Maj + K Ctrl + Maj + Flèche vers le haut	Sélectionner la cellule au-dessus
Ctrl + Maj + J Ctrl + Maj + Flèche vers le bas	Sélectionner la cellule en dessous
Ctrl + Maj + H Ctrl + Maj + Orig.	Sélectionner la première cellule
Ctrl + Maj + L Ctrl + Maj + Fin	Sélectionner la dernière cellule
Ctrl + Maj + A	Ajouter une cellule au-dessus
Ctrl + Maj + B	Ajouter une cellule en dessous
Ctrl + Maj + D	Supprimer la cellule sélectionnée
Ctrl + Maj + Z	Déplacer la cellule vers le haut
Ctrl + Maj + X	Déplacer la cellule vers le bas

Fonctionnalités Jupyter Notebook non incluses dans l'éditeur de script Robots

Comme indiqué ci-dessus, l'éditeur de script Robots est modélisé sur l'application Jupyter Notebook. Ces fonctionnalités de Jupyter ne sont pas incluses dans l'éditeur de script, bien que certaines d'entre elles puissent l'être au fil du temps, à mesure que le produit continue d'évoluer :

• Opérations au niveau de la cellule :

  • annuler/répéter les opérations de la cellule

  • copier/coller des cellules

  • fractionner/fusionner des cellules

• Cellules Markdown (pour du contenu texte)

Enregistrer une sortie de script dans un fichier journal

Quand vous exécutez un script Python/HCL à l'aide d'une tâche de robot, vous pouvez enregistrer la sortie de script dans le fichier journal qui accompagne chaque exécution de tâche. Le journal est un fichier JSON qui porte le même nom que la tâche (nom_tâche.json).

Pour activer cette option, sélectionnez Enregistrer la sortie du script dans le fichier journal d'exécution de la tâche quand vous enregistrez et transmettez une version d'un script. L'option peut être configurée séparément pour chaque version d'un script. Si vous souhaitez enregistrer la sortie du script, veillez donc bien à sélectionner l'option pour la version de script spécifique que la tâche exécute.

Une sortie de script fait référence à tout ce qui se trouve dans le flux stdout produit par un script. Généralement, stdout correspond à tout ce que le script imprime ou affiche à l'écran quand vous exécutez un script de manière interactive. Sélectionner Enregistrer la sortie du script dans le fichier journal d'exécution de la tâche revient donc à capturer de manière permanente tout ce qui s'affiche à l'écran. Il peut être utile d'examiner cette sortie de script quand vous développez et dépannez des scripts.

Informations supplémentaires :

• L'option ne s'applique qu'aux tâches Même si vous sélectionnez Enregistrer la sortie du script dans le fichier journal d'exécution de la tâche dans l'éditeur de script Robots, l'option s'applique uniquement aux scripts exécutés par une tâche de robot. L'option n'a aucun effet quand vous exécutez un script de manière interactive dans l'éditeur de script.

• Messages d'erreur dans le fichier journal d'exécution de la tâche Les messages d'erreur Python (le flux stderr) sont toujours inclus dans le fichier journal d'exécution de la tâche, quelle que soit la configuration de l'option Enregistrer la sortie du script dans le fichier journal d'exécution de la tâche.

• Accéder au fichier journal d'exécution de la tâche Un fichier journal d'exécution de la tâche est créé pour chaque exécution de tâche dans l'onglet Exécutions de tâche. Sélectionnez une exécution de tâche. Le fichier journal s'affiche dans la section Sortie du panneau latéral Task run details (Détails d'exécution de la tâche). Vous pouvez télécharger le fichier sur votre ordinateur pour l'examiner.

Faire la transition d'ACLScript à Python et HCL

Python est un langage de programmation polyvalent et est nettement plus complexe qu'ACLScript, qui est un langage de script relativement simple, conçu à l'origine pour le domaine des outils d'analyse d'audit.

Notre intention est qu'au fil du temps, HCL reproduise un grand nombre des commandes et fonctions disponibles dans ACLScript. Pour commencer à utiliser HCL, notre bibliothèque Python personnalisée, vous devez avoir au moins des connaissances de base en Python. Le conseil pour ceux qui cherchent à faire la transition d'ACLScript à Python/HCL est de suivre un bon cours d'introduction à Python.

Conventions de codage Python

Vous devrez vous habituer à certaines conventions de codage qui ne sont pas appliquées dans ACLScript mais qui le sont dans Python et HCL :

• Respect de la casse La syntaxe Python et HCL est sensible à la casse, alors que la syntaxe ACLScript ne l'est pas.

  Dans Python :

  • print("Hello World!") fonctionne

  • PRINT("Hello World!") renvoie une erreur

• Aucune abréviation La fonction, la méthode et les noms des paramètres Python et HCL doivent être épelés complètement. A la différence d'ACLScript, les abréviations ne sont pas prises en charge.

• Le retrait compte Python utilise le retrait pour mettre en place des structures de contrôle comme les instructions conditionnelles et les boucles. Un retrait incorrect entraîne des erreurs. ACLScript ignore le retrait.

Bibliothèques Python externes

Python prend en charge un grand nombre de bibliothèques ou packages externes que vous pouvez installer pour étendre les fonctionnalités de l'installation de Core Python et de la bibliothèque standard Python. Une bibliothèque externe Python est une collection de modules de code lié conçus pour effectuer des actions spécifiques dépassant ce qu'il est possible de faire avec Core Python et la bibliothèque standard. Par ailleurs, cela permet d'effectuer certaines actions plus rapidement et plus aisément que dans Core Python.

Bibliothèques externes incluses dans Python Diligent One

L'installation Diligent One de Python inclut certaines bibliothèques externes par défaut ; vous ne devez donc pas les installer en tant que telles. À l'exception de la propre bibliothèque Python HCL de Diligent, vous devez importer les bibliothèques pré-installées afin de les utiliser dans la logique de script Python/HCL qui s'ensuivra.

Bibliothèques externes pré-installées dans l'environnement Python Diligent One :

Bibliothèque	Description	Instructions IMPORT de Python
HCL	La bibliothèque HCL, ou HighBond Command Language (HCL), est la bibliothèque Python personnalisée de Diligent pour les analyses de données axées sur le domaine et pour l'automatisation de Diligent One.	non requis
Pandas	La bibliothèque Pandas offre un ensemble solide d'outils pour la manipulation et l'analyse des données dans Python, comme des cadres de données sous forme de tableaux de données en deux dimensions ressemblant à des feuilles de calcul ou à des tables.	import pandas ou import pandas as pd (peut éventuellement créer un alias au format abrégé pour le nom de la bibliothèque)
NumPy	La bibliothèque NumPy offre des fonctionnalités de calcul scientifiques rapides et puissants dans Python : des opérations d'algèbre et de statistiques de base aux opérations de mathématiques avancées, en passant par l'élaboration et la réalisation de calculs sur des tableaux multidimensionnels.	import numpy ou import numpy as np (peut éventuellement créer un alias au format abrégé pour le nom de la bibliothèque)
Requêtes	La bibliothèque Requests fournit une syntaxe légère pour créer des requêtes HTTP dans Python et interagir avec des API Web.	import requests ou import requests as req (peut éventuellement créer un alias au format abrégé pour le nom de la bibliothèque)
Cryptography	La bibliothèque Cryptography prend en charge l'incorporation d'algorithmes cryptographiques dans Python.	import cryptography ou import cryptography as crypt (peut éventuellement créer un alias au format abrégé pour le nom de la bibliothèque)

Installation de bibliothèques externes supplémentaires

Les robots HighBond prennent en charge l'installation de bibliothèques externes supplémentaires en plus de celles pré-installées avec l'environnement Python Diligent One. Pour installer une bibliothèque supplémentaire, utilisez pip , un outil destiné au téléchargement et à l'installation de packages Python. Par défaut, pip télécharge les packages du Python Package Index (PyPI), un référentiel open source de logiciels Python. Vous pouvez aussi utiliser pip pour installer des packages d'autres sources.

Par exemple, pour installer pyexcel , une bibliothèque Python permettant d'utiliser des fichiers et données Excel, utilisez cette commande dans l'éditeur de scripts Robots :

pip install pyexcel

Même si vous installez une bibliothèque externe, il n'y a aucune garantie que l'éditeur de scripts Robots prenne en charge toutes les fonctionnalités de la bibliothèque externe. Par exemple, il peut ne pas prendre en charge l'affichage des graphiques et traçages disponibles dans certaines bibliothèques externes.

Utiliser HCL et Python avec des API

Vous pouvez utiliser les scripts Python/HCL dans Robots pour travailler avec les API, à la fois avec des API tierces et avec la propre API de Diligent One.

Utiliser une API tierce

Pour utiliser une API tierce, commencez par importer la bibliothèque Python Requests dans l'éditeur de script Robots :

import requests

Vous pouvez maintenant faire des requêtes API en utilisant la syntaxe de requête de Python et recevoir des réponses. Afin d'obtenir un exemple simple d'utilisation de Python pour la création d'une requête dans une API tierce dans Robots, consultez la section Partie 3 : Étendez votre champ d'action dans Vos premiers pas avec la création de scripts Robots et l'API Diligent HighBond.

Expliquer dans le détail comment utiliser Python avec des API tierces dépasse le périmètre de notre documentation. Cependant, il existe de nombreuses ressources en ligne qui peuvent fournir des conseils détaillés.

Utiliser l'API HighBond

L'API HighBond est l'interface de développement de la plateforme Diligent One. Vous pouvez utiliser l'API pour automatiser les interactions et le flux de travail de Diligent One, créer des rapports et intégrer Diligent One à d'autres systèmes de votre organisation.

HCL comprend des méthodes qui facilitent l'interaction avec l'API HighBond. Pour plus d'informations, consultez la section Méthodes API HighBond HCL.

Vous pouvez également utiliser la bibliothèque Python Requests avec l'API HighBond. Toutefois, pour des raisons de facilité et de simplicité, nous recommandons d'utiliser les méthodes HCL.

Pour suivre un tutoriel d'introduction sur l'utilisation de Python et de HCL avec l'API HighBond, consultez la section Premiers pas avec la création de scripts Robots et l'API Diligent HighBond.