L’utilisation des scripts et des API de Workiva peut considérablement rationaliser les opérations et les flux de travail. Comme pour tous les projets de scripting, le respect des meilleures pratiques en matière de développement de code et de contrôle des versions permet de gérer efficacement les projets, d’en assurer la continuité et de les mener à bien.
Vous trouverez ci-dessous quelques conseils et astuces de Workiva Scripting pour le développement de projets et les flux de travail.
Éditeur de scripts pour Workiva
L’éditeur de scripts de Workiva a été créé pour faciliter l’intégration du code de production dans Workiva, le suivi des cycles de production et le dépannage initial en cas de problème. Il s’agit de et non de un éditeur de code complet, et nous n’avons pas l’intention d’en faire un.
Environnement de développement
Si vous disposez déjà d’un environnement de développement d’entreprise et d’un système de contrôle de version, nous vous recommandons de l’utiliser pour tous vos développements et tests de scripts.
Les éléments clés d’un environnement de développement comprennent un éditeur de code (les exemples les plus répandus sont VSCode, PyCharm, Jupyter, etc.) et un système de contrôle de version (les exemples les plus répandus sont GitHub et GitLab). Pour les non-ingénieurs ou ceux qui préfèrent ne pas travailler dans une interface de ligne de commande, il existe des outils légers tels que GitHub Desktop et SourceTree qui peuvent rationaliser le travail dans les systèmes de contrôle de version.
Si vous ne disposez pas d’un environnement de développement, envisagez d’en créer un. Entre-temps, veillez à sauvegarder des copies de vos scripts (avant, pendant et après toute modification/mise à jour) et veillez à conserver les versions de développement/travail de vos scripts séparément des versions de production afin de réduire les écrasements accidentels.
Développement de scripts
Pendant le développement et les tests des projets de script, pensez à suivre les principales pratiques de Python et de contrôle de version :
Python
Suivez PEP 8 - Style Guide for Python Code autant que possible. La cohérence du code est grandement bénéfique pour la lisibilité, la maintenabilité et la continuité.
Pour créer des scripts Python robustes, fiables et évolutifs au niveau de la production, veillez à vous concentrer sur les domaines clés suivants :
- Authentification : La création, la gestion et la régénération efficaces du jeton porteur approprié garantissent que seuls les utilisateurs ou systèmes autorisés peuvent accéder aux ressources, données ou fonctionnalités de l’espace de travail.
- Modularité : Décomposez les scripts volumineux en unités plus petites, indépendantes et réutilisables (fonctions, classes, modules/fichiers). Cela facilite la lecture, le test, le débogage et la maintenance du script au fil du temps.
- Journalisation : Incluez une journalisation verbeuse pour capturer les événements clés et les messages d’état, ce qui est essentiel pour surveiller les performances et résoudre les problèmes.
-
Gestion des erreurs : Incluez une logique de gestion des erreurs pour rendre les scripts plus robustes, plus fiables et plus conviviaux en gérant les situations inattendues de manière élégante au lieu de les faire planter.
Remarque : Utilisez la gestion des erreurs pour faire face aux situations inattendues. Ne comptez pas sur lui pour compenser ou masquer les conséquences en termes de performances d’une conception de script sous-optimale (par exemple, si votre script génère un grand nombre de réponses 429/Too Many Requests, votre conception de script et votre flux de travail doivent être remaniés pour optimiser les appels API, vous ne devez pas compter sur le traitement efficace d’un grand nombre de 429 pour assurer la réussite du script).
- Documentation : Explique ce que fait le code et comment l’utiliser (à la fois en interne via des commentaires et des docstrings et en externe via des guides d’utilisation (README), permettant aux autres développeurs et à vous de comprendre et de modifier le script de manière efficace et efficiente.
- Suivi des versions : Incorporez semantic versioning dans vos projets de scripts pour faciliter le suivi des versions.
- Conventions de dénomination : Utilisez des conventions de dénomination claires pour vos scripts (par exemple :
customername_function_v1_3.py). - Testez et vérifiez la conformité du code. Utilisez des paquets Python tels que
ruffetflake8pour effectuer des vérifications de format et de lint. Vous pouvez également tirer parti des nombreux outils complémentaires et extensions disponibles pour les éditeurs de code les plus courants afin d’obtenir des guides et de l’aide pour le formatage du code et l’attribution de points de repère. -
Assistance au code IA : Il existe de nombreux outils de code IA gratuits et payants que vous pouvez utiliser pour faciliter le débogage et l’optimisation.
Note : Bien qu’utiles, les assistants de code IA ne remplacent pas les connaissances et l’expertise requises pour développer des scripts et des automatismes avancés.
Contrôle de version
- Une seule source de vérité : Utilisez votre système de contrôle de version comme référentiel central et source unique de vérité pour vos projets de script. Effectuez souvent des modifications afin de vous assurer que tous les derniers travaux de développement et tests sont pris en compte et stockés de manière centralisée.
- Documentez entièrement les modifications : Ajoutez autant de détails et d’informations que possible dans tous les commentaires et demandes de téléchargement de votre système de contrôle de version afin de documenter tous les changements (qui a fait le changement, en quoi consiste le changement, pourquoi le changement a été fait, etc.)
Meilleures pratiques en matière de flux de travail
Lorsque vous développez, testez et déployez des scripts, le respect des meilleures pratiques en matière de flux de travail vous aidera à maximiser les performances des scripts et à minimiser les erreurs et les problèmes potentiels. Voici quelques-uns des principaux piliers du flux de travail de développement :
- Effectuez tous les développements et tests de scripts dans votre environnement de développement , et non dans votre environnement de production.
- Transférez votre script vers un espace de travail/zone de préparation où vous pourrez tester votre script sur Workiva.
IMPORTANT : Utilisez les données non-production pour vos tests. - Ne déployez votre script dans votre espace de travail de production pour une utilisation opérationnelle qu’après l’avoir testé avec succès.
Transférer le code vers Workiva
Une fois que votre développement principal et vos tests sont terminés et que tout fonctionne comme prévu, vous pouvez transférer votre code vers Workiva. Bien que vous puissiez manuellement transférer des modifications vers Workiva à partir de l’éditeur de script de Workiva, nous vous recommandons fortement d’automatiser le transfert de votre code de votre système de contrôle de version vers Workiva à l’aide de Scripting APIs. C’est le processus recommandé car l’automatisation permet de gagner du temps et de réduire les erreurs.
Exécution et surveillance des scripts
Les scripts peuvent être déclenchés directement à partir de l’éditeur de scripts, de chaînes, d’API de scripts ou d’automatismes intégrés. Quelle que soit la manière dont vos scripts sont déclenchés, nous vous recommandons d’utiliser l’éditeur de scripts pour contrôler les exécutions et résoudre les problèmes.
Journalisation
L’éditeur de scripts comprend une section « Journaux » ; nous recommandons que vos scripts intègrent la journalisation en mode verbeux afin de fournir des informations détaillées et complètes sur les opérations du script. Ces informations sont souvent très utiles pour déboguer, surveiller et comprendre les opérations de votre script. Le paquetage standard Python logging est un exemple d’utilitaire de journalisation qui peut être configuré pour fournir des informations utiles sur les opérations de script (par exemple : horodatage, niveau de journalisation, message, etc.) Veillez à utiliser les différents niveaux de journal (INFO, DEBUG, ERROR, etc.) et à inclure des messages de journal détaillés et utiles.
De nombreux utilisateurs avancés incluent également une fonctionnalité permettant de pousser les journaux vers une feuille de calcul Workiva désignée dans le même espace de travail. Cela permet un accès plus facile, une analyse plus rapide et une interrogation plus efficace des journaux. Voici un exemple de sortie de journal vers une feuille de calcul Workiva (les identifiants de la feuille de calcul et de la feuille ont été obscurcis) :
Débogage et ajout de nouvelles fonctionnalités
Si des problèmes surviennent au cours des opérations de votre script, nous vous recommandons d’effectuer le débogage et la mise à jour dans votre environnement de développement, et non dans votre environnement de production. Une fois que ces corrections/mises à jour sont terminées, testées et validées dans votre système de contrôle de version, vous pouvez alors repousser en toute sécurité le script mis à jour vers Workiva.
Ce même flux de travail doit être utilisé lors de l’ajout de nouvelles fonctionnalités à des scripts existants : effectuez toutes les mises à jour et tous les tests dans votre environnement de développement. Une fois que toutes les mises à jour de scripts sont terminées, testées avec succès et validées dans votre système de contrôle de version, vous pouvez transférer le script mis à jour vers Workiva.