Att utnyttja Workiva Scripting och API:er kan avsevärt effektivisera verksamheter och arbetsflöden. Precis som med alla skriptprojekt resulterar bästa praxis för kodutveckling och versionskontroll i 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 skriptredigerare
Workiva Scripting Editor skapades för att hjälpa till med att integrera produktionskod i Workiva, övervaka produktionskörningar och utföra initial felsökning när problem uppstår. Det är inte en heltäckande kodredigerare, och vi har inga planer på att göra det till en.
Utvecklingsmiljö
Om du redan har en företagsutvecklingsmiljö och ett versionshanteringssystem rekommenderar vi att du använder det för all din skriptutveckling och testning.
Viktiga komponenter i en utvecklingsmiljö inkluderar en kodredigerare (populära exempel inkluderar VSCode, PyCharm, Jupyter, etc.) och ett versionskontrollsystem (populära exempel inkluderar GitHub och GitLab). För icke-ingenjörer eller de som föredrar att inte arbeta i ett kommandoradsgränssnitt finns det lättviktsverktyg som GitHub Desktop och SourceTree som kan effektivisera arbetet i versionshanteringssystem.
Om du inte har en utvecklingsmiljö, överväg att skapa en. Under tiden, se till att spara kopior av dina skript (före, under och efter eventuella ändringar/uppdateringar), och se till att du håller utvecklings-/arbetsversionerna av dina skript separata från produktionsversionerna för att minska oavsiktliga överskrivningar.
Skriptutveckling
Under utveckling och testning av skriptprojekt, överväg att följa ledande Python- och versionshanteringsmetoder:
Pytonorm
Följ PEP 8 - Stilguide för Python-kod så mycket som möjligt. Kodkonsistens är mycket fördelaktigt för läsbarhet, underhållbarhet och kontinuitet.
För att bygga robusta, pålitliga och skalbara Python-skript på produktionsnivå, se till att fokusera på viktiga områden inklusive:
- Autentisering: Att effektivt skapa, hantera och återgenerera lämplig bärartoken säkerställer att endast behöriga användare eller system kan komma åt 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 utförlig loggning för att fånga viktiga händelser och statusmeddelanden, vilket är avgörande 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 smidigt istället för att krascha.
Obs: Använd felhantering för att hantera oväntade situationer. Förlita dig inte på det för att kompensera för, eller maskera prestandakonsekvenserna av, en suboptimal skriptdesign (till exempel, om ditt skript genererar ett stort antal
429: Too Many Requests-svar, bör din skriptdesign och ditt arbetsflöde omstruktureras för att optimera API-anrop, du bör inte förlita dig på effektiv hantering av ett stort antal 429-svar för att skriptet ska lyckas). - Dokumentation: Förklarar vad koden gör och hur den används (både internt via kommentarer och dokumentsträngar och externt via användarguider (README-filer), vilket gör det möjligt för andra utvecklare och framtida dig att förstå och modifiera skriptet effektivt och ändamålsenligt.
- Versionsspårning: Inkorporera semantisk versionshantering i dina skriptprojekt för att underlätta versionsspårning.
- Namngivningskonventioner:Använd tydliga namngivningskonventioner för dina skript (till exempel:
customername_function_v1_3.py). - Testa och verifiera kodefterlevnad. Använd Python-paket som
ruffochflake8för att utföra lint- och formatkontroller. Du kan också utnyttja de omfattande tilläggsverktygen och tilläggen som finns tillgängliga för populära kodredigerare för guider och hjälp med kodformatering och linting. -
AI-kodhjälp: det finns många gratis och betalda AI-kodverktyg tillgängliga som du kan använda för att hjälpa till med felsökning och optimering.
Obs: Även om de är användbara ersätter inte AI-kodassistenter den kunskap och expertis som krävs för att utveckla avancerade skript och automatiseringar.
Versionskontroll
- Ha en enda sanningskälla: Använd ditt versionshanteringssystem som centralt arkiv och enda sanningskälla för dina skriptprojekt. Genomför ändringar ofta för att säkerställa att allt det senaste utvecklingsarbetet och testerna samlas in 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 gjorde ändringen, vad är ändringen, varför ändringen gjordes, etc.).
Bästa praxis för arbetsflöden
När du utvecklar, testar och distribuerar skript, kommer bästa praxis för arbetsflöden att hjälpa till att maximera skriptets prestanda och minimera potentiella fel och problem. Några av de viktigaste grundpelarna i utvecklingsarbetsflödet inkluderar:
- Utför all skriptutveckling och testning i din utvecklingsmiljö, inte i din produktionsmiljö.
- Överför ditt skript till en arbetsyta/ett testområde där du kan testa ditt skript på Workiva.
VIKTIGT: Använd icke-produktionsdata för dina tester. - Distribuera bara ditt skript till din produktionsyta för operativ användning efter att det har testats utan problem.
Överföra 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. Även om du manuellt kan skicka ändringar till Workiva från Workivas skriptredigerare, rekommenderar vi starkt att du automatiserar att skicka din kod från ditt versionshanteringssystem till Workiva med hjälp av Scripting API:erna. Detta är den rekommenderade processen eftersom automatiseringen sparar tid och minskar fel.
Köra och övervaka skript
Skript kan utlösas direkt från skriptredigeraren, från kedjor, från skript-API:er eller från integrerade automatiseringar. Oavsett hur dina skript utlöses rekommenderar vi att du använder skriptredigeraren för att övervaka körningar och felsöka problem.
Skogsavverkning
Skriptredigeraren har ett avsnitt med texten ”Loggar”. Vi rekommenderar att dina skript innehåller utförlig loggning för att ge detaljerad och omfattande information om skriptets funktioner. Denna information är ofta mycket användbar för felsökning, övervakning och förståelse av ditt skripts funktioner. Standardpaketet Python logging är ett exempel på ett loggningsverktyg som kan konfigureras för att ge användbar information om skriptoperationer (till exempel: 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 inkluderar även funktionalitet för att skicka loggar till ett angivet Workiva-kalkylblad i samma arbetsyta. Detta möjliggör enklare åtkomst, snabbare analys och effektiv sökning av loggar. Här är ett exempel på en loggutdata till ett Workiva-kalkylblad (kalkylblads- och ark-ID:n har förvrängts):
Felsökning och tillägg av nya funktioner
Om problem uppstår under skriptets drift rekommenderar vi att du felsöker och uppdaterar i din utvecklingsmiljö, inte i din produktionsmiljö. När dessa korrigeringar/uppdateringar är klara, testade och implementerade i ditt versionshanteringssystem kan du säkert 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 slutförda, testade och implementerade i ditt versionshanteringssystem kan du skicka det uppdaterade skriptet till Workiva.