Ved å utnytte Workiva Scripting og API-er kan du effektivisere driften og arbeidsflyten betydelig. Som med alle skriptprosjekter er det viktig å følge beste praksis for kodeutvikling og versjonskontroll for å sikre effektiv prosjektstyring, kontinuitet og suksess.
Nedenfor finner du noen tips og triks for prosjektutvikling og arbeidsflyt i Workiva Scripting.
Workiva Scripting Editor
Workiva Scripting Editor ble opprettet for å hjelpe deg med å integrere produksjonskode i Workiva, overvåke produksjonskjøringer og utføre feilsøking når det oppstår problemer. Det er ikke en omfattende kodeditor, og vi har ingen planer om å gjøre den til det.
Utviklingsmiljø
Hvis du allerede har et utviklingsmiljø og et versjonskontrollsystem, anbefaler vi at du bruker dette til all utvikling og testing av skript.
Sentrale komponenter i et utviklingsmiljø er blant annet Code Editor (populære eksempler er VSCode, PyCharm, Jupyter, etc.) og Version Control System (populære eksempler er GitHub og GitLab). For ikke-ingeniører eller de som foretrekker å ikke jobbe i et kommandolinjegrensesnitt, finnes det lettvektsverktø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 å holde utviklings-/arbeidsversjonene av skriptene dine adskilt fra produksjonsversjonene for å unngå utilsiktet overskriving.
Skriptutvikling
Under utvikling og testing av skriptprosjekter bør du vurdere å følge ledende praksis for Python og versjonskontroll:
Python
Følg PEP 8 - Style Guide for Python Code så langt det er mulig. Konsistent kode er svært gunstig for lesbarhet, vedlikehold og kontinuitet.
For å bygge robuste, pålitelige og skalerbare Python-skript på produksjonsnivå må du sørge for å fokusere på viktige områder, inkludert
- Autentisering: Effektiv oppretting, administrasjon og regenerering av det aktuelle bærertokenet sikrer at bare autoriserte brukere eller systemer får 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 verbose-logging for å fange opp viktige hendelser og statusmeldinger, noe som er avgjørende for å overvåke ytelsen og feilsøke eventuelle problemer.
-
Feilhåndtering: Inkluder logikk for feilhåndtering for å gjøre skriptene mer robuste, pålitelige og brukervennlige ved å håndtere uventede situasjoner på en elegant måte i stedet for å krasje.
Merk: Bruk feilhåndtering for å håndtere uventede situasjoner. Ikke bruk den til å kompensere for eller skjule ytelseskonsekvensene av et suboptimalt skriptdesign (hvis skriptet ditt for eksempel genererer et stort antall 429/Too Many Requests-svar, bør skriptdesignet og arbeidsflyten omarbeides for å optimalisere API-kall, og 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 dokumentasjonsstrenger og eksternt via brukerveiledninger (README), slik at andre utviklere og fremtidige brukere kan forstå og modifisere skriptet på en effektiv måte.
- Versjonssporing: Innlemme semantisk versjonering i skriptprosjektene dine for å hjelpe deg med versjonssporing.
- Navngivningskonvensjoner: Bruk tydelige navnekonvensjoner for skriptene dine (for eksempel:
customername_function_v1_3.py). - Test og verifiser samsvar med regelverket. Bruk Python-pakker som
ruffogflake8til å utføre lint- og formatsjekker. Du kan også dra nytte av de omfattende tilleggsverktøyene og utvidelsene som er tilgjengelige for populære kodeditorer, for å få veiledning og hjelp med kodeformatering og linting. -
AI-kodeassistanse: Det finnes mange gratis og betalte AI-kodeverktøy som du kan bruke til feilsøking og optimalisering.
Merk: Selv om AI-kodeassistenter er nyttige, erstatter de ikke den kunnskapen og ekspertisen som kreves for å utvikle avanserte skript og automatiseringer.
Versjonskontroll
- Ha én enkelt kilde til sannhet: Bruk versjonskontrollsystemet som det sentrale repositoriet og den eneste kilden til sannhet for skriptprosjektene dine. Gjør endringer ofte for å sikre at alt det siste av utviklingsarbeid og testing fanges opp og lagres sentralt.
- Dokumenter endringer fullt ut: Legg til så mange detaljer og støttende informasjon som mulig i alle commits og pull requests i versjonskontrollsystemet for å dokumentere alle endringer (hvem som har gjort endringen, hva som er endret, hvorfor endringen ble gjort osv.)
Beste praksis for arbeidsflyt
Når du utvikler, tester og distribuerer skript, kan du følge beste praksis for arbeidsflyt for å maksimere skriptytelsen og minimere potensielle feil og problemer. Noen av hovedpilarene i utviklingsarbeidsflyten inkluderer
- Utfør all skriptutvikling og -testing i utviklingsmiljøet , ikke i produksjonsmiljøet.
- Overfør skriptet til et staging-arbeidsområde/område der du kan teste skriptet på Workiva.
VIKTIG: Bruk ikke-produksjonsdata for testing. - Skriptet må først distribueres til produksjonsarbeidsområdet for operativ bruk etter at det har blitt 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 pushe endringer manuelt til Workiva fra Workiva Scripting Editor, anbefaler vi på det sterkeste at du automatiserer pushing av koden din fra versjonskontrollsystemet ditt til Workiva ved hjelp av Scripting API-er. Dette er den anbefalte prosessen ettersom automatiseringen sparer tid og reduserer antall feil.
Kjører og overvåker skript
Skript kan utløses direkte fra Skriptredigering, fra kjeder, fra API-er for skripting eller fra integrerte automatiseringer. Uansett hvordan skriptene dine utløses, anbefaler vi at du bruker Scripting Editor til å overvåke kjøringer og feilsøke problemer.
Loggføring
Skriptredigeringsprogrammet inneholder en "Logger"-seksjon. Vi anbefaler at skriptene dine inneholder verbose-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 logging er et eksempel på et loggverktøy som kan konfigureres 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 har også funksjonalitet for å pushe logger til et Workiva-regneark i det samme arbeidsområdet. Dette gir enklere tilgang, raskere analyse og effektiv spørring i loggene. Her er et eksempel på en logg som sendes ut til et Workiva-regneark (regneark- og ark-ID-er er sladdet):
Feilsøking og tilføyelse av nye funksjoner
Hvis det oppstår problemer under bruk av skriptet, anbefaler vi at du utfører feilsøking og oppdatering i utviklingsmiljøet, ikke i produksjonsmiljøet. Når disse rettelsene/oppdateringene er ferdige, testet og lagt inn i versjonskontrollsystemet ditt, kan du trygt pushe 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 tester i utviklingsmiljøet ditt. Når alle skriptoppdateringer er fullført, testet og lagt inn i versjonskontrollsystemet, kan du sende det oppdaterte skriptet til Workiva.