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 hjälper dig att hantera kod i Workiva, köra skript, övervaka produktionskörningar och felsöka problem. För avancerad utveckling, testning, linting, felsökning och versionshantering, använd en dedikerad utvecklingsmiljö.
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 - Style Guide for Python Code 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 :Använd ett API-bidrag för att begära kortlivade åtkomsttokens för Workiva API:er. Bevilja endast de omfattningar som krävs av integrationen, skydda klient-ID och hemlighet och lagra aldrig autentiseringsuppgifter i loggar. För instruktioner, se Workiva API-konfiguration .
- 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 användbar, strukturerad loggning för att fånga upp viktiga händelser, statusändringar, varningar och fel. Logga aldrig inloggningsuppgifter, åtkomsttokens, körtidsindata eller annan känslig information.
-
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 smidigt sätt 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 dokumentationstexter och externt via användarhandböcker (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 hjälpa till med 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 central databas 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 osv.).
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 initial utveckling och enhetstestning i din utvecklingsmiljö.
- Överför skriptet till en mellanlagringsarbetsyta eller annat kontrollerat område för integrationstestning i Workiva. Använd icke-produktionsdata.
- Distribuera skriptet till produktionsarbetsytan först efter att testningen är klar.
Överföra kod till Workiva
När utveckling och testning är klar, överför koden till Workiva. Du kan uppdatera källor manuellt i skriptredigeraren, men vi rekommenderar starkt att automatisera distributionen från ditt versionskontrollsystem med Workiva Scripting API. Automatiserad distribution sparar tid, minskar manuella fel och hjälper till att hålla Workiva synkroniserad med din versionskontrollerade källa.
Automatiserad källdistribution kräver ett API-tillstånd med omfånget script:write . Om distributionen även hämtar eller verifierar källor kräver den script:read . Skicka X-version: 2026-01-01 med varje API-förfrågan. För instruktioner om bidrag, se Workiva API-konfiguration . För åtgärder som stöds, se guiden för Scripting API .
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 innehåller ett avsnitt för loggar . Vi rekommenderar starkt att dina skript använder detaljerad, strukturerad loggning för att registrera viktiga åtgärder, statusändringar, varningar och fel. Bra loggning är avgörande för att övervaka prestanda, felsöka problem och förstå skriptbeteende.
Standardpaketet för Python -loggning kan innehålla användbar information som tidsstämplar, loggnivåer och meddelanden. Använd lämpliga nivåer, såsom DEBUG , INFO , WARNING och ERROR , för att kontrollera mängden information som produceras. Logga inte inloggningsuppgifter, åtkomsttokens, körtidsindata eller annan känslig information.
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.