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 Workiva vous aide à gérer le code dans Workiva, à exécuter des scripts, à surveiller les exécutions en production et à résoudre les problèmes. Pour le développement avancé, les tests, la vérification du code, le débogage et la gestion des versions, utilisez un environnement de développement dédié.
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 :
- s sur l'authentification : Utilisez une autorisation API pour demander des jetons d'accès à durée limitée pour les API Workiva. N'accordez que les autorisations requises par l'intégration, protégez l'identifiant client et la clé secrète, et ne stockez jamais les identifiants dans les journaux. Pour obtenir des instructions, consultez la page « » (Configuration de l'API Workiva) à l'adresse .
- 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 : Intégrez une journalisation utile et structurée afin de consigner les événements importants, les changements d'état, les avertissements et les erreurs. N'enregistrez jamais d'identifiants, de jetons d'accès, de données saisies lors de l'exécution ou toute autre information sensible.
-
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 cette fonctionnalité pour compenser ou masquer les répercussions sur les 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 ; la conception de votre script et votre workflow doivent être repensés afin d’optimiser les appels API ; vous ne devez pas compter sur une gestion efficace d’un grand nombre de réponses 429 pour garantir le succès de votre 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 le développement initial et les tests unitaires dans votre environnement de développement.
- Transférez le script vers un espace de travail de préproduction ou toute autre zone contrôlée afin de procéder à des tests d'intégration dans Workiva. Utilisez des données hors production.
- Ne déployez le script dans l'environnement de production qu'une fois les tests terminés.
Transférer le code vers Workiva
Une fois le développement et les tests terminés, transférez le code vers Workiva. Vous pouvez mettre à jour les sources manuellement dans l'éditeur de scripts, mais nous vous recommandons vivement d'automatiser le déploiement à partir de votre système de contrôle de version grâce à l'API de script Workiva. Le déploiement automatisé permet de gagner du temps, de réduire les erreurs manuelles et contribue à maintenir Workiva synchronisé avec votre source soumise au contrôle de version.
Le déploiement automatisé des sources nécessite une autorisation API avec le script « » et le champ d'application « script:write ». Si le déploiement implique également la récupération ou la vérification de sources, il nécessite le script « » : voir . Envoyez X-Version: 2026-01-01 avec chaque requête API. Pour obtenir des instructions sur l'octroi de subventions, consultez . Configuration de l'API Workiva : . Pour connaître les opérations prises en charge, consultez le guide de l'API de script d' : .
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 intitulée « Logs ». Nous vous recommandons vivement d'utiliser, dans vos scripts, un système de journalisation détaillé et structuré afin d'enregistrer les opérations importantes, les changements d'état, les avertissements et les erreurs. Une journalisation efficace est indispensable pour surveiller les performances, résoudre les problèmes et comprendre le comportement des scripts.
Le module standard de Python dédié à la journalisation, , peut inclure des informations utiles telles que les horodatages, les niveaux de journalisation et les messages. Utilisez les niveaux appropriés, tels que DEBUG , INFO , WARNING et ERROR , pour contrôler la quantité d'informations générées. N'enregistrez pas les identifiants, les jetons d'accès, les données saisies lors de l'exécution ni aucune autre information sensible.
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.