Workiva Scripting fournit une plateforme flexible et sécurisée pour exécuter du code Python sur le logiciel Workiva. En écrivant des scripts personnalisés qui exécutent automatiquement des processus reproductibles, vous pouvez créer des efficacités à grande échelle sur plusieurs rapports, fichiers et espaces de travail.
Note: La création de scripts n'est actuellement possible que par l'intermédiaire de Customize Workiva. En savoir plus.
Rôles et permissions
Les rôles sont un paramètre à l'échelle du système dans Workiva, ce qui signifie qu'ils établissent un niveau d'accès standard pour chaque script dans un espace de travail. Il existe trois rôles Workiva Scripting qui peuvent être attribués à par votre administrateur d'espace de travail.
| Rôle | Niveau d’accès |
|---|---|
| Script Runner | Peut exécuter des scripts. |
| Script Viewer | Peut visualiser les scripts. |
| Éditeur de scripts | Peut visualiser, créer et modifier des scripts. |
Conseil : Plutôt que d'utiliser le rôle Script Runner, nous recommandons à la plupart des utilisateurs non techniques d'initier des scripts via integrated automations.
Vous pouvez également contrôler l'accès à chaque fichier en attribuant des autorisations à . Les autorisations prévalant sur les rôles, les propriétaires et créateurs de scripts peuvent accorder ou restreindre l'accès à des fichiers individuels.
| Permission | Niveau d’accès |
|---|---|
| Lecteur | Peut exécuter et visualiser des scripts. |
| Éditeur | Peut exécuter, modifier et visualiser des scripts. |
| Responsable | Peut exécuter, modifier, visualiser et créer des scripts. |
Comment utiliser Workiva Scripting
Une fois activés dans votre espace de travail, les scripts apparaîtront sur votre écran d'accueil à côté des autres feuilles de calcul, documents et présentations de votre site. Vous pouvez créer un nouveau script ou sélectionner un script existant dans votre liste de fichiers.
L'éditeur de scripts est l'endroit où vous créez, modifiez et exécutez les scripts de votre site.
Notamment :
- Un canevas central où vous composerez le script
- Une section de sortie au bas de la page où vous verrez les résultats de l'exécution du script.
- Une barre de menu en haut de la page permet de sauvegarder ou d'exécuter le script.
- Un panneau de propriétés sur la droite pour gérer les propriétés des scripts et l'historique des exécutions.
- Un panneau des sources sur le côté gauche
Une fois construits, les scripts peuvent être exécutés manuellement, par programmation, par des chaînes ou à partir d’un fichier Workiva.
Pour exécuter un script manuellement :
- Cliquez sur Run Script dans la barre de menu en haut de l'écran.
- Cliquez sur Add Variable.
- Saisissez les noms et les valeurs des variables d'environnement à transmettre en tant que paramètres.
- Cliquez sur Run Script.
Pour exécuter un script de manière programmatique, envoyez une requête HTTP POST au point de terminaison du prototype Lancer une exécution de script.
L'ID du script est inclus dans le point de terminaison ; vous pouvez transmettre des paramètres en définissant les noms et les valeurs des variables d'environnement dans le corps de la requête POST.
Les sorties de scripts sont enregistrées dans les fichiers stderr et stdout, ainsi que certaines mesures d'utilisation permettant de surveiller l'état du produit.
Pour exécuter un script par l'intermédiaire des chaînes, vous devez utiliser le connecteur Workiva Scripting. Avant cela, un administrateur de sécurité org doit activer le connecteur via l'écran Configurations.
Pour en savoir plus, consultez les articles ci-dessous :
Pour exécuter un script dans un fichier Workiva, vous devez suivre les étapes suivantes
Dans le panneau Automations d’un document, d’une feuille de calcul ou d’une présentation, créez une nouvelle automatisation et choisissez Exécution manuelle comme déclencheur.
Ajoutez une action Execute script, sélectionnez le script que vous souhaitez exécuter et définissez éventuellement les utilisateurs ou les rôles autorisés à l’exécuter.
Seuls les utilisateurs spécifiés verront et pourront exécuter l’automatisation dans le fichier.
En savoir plus sur Exécuter des scripts avec des automatismes.
Créer un script d'entraînement
Avant de créer des scripts réels dans votre site, nous vous recommandons de créer un script d'entraînement dans l'éditeur de scripts. Cela vous permettra de vous familiariser avec le processus avant de manipuler des données réelles.
Suivez les étapes suivantes pour créer un script simple qui calcule la valeur temporelle de l'argent :
- Depuis Home, cliquez sur Create => Script.
- Dans la partie droite, saisissez un nom et une brève description du script.
- Allez dans l'éditeur de script au milieu de l'écran et supprimez tout code existant. Vous devez disposer d'une toile vierge.
-
Collez ce code dans l’éditeur :
import os, sys # https ://www.investopedia.com/terms/t/timevalueofmoney.asp # Formule pour la valeur temporelle de l’argent # FV = PV x [1 + (i / n)]^(n x t) # Supposons qu’une somme de 10 000 $ soit investie pendant un an à un taux d’intérêt de 10 % composé annuellement. # La valeur future de cet argent est : # FV = $10,000 x [1 + (10% / 1)] ^ (1 x 1) = $11,000 compounding_periods = {"annual" : 1, "monthly" : 12, "quarterly" : 4, "daily" :365} if 'INVESTMENT' not in os.environ: print("Cannot run the script. Investment is missing.") sys.exit() if 'INTEREST_RATE' not in os.environ : print("Impossible d'exécuter le script. Le taux d'intérêt est manquant.") sys.exit() if 'COMPOUNDING_PERIOD' not in os.environ : print("Impossible d'exécuter le script. La période de calcul est manquante.") sys.exit() if 'YEARS' not in os.environ : print("Impossible d'exécuter le script. Le nombre d'années est manquant.") sys.exit() compounding_period = os.getenv('COMPOUNDING_PERIOD') if compounding_period not in compounding_periods.keys() : print("Cannot run the script.", compounding_period," is not a valid period") sys.exit() investment = int(os.getenv('INVESTMENT')) interest_rate = float(os.getenv('INTEREST_RATE')) years = int(os.getenv('YEARS')) n = compounding_periods[compounding_period] FV = investment * pow((1 ((interest_rate/100) / n)),n * years) print("Assume a sum of",investment, "is invested for",years, "year(s) at",\ interest_rate,"% interest compounded on",compounding_period, "basis. ") print("La valeur future de cet argent est :") print(FV) - Cliquez sur Run Script en haut à gauche.
- Cliquez sur Add Variable et saisissez les paramètres que vous souhaitez utiliser.
- Cliquez sur Run Script pour terminer.
Les résultats du script peuvent maintenant être visualisés dans le panneau Output en bas de l'écran.
Comment obtenir de l'aide avec Workiva Scripting
Vous pouvez contacter Workiva Support pour toute question concernant Workiva Scripting. Notez toutefois que nos agents ne peuvent répondre qu'aux questions concernant la plateforme elle-même - nous ne pouvons pas vous aider à écrire ou à dépanner votre code.
Nous disposons également d'un certain nombre de solutions disponibles dans le Centre d'assistance :
- Bibliothèques de script et dépendances prises en charge
- Exemple : Script de mise à jour des feuilles de calcul
- Ajouter, télécharger et supprimer des fichiers sources de scripts
- Exécuter des scripts avec des automatismes
- Stocker les résultats des scripts
- Limites des scripts de Workiva
- Exemples de scripts
Ces ressources vous aideront à démarrer avec Workiva Scripting. Pour les questions relatives à l'utilisation des API publiques de Workiva pour écrire votre code afin d'interagir avec la plateforme Workiva de manière programmatique, utilisez notre communauté de développeurs et d'API .
FAQ
Comment les scripts sont-ils couramment utilisés ?
Workiva Scripting permet d'automatiser de nombreuses tâches répétitives et fastidieuses qui seraient autrement effectuées à la main. Parmi les cas d'utilisation les plus courants, on peut citer la suppression des rangées zéro, les mises en page de rapports et l'application d'un formatage personnalisé à plusieurs documents.
Cela dit, les scripts peuvent être largement adaptés à de nombreux besoins professionnels. Le code vous appartient ; ce que vous en faites dépend largement de votre développeur de scripts, de la configuration de votre espace de travail et du nombre actuel de processus manuels dans votre entreprise.
Existe-t-il des limites à l'utilisation de scripts ?
Oui, Workiva applique un certain nombre de limites à Workiva Scripting et à l'API de script.
En savoir plus sur les limites des scripts.
Comment déclencher des scripts à partir de chaînes ?
Cela nécessite le connecteur Workiva Scripting.
Pour en savoir plus, consultez les articles ci-dessous :
Workiva Scripting est-il conforme à Fedramp ?
Absolument. La sécurité est notre priorité absolue chez Workiva, et nous avons construit une infrastructure qui garantit que vos exécutions de code sont à la fois sûres et performantes.
Comment puis-je contrôler l'accès aux scripts ?
Il existe plusieurs façons de protéger votre code contre l'accès par des utilisateurs non autorisés :
- Créer un espace de travail ou une organisation réservés aux utilisateurs autorisés: La création d'un espace de travail, voire d'une organisation entière, réservé aux utilisateurs autorisés est l'option la plus sûre. Par exemple, les partenaires peuvent créer un espace de travail pour Workiva Scripting dans votre organisation et permettre aux clients d'exécuter des scripts à partir de leur propre organisation.
- Utilisez les rôles: Les rôles de script de Workiva (Script Viewer, Script Runner et Script Editor) sont hiérarchisés de manière à ce que les utilisateurs n'aient accès qu'aux scripts nécessaires à leur travail. Le rôle Script Runner, par exemple, permet aux utilisateurs d'exécuter des scripts mais pas d'accéder au code.
- Utiliser les autorisations: Les fichiers de script peuvent être restreints au niveau du fichier afin que seuls des utilisateurs spécifiques puissent modifier ou visualiser votre code.
En savoir plus sur les rôles et les autorisations de script .
Existe-t-il une liste des adresses IP autorisées pour les scripts ?
Oui, les adresses IP autorisées pour le programme de script sont incluses ici.
Existe-t-il une bibliothèque de scripts ?
Nous avons rassemblé un certain nombre d'exemples de scripts pour votre usage. Ces scripts peuvent également être créés manuellement à l'aide des articles mentionnés dans la question précédente.
Comment gérer les versions des scripts ?
À l'heure actuelle, Workiva ne stocke que la dernière version d'un script.
Vous pouvez créer des copies de vos fichiers de script dans Workiva et les organiser dans des dossiers, mais nous vous recommandons d'utiliser un système de contrôle de version distinct - en particulier si vous disposez d'un système de contrôle de version d'entreprise.
Comment synchroniser le code de Workiva avec un système de contrôle de version d'entreprise (par exemple, GitHub) ?
Le site Workiva Scripting API fournit des points d'extrémité de gestion des sources où les utilisateurs peuvent récupérer la dernière version d'un script ou mettre à jour un script vers une copie plus récente. Workiva n'offre pas actuellement de synchronisation automatisée entre les fichiers de scripts et votre système de contrôle de version d'entreprise (par exemple Gitlab, Github, SVN).
Comment puis-je accéder aux informations d'identification des systèmes Workiva et non Workiva à partir d'un script ?
Il existe deux façons d'accéder aux informations d'identification pour les systèmes Workiva et non Workiva :
- Envoyer les informations d'identification en tant qu'entrées d'exécution (de préférence)
- Coder en dur les informations d'identification dans le code
Pourquoi les valeurs des entrées d'exécution du script ne sont-elles pas affichées dans la sortie du journal pendant l'exécution ?
Il s'agit d'une mesure de sécurité. Les paramètres d'entrée pouvant contenir des données sensibles, nous les supprimons des journaux destinés aux utilisateurs.
Comment puis-je stocker des données temporaires pendant l'exécution des scripts ?
Les scripts Workiva peuvent utiliser la fonction Python Open (lien externe) pour lire et écrire des fichiers temporairement dans le dossier /tmp. Les autres chemins sont limités.
Chaque fois qu'un script est exécuté, un conteneur est lancé dans l'infrastructure en nuage de Workiva. Ce conteneur a linux installé, et tous les chemins sont restreints à l'exception de /tmp (qui est vide). Les données peuvent être écrites et lues temporairement sur ce chemin. Une fois la course terminée, le conteneur est mis à la poubelle.
Puis-je définir des variables globales à utiliser dans plusieurs scripts, à la manière des chaînes ?
Pas pour l’instant.
Puis-je envoyer des fichiers en tant que paramètres ?
Les fichiers binaires peuvent être envoyés en tant que paramètres pour autant qu'ils ne dépassent pas 128 Ko et qu'ils soient codés en texte (par exemple, binaire codé en texte).
Puis-je accéder à l'identifiant de l'organisation, à l'identifiant de l'espace de travail et à la région dans mes scripts ?
Oui, l'identifiant de l'organisation, l'identifiant de l'espace de travail et la région (US, APAC, EU) sont accessibles à votre code de script via une variable d'environnement. Par exemple, os.getenv("WORKIVA_ORGANIZATION_ID").
| Variable | Description |
|---|---|
| WORKIVA_ORGANIZATION_ID | L’identifiant unique de l’organisation Workiva où le script est hébergé |
| WORKIVA_ACCOUNT_ID | L’identifiant unique de l’espace de travail Workiva où le script est hébergé |
| DOMAINE_DU_CLUSTER_DE_TRAVAIL | La région Workiva (US, APAC, ou EU) de l’environnement de production où le script est hébergé |
| WORKIVA_SCRIPTING_SCRIPT_ID | L’identifiant unique du script en cours d’exécution. |
| WORKIVA_SCRIPTING_RUN_ID | L’identifiant unique de l’exécution actuelle du script |
| WORKIVA_SCRIPTING_MEMORY_LIMIT | La quantité maximale de RAM disponible pour le script au cours d’une seule exécution. |
| WORKIVA_SCRIPTING_DISK_LIMIT | L’espace disque maximum que le script peut utiliser dans le répertoire /tmp au cours d’une seule exécution. |
Puis-je utiliser le code d'un script Workiva dans un autre script Workiva ?
À l'heure actuelle, il n'existe aucun moyen d'empaqueter un script Workiva en tant que bibliothèque et de réutiliser le code dans plusieurs scripts. La meilleure solution consiste à copier le morceau de code réutilisable et à le coller dans les scripts en fonction des besoins.