Å utnytte Workiva-skripting og API-er kan effektivisere drift og arbeidsflyter betydelig. Som med alle skriptprosjekter, resulterer det å følge beste praksis for kodeutvikling og versjonskontroll i effektiv prosjektledelse, kontinuitet og suksess.
Nedenfor finner du noen tips og triks for Workiva-skripting for prosjektutvikling og arbeidsflyter.
Workiva skriptredigerer
Workiva Scripting Editor ble laget for å hjelpe med å integrere produksjonskode i Workiva, overvåke produksjonskjøringer og utføre innledende feilsøking når problemer oppstår. Det er ikke en omfattende kodeeditor, og vi har ingen planer om å gjøre den til en.
Utviklingsmiljø
Hvis du allerede har et bedriftsutviklingsmiljø og et versjonskontrollsystem, anbefaler vi at du bruker det til all skriptutvikling og testing.
Viktige komponenter i et utviklingsmiljø inkluderer en kodeeditor (populære eksempler inkluderer VSCode, PyCharm, Jupyter, osv.), og et versjonskontrollsystem (populære eksempler inkluderer GitHub og GitLab). For de som ikke er ingeniører, eller de som foretrekker å ikke jobbe i et kommandolinjegrensesnitt, finnes det lette verktøy som GitHub Desktop og SourceTree som kan effektivisere arbeidet i versjonskontrollsystemer.
Hvis du ikke har et utviklingsmiljø, bør du vurdere å sette opp et. I mellomtiden bør du sørge for å lagre kopier av skriptene dine (før, under og etter eventuelle endringer/oppdateringer), og sørg for at du holder utviklings-/arbeidsversjonene av skriptene dine atskilt fra produksjonsversjonene for å redusere utilsiktet overskriving.
Skriptutvikling
Under utvikling og testing av skriptprosjekter bør du vurdere å følge ledende Python- og versjonskontrollpraksiser:
Python
Følg PEP 8 - Stilguide for Python-kode så mye som mulig. Kodekonsistens er svært gunstig for lesbarhet, vedlikeholdbarhet og kontinuitet.
For å bygge robuste, pålitelige og skalerbare Python-skript på produksjonsnivå, sørg for å fokusere på viktige områder, inkludert:
- Autentisering: Effektiv oppretting, administrasjon og regenerering av riktig bærertoken sikrer at bare autoriserte brukere eller systemer har tilgang til arbeidsområdets ressurser, data eller funksjonalitet.
- Modularitet: Del opp store skript i mindre, uavhengige og gjenbrukbare enheter (funksjoner, klasser, moduler/filer). Dette gjør skriptet enklere å lese, teste, feilsøke og vedlikeholde over tid.
- Logging: Inkluder detaljert logging for å fange opp viktige hendelser og statusmeldinger, noe som er viktig for å overvåke ytelse og feilsøke eventuelle problemer.
-
Feilhåndtering: Inkluder logikk for feilhåndtering for å gjøre skript mer robuste, pålitelige og brukervennlige ved å håndtere uventede situasjoner på en elegant måte i stedet for at de krasjer.
Merk: Bruk feilhåndtering for å håndtere uventede situasjoner. Ikke stol på det for å kompensere for, eller maskere ytelseskonsekvensene av, et suboptimalt skriptdesign (for eksempel, hvis skriptet ditt genererer et stort antall
429: Too Many Requests-svar, bør skriptdesignet og arbeidsflyten din omstruktureres for å optimalisere API-kall. Du bør ikke stole på effektiv håndtering av et stort antall 429-svar for at skriptet skal lykkes). - Dokumentasjon: Forklarer hva koden gjør og hvordan den brukes (både internt via kommentarer og dokumentstrenger og eksternt via brukerhåndbøker (README-er), slik at andre utviklere og fremtidige deg kan forstå og endre skriptet effektivt og virkningsfullt.
- Versjonssporing: Innlemm semantisk versjonskontroll i skriptprosjektene dine for å hjelpe med versjonssporing.
- Navnekonvensjoner:Bruk tydelige navnekonvensjoner for skriptene dine (for eksempel:
customername_function_v1_3.py). - Test og verifiser kodesamsvar. Bruk Python-pakker som
ruffogflake8for å utføre lint- og formatkontroller. Du kan også utnytte de omfattende tilleggsverktøyene og utvidelsene som er tilgjengelige for populære koderedigerere for veiledninger og hjelp med kodeformatering og linting. -
Hjelp med AI-kode: Det finnes mange gratis og betalte AI-kodeverktøy som du kan bruke for å hjelpe med feilsøking og optimalisering.
Merk: Selv om de er nyttige, erstatter ikke AI-kodeassistenter kunnskapen og ekspertisen som kreves for å utvikle avanserte skript og automatiseringer.
Versjonskontroll
- Ha én sannhetskilde: Bruk versjonskontrollsystemet ditt som det sentrale arkivet og den eneste sannhetskilden for skriptprosjektene dine. Gjennomfør endringer ofte for å sikre at alt det nyeste utviklingsarbeidet og testingen registreres og lagres sentralt.
- Dokumenter endringer fullstendig: Legg til så mye detaljer og støttende informasjon som mulig i alle commits og pull-forespørsler i versjonskontrollsystemet ditt for å dokumentere alle endringer (hvem som gjorde endringen, hva er endringen, hvorfor endringen ble gjort osv.).
Beste praksis for arbeidsflyt
Når du utvikler, tester og distribuerer skript, vil det å følge beste praksis for arbeidsflyt bidra til å maksimere skriptytelsen og minimere potensielle feil og problemer. Noen av hovedpilarene i utviklingsarbeidsflyten inkluderer:
- Utfør all skriptutvikling og testing i ditt utviklingsmiljø, ikke i produksjonsmiljøet ditt.
- Overfør skriptet ditt til et testområde/arbeidsområde hvor du kan teste skriptet på Workiva.
VIKTIG: Bruk ikke-produksjonsdata til testingen din. - Distribuer kun skriptet ditt til produksjonsområdet for operativ bruk etter at det er testet.
Overføring av kode til Workiva
Når hovedutviklingen og testingen er fullført og alt fungerer som forventet, kan du overføre koden din til Workiva. Selv om du kan sende endringer til Workiva manuelt fra Workiva Scripting Editor, anbefaler vi på det sterkeste at du automatiserer å sende koden din fra versjonskontrollsystemet til Workiva ved hjelp av Scripting API-ene. Dette er den anbefalte prosessen ettersom automatiseringen sparer tid og reduserer feil.
Kjøring og overvåking av skript
Skript kan utløses direkte fra skriptredigereren, fra kjeder, fra skript-API-ene eller fra integrerte automatiseringer. Uansett hvordan skriptene dine utløses, anbefaler vi at du bruker skriptredigereren til å overvåke kjøringer og feilsøke problemer.
Loggføring
Skriptredigereren har en «Logger»-seksjon. Vi anbefaler at skriptene dine inkluderer detaljert logging for å gi detaljert og omfattende informasjon om skriptets operasjoner. Denne informasjonen er ofte svært nyttig for feilsøking, overvåking og forståelse av skriptets operasjoner. Standard Python-loggpakkener et eksempel på et loggverktøy som kan settes opp til å gi nyttig informasjon om skriptoperasjoner (for eksempel: tidsstempel, loggnivå, melding osv.). Sørg for å bruke de ulike loggnivåene (INFO, DEBUG, ERROR osv.) og inkluder detaljerte og nyttige loggmeldinger.
Mange avanserte brukere inkluderer også funksjonalitet for å sende logger til et angitt Workiva-regneark i samme arbeidsområde. Dette gir enklere tilgang, raskere analyse og effektiv spørring av logger. Her er et eksempel på en loggutdata til et Workiva-regneark (regneark- og ark-ID-er er blitt tilslørt):
Feilsøking og legge til nye funksjoner
Hvis det oppstår problemer under skriptets drift, anbefaler vi at du utfører feilsøking og oppdatering i utviklingsmiljøet, ikke produksjonsmiljøet. Når disse rettelsene/oppdateringene er fullførte, testet og lagret i versjonskontrollsystemet ditt, kan du trygt sende det oppdaterte skriptet tilbake til Workiva.
Den samme arbeidsflyten bør brukes når du legger til nye funksjoner i eksisterende skript: utfør alle oppdateringer og testing i utviklingsmiljøet ditt. Når alle skriptoppdateringer er fullførte, testet og lagret i versjonskontrollsystemet ditt, kan du sende det oppdaterte skriptet til Workiva.