Der Einsatz von Workiva Scripting und APIs kann Arbeitsabläufe und Workflows erheblich rationalisieren. Wie bei allen Scripting-Projekten führt die Einhaltung bewährter Verfahren für die Code-Entwicklung und Versionskontrolle zu einem effektiven Projektmanagement, Kontinuität und Erfolg.
Nachfolgend finden Sie einige Tipps und Tricks zu Workiva Scripting für die Projektentwicklung und die Arbeitsabläufe.
Workiva Skripting-Editor
Mit dem Workiva-Skript-Editor können Sie Code in Workiva verwalten, Skripte ausführen, Produktionsläufe überwachen und Probleme beheben. Verwenden Sie für fortgeschrittene Entwicklungsarbeiten, Tests, Linting, Fehlerbehebung und Versionskontrolle eine dedizierte Entwicklungsumgebung.
Entwicklungsumgebung
Wenn Sie bereits über eine Entwicklungsumgebung und ein Versionskontrollsystem verfügen, empfehlen wir Ihnen, dies für die Entwicklung und das Testen von Skripten zu verwenden.
Zu den wichtigsten Komponenten einer Entwicklungsumgebung gehören ein Code-Editor (beliebte Beispiele sind VSCode, PyCharm, Jupyter, usw.) und ein Versionskontrollsystem (beliebte Beispiele sind GitHub und GitLab). Für Nicht-Ingenieure oder diejenigen, die es vorziehen, nicht mit einer Befehlszeilenschnittstelle zu arbeiten, gibt es leichtgewichtige Tools wie GitHub Desktop und SourceTree, die die Arbeit in Versionskontrollsystemen vereinfachen können.
Wenn Sie keine Entwicklungsumgebung haben, sollten Sie eine einrichten. Achten Sie in der Zwischenzeit darauf, Kopien Ihrer Skripte zu speichern (vor, während und nach allen Änderungen/Aktualisierungen) und stellen Sie sicher, dass Sie die Entwicklungs-/Arbeitsversionen Ihrer Skripte getrennt von den Produktionsversionen aufbewahren, um versehentliches Überschreiben zu vermeiden.
Skripting-Entwicklung
Beachten Sie bei der Entwicklung und dem Testen von Skripting-Projekten die führenden Python- und Versionskontrollpraktiken:
Python
Befolgen Sie PEP 8 - Style Guide for Python Code so weit wie möglich. Die Konsistenz des Codes ist von großem Vorteil für die Lesbarkeit, Wartbarkeit und Kontinuität.
Um robuste, zuverlässige und skalierbare Python-Skripte auf Produktionsebene zu erstellen, sollten Sie sich auf folgende Schlüsselbereiche konzentrieren:
- Authentifizierungs- : Verwenden Sie eine API-Berechtigung, um kurzlebige Zugriffstoken für Workiva-APIs anzufordern. Gewähren Sie nur die für die Integration erforderlichen Zugriffsbereiche, schützen Sie die Client-ID und den geheimen Schlüssel und speichern Sie Anmeldedaten niemals in Protokollen. Eine Anleitung finden Sie unter Workiva-API-Einrichtung .
- Modularität: Zerlegen Sie große Skripte in kleinere, unabhängige und wiederverwendbare Einheiten (Funktionen, Klassen, Module/Dateien). Dies erleichtert das Lesen, Testen, Debuggen und die Pflege des Skripts im Laufe der Zeit.
- Protokollierung: Fügen Sie nützliche, strukturierte Protokollierungen ein, um wichtige Ereignisse, Statusänderungen, Warnungen und Fehler zu erfassen. Protokollieren Sie niemals Anmeldedaten, Zugriffstoken, Laufzeiteingaben oder andere sensible Informationen.
-
Fehlerbehandlung: Fügen Sie eine Logik für die Fehlerbehandlung ein, um Skripte robuster, zuverlässiger und benutzerfreundlicher zu machen, indem Sie unerwartete Situationen elegant bewältigen, anstatt sie zum Absturz zu bringen.
Hinweis: Verwenden Sie die Fehlerbehandlung, um unerwartete Situationen zu behandeln. Verlassen Sie sich nicht darauf, um die Leistungsnachteile eines suboptimalen Skriptdesigns auszugleichen oder zu verschleiern (beispielsweise wenn Ihr Skript eine große Anzahl von „ “
429: Too Many Requests -Antworten generiert, sollten Sie Ihr Skriptdesign und Ihren Workflow überarbeiten, um die API-Aufrufe zu optimieren; Sie sollten sich nicht darauf verlassen, dass die effektive Verarbeitung einer großen Anzahl von 429-Antworten den Erfolg Ihres Skripts gewährleistet). - Dokumentation: Erklärt, was der Code tut und wie er zu verwenden ist (sowohl intern über Kommentare und Docstrings als auch extern über Benutzerhandbücher (READMEs), damit andere Entwickler und Sie selbst das Skript effektiv und effizient verstehen und verändern können.
- Versionsverfolgung: Integrieren Sie semantische Versionierung in Ihre Skript-Projekte, um die Versionsverfolgung zu erleichtern.
- Benennungskonventionen: Verwenden Sie klare Namenskonventionen für Ihre Skripte (zum Beispiel:
customername_function_v1_3.py). - Testen und verifizieren Sie die Einhaltung des Codes. Verwenden Sie Python-Pakete wie
ruffundflake8, um Lint- und Formatprüfungen durchzuführen. Sie können auch die umfangreichen Zusatztools und Erweiterungen nutzen, die für gängige Code-Editoren verfügbar sind, um Anleitungen und Unterstützung bei der Codeformatierung und beim Linting zu erhalten. -
KI-Code-Assistenten: gibt es viele kostenlose und kostenpflichtige KI-Code-Tools, die Ihnen bei der Fehlersuche und Optimierung helfen können.
Hinweis: KI-Code-Assistenten sind zwar hilfreich, ersetzen jedoch nicht das Wissen und die Erfahrung, die für die Entwicklung fortgeschrittener Skripte und Automatisierungen erforderlich sind.
Versionskontrolle
- Eine einzige Quelle der Wahrheit: Verwenden Sie Ihr Versionskontrollsystem als zentrales Repository und als einzige Quelle der Wahrheit für Ihre Skriptprojekte. Übertragen Sie Änderungen häufig, um sicherzustellen, dass alle aktuellen Entwicklungsarbeiten und Tests erfasst und zentral gespeichert werden.
- Dokumentieren Sie Änderungen vollständig: Fügen Sie allen Commits und Pull-Requests in Ihrem Versionskontrollsystem so viele Details und unterstützende Informationen wie möglich hinzu, um alle Änderungen zu dokumentieren (wer hat die Änderung vorgenommen, was ist die Änderung, warum wurde sie vorgenommen usw.).
Bewährte Praktiken für den Workflow
Bei der Entwicklung, dem Testen und der Bereitstellung von Skripten können Sie die Leistung von Skripten maximieren und potenzielle Fehler und Probleme minimieren, wenn Sie die bewährten Arbeitsabläufe befolgen. Einige der wichtigsten Säulen des Entwicklungs-Workflows sind:
- Führen Sie die anfängliche Entwicklung und die Komponententests in Ihrer Entwicklungsumgebung durch.
- Übertragen Sie das Skript in einen Staging-Arbeitsbereich oder einen anderen kontrollierten Bereich, um es in Workiva einer Integrationstestung zu unterziehen. Verwenden Sie Daten aus einer Nicht-Produktionsumgebung.
- Stellen Sie das Skript erst dann im Produktionsarbeitsbereich bereit, wenn die Tests abgeschlossen sind.
Code zu Workiva übertragen
Sobald die Entwicklung und die Tests abgeschlossen sind, übertragen Sie den Code zu Workiva. Sie können die Quellen im Skript-Editor manuell aktualisieren, aber empfehlen wir Ihnen dringend, die Bereitstellung aus Ihrem Versionskontrollsystem mithilfe der Workiva-Skript-API zu automatisieren. Die automatisierte Bereitstellung spart Zeit, reduziert manuelle Fehler und trägt dazu bei, dass Workiva stets mit Ihrer versionsverwalteten Quelle synchronisiert bleibt.
Für die automatisierte Bereitstellung von Quellen ist eine API-Berechtigung mit dem Umfang „ script:write “ erforderlich. Wenn bei der Bereitstellung auch Quellen abgerufen oder überprüft werden, ist das bei jeder API-Anfrage „ Skript „ :read“ erforderlich: . Senden Sie X-Version: 2026-01-01 “. Anweisungen zur Gewährung von Zuschüssen finden Sie unter . Informationen zur Einrichtung der Workiva-API finden Sie unter . Informationen zu den unterstützten Operationen finden Sie im Handbuch zur Skript-API von „ “ unter .
Ausführen und Überwachen von Skripts
Skripte können direkt aus dem Skript-Editor, aus Ketten, aus den Skripting-APIs oder aus integrierten Automatisierungen ausgelöst werden. Unabhängig davon, wie Ihre Skripte ausgelöst werden, empfehlen wir Ihnen, den Skript-Editor zur Überwachung der Ausführung und zur Fehlerbehebung zu verwenden.
Protokollierung
Der Skript-Editor enthält einen Abschnitt „ -Protokolle“ ( ). Wir empfehlen Ihnen dringend, in Ihren Skripten eine detaillierte, strukturierte Protokollierung zu verwenden, um wichtige Vorgänge, Statusänderungen, Warnungen und Fehler aufzuzeichnen. Eine gute Protokollierung ist unerlässlich, um die Leistung zu überwachen, Probleme zu beheben und das Verhalten von Skripten zu verstehen.
Das Standard-Python-Paket „ “ ( ) kann nützliche Informationen wie Zeitstempel, Protokollstufen und Meldungen enthalten. Verwenden Sie geeignete Stufen wie beispielsweise DEBUG , INFO , WARNING sowie ERROR , um den Umfang der ausgegebenen Informationen zu steuern. Protokollieren Sie keine Anmeldedaten, Zugriffstoken, Laufzeiteingaben oder andere sensible Informationen.
Viele fortgeschrittene Benutzer verfügen auch über die Funktion, Protokolle in ein bestimmtes Workiva-Tabellenblatt im selben Arbeitsbereich zu verschieben. Dies ermöglicht einen einfacheren Zugriff, eine schnellere Analyse und eine effiziente Abfrage von Protokollen. Hier sehen Sie ein Beispiel für die Ausgabe eines Protokolls in ein Workiva-Arbeitsblatt (die IDs von Arbeitsblatt und Tabellenkalkulation wurden verschleiert):
Fehlersuche und Hinzufügen neuer Funktionen
Sollten bei der Ausführung Ihres Skripts Probleme auftreten, empfehlen wir Ihnen, das Debugging und die Aktualisierung in Ihrer Entwicklungsumgebung durchzuführen, nicht in Ihrer Produktionsumgebung. Sobald diese Korrekturen/Aktualisierungen fertiggestellt, getestet und in Ihr Versionskontrollsystem übertragen wurden, können Sie das aktualisierte Skript sicher zurück zu Workiva übertragen.
Derselbe Arbeitsablauf sollte verwendet werden, wenn Sie neue Funktionen zu bestehenden Skripten hinzufügen: Führen Sie alle Aktualisierungen und Tests in Ihrer Entwicklungsumgebung durch. Sobald alle Skriptaktualisierungen abgeschlossen, erfolgreich getestet und an Ihr Versionskontrollsystem übergeben wurden, können Sie das aktualisierte Skript an Workiva übergeben.