Door gebruik te maken van Workiva Scripting en API's kunt u uw activiteiten en workflows aanzienlijk stroomlijnen. Zoals bij alle scriptingprojecten, leidt het volgen van best practices voor codeontwikkeling en versiebeheer tot effectief projectbeheer, continuïteit en succes.
Hieronder vindt u enkele Workiva Scripting tips en trucs voor projectontwikkeling en workflows.
Workiva Scripting Editor
De Workiva Scripting Editor is gemaakt om te helpen bij het integreren van productiecode in Workiva, bij het bewaken van productieruns en bij het oplossen van problemen. Het is geen uitgebreide code-editor, en we hebben geen plannen om er een te maken.
Ontwikkelomgeving
Als u al een enterprise ontwikkelomgeving en versiebeheersysteem hebt, dan raden wij u aan om dat te gebruiken voor al uw scriptontwikkeling en testen.
De belangrijkste onderdelen van een ontwikkelomgeving zijn een Code Editor (populaire voorbeelden zijn VSCode, PyCharm, Jupyter, etc.), en een Versiebeheersysteem (populaire voorbeelden zijn GitHub en GitLab). Voor niet-engineers of degenen die liever niet in een opdrachtregelinterface werken, zijn er lichtgewicht tools zoals GitHub Desktop en SourceTree die het werk in versiebeheersystemen kunnen stroomlijnen.
Als u geen ontwikkelomgeving hebt, overweeg dan om er een op te zetten. Zorg er in de tussentijd voor dat u kopieën van uw scripts bewaart (voor, tijdens en na wijzigingen/updates), en zorg ervoor dat u de ontwikkelings-/werkversies van uw scripts gescheiden houdt van de productieversies om onbedoelde overschrijvingen te voorkomen.
Ontwikkeling van scripts
Overweeg tijdens het ontwikkelen en testen van scriptingprojecten om toonaangevende Python- en versiebeheerpraktijken te volgen:
Python
Volg PEP 8 - Stijlgids voor Python-code zoveel mogelijk. Codeconsistentie is zeer bevorderlijk voor de leesbaarheid, onderhoudbaarheid en continuïteit.
Om robuuste, betrouwbare en schaalbare Python-scripts op productieniveau te bouwen, moet u zich richten op de belangrijkste gebieden, waaronder:
- Authenticatie: Het effectief aanmaken, beheren en regenereren van het juiste token zorgt ervoor dat alleen bevoegde gebruikers of systemen toegang hebben tot de bronnen, gegevens of functionaliteit van de werkruimte.
- Modulariteit: Verdeel grote scripts in kleinere, onafhankelijke en herbruikbare eenheden (functies, klassen, modules/bestanden). Hierdoor is het script gemakkelijker te lezen, te testen, te debuggen en na verloop van tijd te onderhouden.
- Loggen: Zorg voor uitgebreide logboekregistratie om belangrijke gebeurtenissen en statusberichten vast te leggen, wat van vitaal belang is voor het bewaken van de prestaties en het oplossen van problemen.
-
Foutafhandeling: Neem logica voor foutafhandeling op om scripts robuuster, betrouwbaarder en gebruiksvriendelijker te maken door onverwachte situaties netjes op te lossen in plaats van te crashen.
Opmerking: Gebruik foutafhandeling om onverwachte situaties aan te pakken. Vertrouw er niet op om de gevolgen voor de prestaties van een suboptimaal scriptontwerp te compenseren of te maskeren (als uw script bijvoorbeeld een groot aantal 429/Too Many Requests reacties genereert, moeten uw scriptontwerp en workflow worden geherstructureerd om de API-aanroepen te optimaliseren, u moet niet vertrouwen op de effectieve afhandeling van grote aantallen 429s voor het succes van het script).
- Documentatie: Legt uit wat de code doet en hoe deze te gebruiken (zowel intern via commentaar en docstrings als extern via gebruikershandleidingen (README's), zodat andere ontwikkelaars en toekomstige gebruikers het script effectief en efficiënt kunnen begrijpen en aanpassen.
- Versie bijhouden: Neem semantisch versiebeheer op in uw scriptingprojecten om te helpen bij het bijhouden van versies.
- Naamgevingsconventies: Gebruik duidelijke naamgevingsconventies voor uw scripts (bijvoorbeeld:
customername_function_v1_3.py). - Test en controleer of de code wordt nageleefd. Gebruik Python-pakketten zoals
ruffenflake8om controles op lint en formaat uit te voeren. U kunt ook gebruik maken van de uitgebreide add-on tools en extensies die beschikbaar zijn voor populaire code-editors voor gidsen en hulp bij het formatteren en linten van code. -
AI-codehulp: er zijn veel gratis en betaalde AI-codehulpmiddelen beschikbaar die u kunt gebruiken om te helpen bij het debuggen en optimaliseren.
Opmerking: Hoewel ze nuttig zijn, vervangen AI-codeassistenten niet de kennis en expertise die nodig zijn om geavanceerde scripts en automatiseringen te ontwikkelen.
Versiebeheer
- Gebruik één enkele bron van waarheid: Gebruik uw versiebeheersysteem als het centrale archief en de enige bron van waarheid voor uw scriptingprojecten. Committeer wijzigingen vaak om ervoor te zorgen dat al het laatste ontwikkelingswerk en testen wordt vastgelegd en centraal wordt opgeslagen.
- Documenteer veranderingen volledig: Voeg zoveel mogelijk details en ondersteunende informatie toe aan alle commits en pull requests in uw versiebeheersysteem om alle wijzigingen te documenteren (wie heeft de wijziging gemaakt, wat is de wijziging, waarom is de wijziging gemaakt, etc.).
Beste werkwijzen voor workflows
Bij het ontwikkelen, testen en implementeren van scripts helpt het volgen van best practices in de workflow om de scriptprestaties te maximaliseren en potentiële fouten en problemen te minimaliseren. Enkele van de belangrijkste pijlers van de ontwikkelingsworkflow zijn:
- Voer alle scriptontwikkeling en tests uit in uw development omgeving, niet in uw productieomgeving.
- Verplaats uw script naar een staging werkruimte/gebied waar u uw script op Workiva kunt testen.
BELANGRIJK: Gebruik niet-productie gegevens voor uw testen. - Implementeer uw script pas op uw productiewerkruimte voor operationeel gebruik nadat het met succes is getest.
Code overbrengen naar Workiva
Zodra uw hoofdontwikkeling en testen voltooid zijn en alles werkt zoals verwacht, kunt u uw code overbrengen naar Workiva. Hoewel u handmatig wijzigingen naar Workiva kunt pushen vanuit de Workiva Scripting Editor, raden wij u sterk aan om het pushen van uw code vanuit uw versiebeheersysteem naar Workiva te automatiseren met behulp van de Scripting API's. Dit is het aanbevolen proces omdat de automatisering tijd bespaart en fouten vermindert.
Scripts uitvoeren en bewaken
Scripts kunnen rechtstreeks vanuit de Scripting Editor, vanuit Chains, vanuit de Scripting API's of vanuit Geïntegreerde Automatiseringen geactiveerd worden. Ongeacht hoe uw scripts worden geactiveerd, raden wij u aan de Scripting Editor te gebruiken om runs te controleren en problemen op te lossen.
Loggen
De Scripting Editor bevat een sectie "Logs"; wij raden aan dat uw scripts verbose logging bevatten om gedetailleerde en uitgebreide informatie te geven over de bewerkingen van het script. Deze informatie is vaak erg nuttig voor het debuggen, controleren en begrijpen van de werking van uw script. Het standaard Python logging pakket is een voorbeeld van een logging-hulpprogramma dat ingesteld kan worden om nuttige informatie over scriptbewerkingen te geven (bijvoorbeeld: tijdstempel, logniveau, bericht, enz.) Zorg ervoor dat u de verschillende logniveaus (INFO, DEBUG, ERROR, enz.) gebruikt en gedetailleerde en nuttige logberichten opneemt.
Veel geavanceerde gebruikers hebben ook de functionaliteit om logboeken naar een aangewezen Workiva-spreadsheet in dezelfde werkruimte te pushen. Dit maakt eenvoudigere toegang, snellere analyse en efficiënt opvragen van logs mogelijk. Hier is een voorbeeld van een loguitvoer naar een Workiva-spreadsheet (spreadsheet- en blad-ID's zijn verduisterd):
Debuggen en nieuwe functies toevoegen
Als er problemen optreden tijdens de werking van uw script, raden wij u aan het debuggen en bijwerken uit te voeren in uw ontwikkelomgeving, niet in uw productieomgeving. Zodra deze fixes/updates klaar, getest en gecommit zijn naar uw versiebeheersysteem, kunt u het bijgewerkte script veilig terugzetten naar Workiva.
Dezelfde workflow moet worden gebruikt bij het toevoegen van nieuwe functies aan bestaande scripts: voer alle updates en tests uit in uw ontwikkelomgeving. Zodra alle scriptupdates zijn voltooid, met succes zijn getest en zijn vastgelegd in uw versiebeheersysteem, kunt u het bijgewerkte script naar Workiva pushen.