Genom att utnyttja Workiva Scripting och API:er kan du effektivisera verksamheten och arbetsflödena avsevärt. Precis som i alla skriptprojekt är det viktigt att följa bästa praxis för kodutveckling och versionshantering, vilket leder till effektiv projektledning, kontinuitet och framgång.
Nedan följer några tips och tricks för Workiva Scripting för projektutveckling och arbetsflöden.
Workiva Scripting Editor
Workiva Scripting Editor skapades för att hjälpa till att integrera produktionskod i Workiva, övervaka produktionskörningar och för att göra inledande felsökning när problem uppstår. Det är inte en heltäckande kodredigerare, och vi har inga planer på att göra det.
Utvecklingsmiljö
Om du redan har en utvecklingsmiljö och ett system för versionshantering rekommenderar vi att du använder den för all utveckling och testning av skript.
Viktiga komponenter i en utvecklingsmiljö är bland annat en kodredigerare (populära exempel är VSCode, PyCharm, Jupyter, etc.) och ett versionskontrollsystem (populära exempel är GitHub och GitLab). För icke-ingenjörer eller de som föredrar att inte arbeta i ett kommandoradsgränssnitt finns det lättviktiga verktyg som GitHub Desktop och SourceTree som kan effektivisera arbetet i versionshanteringssystem.
Om du inte har någon utvecklingsmiljö bör du överväga att skapa en. Under tiden bör du spara kopior av dina skript (före, under och efter ändringar/uppdateringar) och se till att du håller utvecklings-/arbetsversionerna av dina skript åtskilda från produktionsversionerna för att undvika oavsiktliga överskrivningar.
Scripting-utveckling
Under utveckling och testning av skriptprojekt bör du överväga att följa ledande Python- och versionshanteringsmetoder:
Python
Följ PEP 8 - Style Guide for Python Code så mycket som möjligt. En konsekvent kod är till stor nytta för läsbarhet, underhåll och kontinuitet.
För att bygga robusta, tillförlitliga och skalbara Python-skript på produktionsnivå måste du fokusera på viktiga områden, bland annat
- Autentisering: Genom att effektivt skapa, hantera och regenerera lämplig bärartoken säkerställs att endast behöriga användare eller system får åtkomst till arbetsytans resurser, data eller funktioner.
- Modularitet: Dela upp stora skript i mindre, oberoende och återanvändbara enheter (funktioner, klasser, moduler/filer). Detta gör skriptet enklare att läsa, testa, felsöka och underhålla över tid.
- Loggning: Inkludera verbose-loggning för att fånga upp viktiga händelser och statusmeddelanden, vilket är viktigt för att övervaka prestanda och felsöka eventuella problem.
-
Felhantering: Inkludera logik för felhantering för att göra skript mer robusta, tillförlitliga och användarvänliga genom att hantera oväntade situationer på ett elegant sätt istället för att krascha.
Obs: Använd felhantering för att hantera oväntade situationer. Förlita dig inte på att det kompenserar för eller maskerar prestandakonsekvenserna av en suboptimal skriptdesign (om ditt skript t.ex. genererar ett stort antal 429/Too Many Requests-svar bör din skriptdesign och ditt arbetsflöde omarbetas för att optimera API-anrop, och du bör inte förlita dig på effektiv hantering av ett stort antal 429 för att skriptet ska lyckas).
- Dokumentation: Förklarar vad koden gör och hur den ska användas (både internt via kommentarer och docstrings och externt via användarhandböcker (README)), så att andra utvecklare och framtida användare kan förstå och modifiera skriptet på ett effektivt sätt.
- Versionsspårning: Införliva semantisk versionshantering i dina skriptprojekt för att underlätta versionsspårning.
- Namngivningskonventioner: Använd tydliga namnkonventioner för dina skript (t.ex.:
customername_function_v1_3.py). - Testa och verifiera att koden följs. Använd Python-paket som
ruffochflake8för att utföra lint- och formatkontroller. Du kan också utnyttja de omfattande tilläggsverktyg och tillägg som finns för populära kodredigerare för att få guider och hjälp med kodformatering och linting. -
AI-kodassistans: Det finns många gratis och betalda AI-kodverktyg som du kan använda för att hjälpa till med felsökning och optimering.
Obs: AI-kodassistenter är visserligen användbara, men ersätter inte den kunskap och expertis som krävs för att utveckla avancerade skript och automatiseringar.
Versionskontroll
- Ha en enda källa till sanning: Använd ditt versionshanteringssystem som central lagringsplats och enda källa till sanning för dina skriptprojekt. Genomför ändringar ofta för att säkerställa att allt det senaste utvecklingsarbetet och testerna fångas upp och lagras centralt.
- Dokumentera ändringar fullständigt: Lägg till så mycket detaljer och stödjande information som möjligt i alla commits och pull requests i ditt versionshanteringssystem för att dokumentera alla ändringar (vem som har gjort ändringen, vad ändringen innebär, varför ändringen gjordes etc.)
Bästa praxis för arbetsflöden
När du utvecklar, testar och distribuerar skript kan du följa bästa praxis för arbetsflödet för att maximera skriptets prestanda och minimera potentiella fel och problem. Några av de viktigaste pelarna i utvecklingsarbetsflödet inkluderar:
- Utför all utveckling och testning av skript i din utvecklingsmiljö, inte i din produktionsmiljö.
- Överför ditt skript till en staging-arbetsyta/område där du kan testa ditt skript på Workiva.
VIKTIGT: Använd icke-produktionsdata för dina tester. - Distribuera ditt skript till din produktionsarbetsyta för operativ användning först efter att det har testats framgångsrikt.
Överföring av kod till Workiva
När din huvudsakliga utveckling och testning är klar och allt fungerar som förväntat kan du överföra din kod till Workiva. Du kan manuellt överföra ändringar till Workiva från Workiva Scripting Editor, men vi rekommenderar starkt att du automatiserar överföring av din kod från ditt versionskontrollsystem till Workiva med hjälp av Scripting API:er. Detta är den rekommenderade processen eftersom automatiseringen sparar tid och minskar antalet fel.
Körning och övervakning av skript
Skript kan utlösas direkt från Scripting Editor, från kedjor, från Scripting API:er eller från integrerade automatiseringar. Oavsett hur dina skript triggas rekommenderar vi att du använder Scripting Editor för att övervaka körningar och för att felsöka problem.
Loggning
Skriptredigeraren innehåller ett avsnitt "Loggar"; vi rekommenderar att dina skript innehåller verbose-loggning för att ge detaljerad och omfattande information om skriptets operationer. Den här informationen är ofta mycket användbar för felsökning, övervakning och förståelse av skriptets funktioner. Pythons standardpaket logging är ett exempel på ett loggningsverktyg som kan ställas in för att ge användbar information om skriptoperationer (t.ex. tidsstämpel, loggnivå, meddelande etc.). Se till att använda de olika loggnivåerna (INFO, DEBUG, ERROR etc.) och inkludera detaljerade och användbara loggmeddelanden.
Många avancerade användare har också funktioner för att skicka loggar till ett särskilt kalkylblad i Workiva i samma arbetsyta. Detta möjliggör enklare åtkomst, snabbare analys och effektiv sökning av loggar. Här är ett exempel på en loggutmatning till ett kalkylblad i Workiva (kalkylbladets och bladets ID har döljts):
Felsökning och tillägg av nya funktioner
Om det uppstår några problem under skriptets drift rekommenderar vi att du utför felsökning och uppdatering i din utvecklingsmiljö, inte i din produktionsmiljö. När dessa korrigeringar/uppdateringar är klara, testade och överförda till ditt versionskontrollsystem kan du sedan på ett säkert sätt skicka tillbaka det uppdaterade skriptet till Workiva.
Samma arbetsflöde bör användas när du lägger till nya funktioner i befintliga skript: utför alla uppdateringar och tester i din utvecklingsmiljö. När alla skriptuppdateringar är klara, testade och överförda till ditt versionshanteringssystem kan du skicka det uppdaterade skriptet till Workiva.