Door gebruik te maken van Workiva Scripting en API's kunnen processen en workflows aanzienlijk worden gestroomlijnd. Zoals bij alle scriptprojecten geldt ook hier: het volgen van best practices voor codeontwikkeling en versiebeheer leidt tot effectief projectmanagement, continuïteit en succes.
Hieronder vindt u enkele tips en trucs voor Workiva Scripting, nuttig voor projectontwikkeling en workflows.
Workiva Scripting Editor
De Workiva Scripting Editor is ontwikkeld om te helpen bij het integreren van productiecode in Workiva, het monitoren van productieruns en het uitvoeren van eerste probleemoplossing wanneer zich problemen voordoen. Het is geen uitgebreide code-editor en we zijn ook niet van plan er een te maken.
Ontwikkelingsomgeving
Als u al beschikt over een bedrijfsontwikkelomgeving en een versiebeheersysteem, raden we u aan deze te gebruiken voor al uw scriptontwikkeling en -testen.
Belangrijke onderdelen van een ontwikkelomgeving zijn onder andere een Code Editor (populaire voorbeelden zijn VSCode, PyCharm, Jupyter, enz.) en een Versiebeheersysteem (populaire voorbeelden zijn GitHub en GitLab). Voor niet-technici of voor degenen die liever niet met een commandoregelinterface werken, zijn er lichtgewicht tools zoals GitHub Desktop en SourceTree die het werken met versiebeheersystemen kunnen stroomlijnen.
Als je geen ontwikkelomgeving hebt, overweeg er dan een op te zetten. Zorg er ondertussen voor dat u kopieën van uw scripts opslaat (vóór, tijdens en na eventuele wijzigingen/updates), en zorg ervoor dat u de ontwikkelings-/werkversies van uw scripts gescheiden houdt van de productieversies om te voorkomen dat ze per ongeluk worden overschreven.
Scriptontwikkeling
Houd tijdens de ontwikkeling en het testen van scriptprojecten rekening met de gangbare Python- en versiebeheerpraktijken:
Python
Volg PEP 8 - Stijlrichtlijnen voor Python-code zoveel mogelijk. Codeconsistentie is zeer gunstig voor de leesbaarheid, het onderhoud en de continuïteit.
Om robuuste, betrouwbare en schaalbare Python-scripts voor productiegebruik te ontwikkelen, is het belangrijk om je te concentreren op de volgende belangrijke gebieden:
- Authenticatie: Het effectief aanmaken, beheren en regenereren van het juiste bearer-token zorgt ervoor dat alleen geautoriseerde gebruikers of systemen toegang hebben tot de resources, data of functionaliteit van de werkruimte.
- Modulariteit: Splits grote scripts op in kleinere, onafhankelijke en herbruikbare eenheden (functies, klassen, modules/bestanden). Hierdoor is het script gemakkelijker te lezen, te testen, te debuggen en te onderhouden.
- Logboekregistratie: Schakel uitgebreide logboekregistratie in om belangrijke gebeurtenissen en statusberichten vast te leggen. Dit is essentieel voor het bewaken van de prestaties en het oplossen van eventuele problemen.
-
Foutafhandeling: Voeg logica voor foutafhandeling toe om scripts robuuster, betrouwbaarder en gebruiksvriendelijker te maken door onverwachte situaties netjes af te handelen in plaats van te crashen.
Opmerking: Gebruik foutafhandeling om onverwachte situaties [] aan te pakken. Vertrouw er niet op dat het de prestatiegevolgen van een suboptimaal scriptontwerp compenseert of maskeert (bijvoorbeeld, als uw script een groot aantal
.429: Too Many Requestsreacties genereert, moeten uw scriptontwerp en workflow worden herzien om API-aanroepen te optimaliseren; u moet er niet op vertrouwen dat een effectieve afhandeling van een groot aantal 429-reacties het succes van het script garandeert) - Documentatie: Legt uit wat de code doet en hoe deze te gebruiken is (zowel intern via commentaren en docstrings als extern via gebruikershandleidingen (README's)), waardoor andere ontwikkelaars en toekomstige gebruikers het script effectief en efficiënt kunnen begrijpen en aanpassen.
- Versiebeheer: Integreer semantisch versiebeheer in uw scriptprojecten om te helpen bij het bijhouden van versies.
- Naamgevingsconventies:Gebruik duidelijke naamgevingsconventies voor uw scripts (bijvoorbeeld:
klantnaam_functie_v1_3.py). - Test en verifieer de naleving van de code. Gebruik Python-pakketten zoals
ruffenflake8om lint- en formaatcontroles uit te voeren. Je kunt ook gebruikmaken van de uitgebreide add-on tools en extensies die beschikbaar zijn voor populaire code-editors voor handleidingen en hulp bij het formatteren en controleren van code. -
AI-codeondersteuning: Er zijn veel gratis en betaalde AI-codetools beschikbaar die je kunt gebruiken om te helpen bij het debuggen en optimaliseren.
Opmerking: Hoewel AI-codeassistenten nuttig zijn, vervangen ze niet de kennis en expertise die nodig zijn om geavanceerde scripts en automatiseringen te ontwikkelen.
Versiebeheer
- Zorg voor één betrouwbare bron: Gebruik je versiebeheersysteem als centrale opslagplaats en enige betrouwbare bron voor je scriptprojecten. Voer regelmatig wijzigingen door om ervoor te zorgen dat al het recente ontwikkelingswerk en de testresultaten worden vastgelegd en centraal worden opgeslagen.
- Documenteer wijzigingen volledig: Voeg zoveel mogelijk details en ondersteunende informatie toe aan alle commits en pull requests in uw versiebeheersysteem om alle wijzigingen te documenteren (wie de wijziging heeft aangebracht, wat de wijziging is, waarom de wijziging is aangebracht, enz.).
Werkproces-best practices
Bij het ontwikkelen, testen en implementeren van scripts helpt het volgen van best practices voor 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 -testen uit in uw ontwikkelomgeving, niet in uw productieomgeving.
- Verplaats je script naar een testomgeving waar je het kunt testen op Workiva.
BELANGRIJK: Gebruik niet-productie data voor uw tests. - Implementeer uw script pas in uw productieomgeving voor operationeel gebruik nadat het succesvol is getest.
Code overzetten naar Workiva
Zodra de belangrijkste ontwikkelings- en testfase is afgerond en alles naar behoren werkt, kunt u uw code overzetten naar Workiva. Hoewel je handmatig wijzigingen naar Workiva kunt pushen vanuit de Workiva Scripting Editor, raden we je ten zeerste aan om het pushen van je code vanuit je versiebeheersysteem naar Workiva te automatiseren met behulp van de Scripting API's . Dit is het aanbevolen proces omdat automatisering tijd bespaart en fouten vermindert.
Scripts uitvoeren en bewaken
Scripts kunnen rechtstreeks worden geactiveerd vanuit de scripteditor, vanuit ketens, vanuit de script-API's of vanuit geïntegreerde automatiseringen. Ongeacht hoe uw scripts worden geactiveerd, raden we u aan de scripteditor te gebruiken om de uitvoering te controleren en problemen op te sporen.
Logboekregistratie
De scripteditor bevat een sectie 'Logboeken'; we raden aan om in uw scripts uitgebreide logboekregistratie te gebruiken om gedetailleerde en uitgebreide informatie te verkrijgen over de werking van het script. Deze informatie is vaak erg nuttig voor het debuggen, monitoren en begrijpen van de werking van uw script. Het standaard Python-pakket ` logging` is een voorbeeld van een hulpprogramma voor loggen dat kan worden ingesteld om nuttige informatie te verschaffen over scriptbewerkingen (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 mogelijkheid toegevoegd om logboeken naar een speciaal daarvoor bestemd Workiva-spreadsheet in dezelfde werkruimte te sturen. Dit maakt eenvoudigere toegang, snellere analyse en efficiëntere bevraging van logbestanden mogelijk. Hier volgt een voorbeeld van een loguitvoer naar een Workiva-spreadsheet (spreadsheet- en sheet-ID's zijn onherkenbaar gemaakt):
Foutopsporing uitvoeren en nieuwe functies toevoegen
Als er problemen optreden tijdens de werking van uw script, raden we u aan om het debuggen en bijwerken uit te voeren in uw ontwikkelomgeving en niet in uw productieomgeving. Zodra die correcties/updates zijn voltooid, getest en vastgelegd in uw versiebeheersysteem, kunt u het bijgewerkte script veilig terugsturen naar Workiva.
Volg dezelfde workflow bij het toevoegen van nieuwe functies aan bestaande scripts: voer alle updates en tests uit in je ontwikkelomgeving. Zodra alle scriptupdates zijn voltooid, succesvol zijn getest en zijn vastgelegd in uw versiebeheersysteem, kunt u het bijgewerkte script naar Workiva pushen.