Workiva Scripting: Best practices voor het ontwikkelproces

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

Met de Workiva Scripting Editor kunt u code in Workiva beheren, scripts uitvoeren, productieruns bewaken en problemen oplossen. Voor geavanceerde ontwikkeling, testen, linting, debuggen en versiebeheer kunt u een speciale ontwikkelomgeving gebruiken.

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 : Gebruik een API-grant om kortstondige toegangstokens aan te vragen voor Workiva API's. Geef alleen de benodigde rechten voor de integratie, bescherm de client-ID en het geheim, en sla nooit inloggegevens op in logbestanden. Zie Workiva API Setup voor instructies.
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: Voeg nuttige, gestructureerde logboekregistratie toe om belangrijke gebeurtenissen, statuswijzigingen, waarschuwingen en fouten vast te leggen. Sla nooit inloggegevens, toegangstokens, runtime-inputs of andere gevoelige informatie op.
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 Requests reacties 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 ruff en flake8 om 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.).

Werkprocesoptimalisatie

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 de eerste ontwikkelingsfase en unit-tests uit in uw ontwikkelomgeving.
Verplaats het script naar een staging-werkruimte of een andere gecontroleerde omgeving voor integratietests in Workiva. Gebruik niet-productiegegevens.
Implementeer het script pas in de productieomgeving nadat de tests zijn voltooid.

Code overzetten naar Workiva

Zodra de ontwikkeling en het testen zijn afgerond, kunt u de code overdragen naar Workiva. Je kunt bronnen handmatig bijwerken in de Scripting Editor, maar we raden ten zeerste aan om de implementatie te automatiseren vanuit je versiebeheersysteem met de Workiva Scripting API. Geautomatiseerde implementatie bespaart tijd, vermindert handmatige fouten en zorgt ervoor dat Workiva gesynchroniseerd blijft met uw versiebeheerde broncode.

Geautomatiseerde implementatie van de broncode vereist een API-grant met de scope script:write . Als de implementatie ook bronnen ophaalt of verifieert, is script:read vereist. Stuur X-Version: 2026-01-01 mee met elk API-verzoek. Voor instructies over het verkrijgen van toestemming, zie Workiva API Setup . Voor ondersteunde bewerkingen, zie de Scripting API-handleiding .

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 Logs sectie. We raden ten zeerste aan dat uw scripts gedetailleerde, gestructureerde logboekregistratie gebruiken om belangrijke bewerkingen, statuswijzigingen, waarschuwingen en fouten vast te leggen. Goede logboekregistratie is essentieel voor het bewaken van de prestaties, het oplossen van problemen en het begrijpen van het gedrag van scripts.

Het standaard Python-pakket ` logging` kan nuttige informatie bevatten, zoals tijdstempels, logniveaus en berichten. Gebruik geschikte niveaus, zoals DEBUG , INFO , WARNING , en ERROR , om de hoeveelheid geproduceerde informatie te regelen. Sla geen inloggegevens, toegangstokens, runtime-inputs of andere gevoelige informatie op.

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.

Bronnen

Workiva-ondersteuningscentrum