Workiva-skripting: Beste praksis for utviklingsprosesser

Å 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 hjelper deg med å administrere kode i Workiva, kjøre skript, overvåke produksjonskjøringer og feilsøke problemer. For avansert utvikling, testing, linting, feilsøking og versjonskontroll, bruk et dedikert utviklingsmiljø.

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 : Bruk en API-bevilgning for å be om kortvarige tilgangstokener for Workiva API-er. Gi kun omfangene som kreves av integrasjonen, beskytt klient-ID-en og hemmeligheten, og lagre aldri legitimasjon i logger. For instruksjoner, se Workiva API-oppsett .
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 nyttig, strukturert logging for å fange opp viktige hendelser, statusendringer, advarsler og feil. Logg aldri påloggingsinformasjon, tilgangstokener, kjøretidsinndata eller annen sensitiv informasjon.
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 ruff og flake8 for å 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 innledende utvikling og enhetstesting i utviklingsmiljøet ditt.
Overfør skriptet til et testområde eller et annet kontrollert område for integrasjonstesting i Workiva. Bruk ikke-produksjonsdata.
Distribuer skriptet til produksjonsarbeidsområdet først etter at testingen er fullført.

Overføring av kode til Workiva

Når utviklingen og testingen er fullført, overfør koden til Workiva. Du kan oppdatere kilder manuelt i skriptredigereren, men vi anbefaler på det sterkeste å automatisere distribusjonen fra versjonskontrollsystemet ditt med Workiva Scripting API. Automatisert utrulling sparer tid, reduserer manuelle feil og bidrar til å holde Workiva synkronisert med din versjonskontrollerte kilde.

Automatisert kildedistribusjon krever en API-tillatelse med omfanget script:write . Hvis distribusjonen også henter eller verifiserer kilder, krever den script:read . Send X-versjon: 2026-01-01 med hver API-forespørsel. For instruksjoner om tildeling, se Workiva API-oppsett . For støttede operasjoner, se Scripting API-veiledningen .

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 på det sterkeste at skriptene dine bruker detaljert, strukturert logging for å registrere viktige operasjoner, statusendringer, advarsler og feil. God logging er viktig for å overvåke ytelse, feilsøke problemer og forstå skriptoppførsel.

Standard Python-loggpakken kan inneholde nyttig informasjon som tidsstempler, loggnivåer og meldinger. Bruk passende nivåer, som for eksempel DEBUG , INFO , WARNING og ERROR , for å kontrollere mengden informasjon som produseres. Ikke loggfør påloggingsinformasjon, tilgangstokener, kjøretidsinndata eller annen sensitiv informasjon.

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.

Ressurser

Workiva kundestøttesenter