L'utilizzo di Workiva Scripting e delle API può semplificare notevolmente le operazioni e i flussi di lavoro. Come per tutti i progetti di scripting, seguire le migliori pratiche per lo sviluppo del codice e il controllo delle versioni consente una gestione efficace del progetto, una continuità e un successo.
Di seguito sono riportati alcuni suggerimenti e trucchi di Workiva Scripting per lo sviluppo di progetti e flussi di lavoro.
Editor di scripting di Workiva
L'editor di script di Workiva ti aiuta a gestire il codice in Workiva, eseguire script, monitorare le esecuzioni in produzione e risolvere i problemi. Per lo sviluppo avanzato, i test, il controllo della qualità del codice, il debug e il controllo delle versioni, utilizzare un ambiente di sviluppo dedicato.
Ambiente di sviluppo
Se disponi già di un ambiente di sviluppo aziendale e di un sistema di controllo delle versioni, ti consigliamo di utilizzarlo per lo sviluppo e i test di scripting.
I componenti chiave di un ambiente di sviluppo includono un Code Editor (esempi popolari sono VSCode, PyCharm, Jupyter, ecc.) e un Version Control System (esempi popolari sono GitHub e GitLab). Per i non ingegneri o per coloro che preferiscono non lavorare con un'interfaccia a riga di comando, esistono strumenti leggeri come GitHub Desktop e SourceTree che possono semplificare il lavoro nei sistemi di controllo delle versioni.
Se non disponi di un ambiente di sviluppo, prendi in considerazione la possibilità di crearne uno. Nel frattempo, assicurati di salvare le copie dei tuoi script (prima, durante e dopo qualsiasi modifica/aggiornamento) e di tenere le versioni di sviluppo/lavoro dei tuoi script separate da quelle di produzione per ridurre le sovrascritture accidentali.
Sviluppo di scripting
Durante lo sviluppo e il collaudo di progetti di scripting, considera l'opportunità di seguire le principali pratiche di Python e di controllo delle versioni:
Python
Segui il più possibile PEP 8 - Guida allo stile del codice Python. La coerenza del codice è molto utile per la leggibilità, la manutenibilità e la continuità.
Per creare script Python robusti, affidabili e scalabili a livello di produzione, assicurati di concentrarti su aree chiave quali:
- Autenticazione : Utilizza un'autorizzazione API per richiedere token di accesso a breve durata per le API di Workiva. Concedere solo gli ambiti richiesti dall’integrazione, proteggere l’ID cliente e la chiave segreta e non memorizzare mai le credenziali nei log. Per le istruzioni, consultare Configurazione dell'API Workiva .
- Modularità: Suddividi gli script di grandi dimensioni in unità più piccole, indipendenti e riutilizzabili (funzioni, classi, moduli/file). Questo rende lo script più facile da leggere, testare, debuggare e mantenere nel tempo.
- Registrazione: Includere una registrazione utile e strutturata per rilevare eventi importanti, cambiamenti di stato, avvisi ed errori. Non registrare mai credenziali, token di accesso, dati inseriti durante l'esecuzione o altre informazioni sensibili.
-
Gestione degli errori: Includi una logica di gestione degli errori per rendere gli script più robusti, affidabili e facili da usare, gestendo con grazia le situazioni inaspettate invece di bloccarsi.
Nota: Usa la gestione degli errori per affrontare situazioni inaspettate. Non fare affidamento su di esso per compensare o mascherare le ripercussioni sulle prestazioni derivanti da una progettazione non ottimale dello script (ad esempio, se lo script genera un numero elevato di risposte
429: Troppe richieste ; in tal caso, la progettazione dello script e il flusso di lavoro dovrebbero essere riorganizzati per ottimizzare le chiamate API; non dovreste fare affidamento su una gestione efficace di un numero elevato di risposte 429 per garantire il successo dello script). - Documentazione: Spiega cosa fa il codice e come usarlo (sia internamente tramite commenti e documenti, sia esternamente tramite guide per l'utente (README)), consentendo agli altri sviluppatori e ai futuri utenti di comprendere e modificare lo script in modo efficace ed efficiente.
- Tracciamento delle versioni: Incorpora il versioning semantico nei tuoi progetti di scripting per facilitare il tracciamento delle versioni.
- Convenzioni di denominazione: Usa convenzioni di denominazione chiare per i tuoi script (ad esempio:
customername_function_v1_3.py). - Prova e verifica la conformità del codice. Usa i pacchetti Python come
ruffeflake8per eseguire controlli di lint e di formato. Puoi anche sfruttare i numerosi strumenti aggiuntivi e le estensioni disponibili per gli editor di codice più diffusi per ottenere guide e assistenza con la formattazione del codice e il linting. -
Assistenza per il codice AI: sono disponibili molti strumenti gratuiti e a pagamento per il codice AI che puoi sfruttare per aiutarti nel debug e nell'ottimizzazione.
Nota: Sebbene siano utili, gli assistenti al codice AI non sostituiscono le conoscenze e le competenze necessarie per sviluppare script e automazioni avanzate.
Controllo delle versioni
- Avere un'unica fonte di verità: Usa il tuo sistema di controllo delle versioni come repository centrale e unica fonte di verità per i tuoi progetti di scripting. Esegui spesso il commit delle modifiche per assicurarti che tutto il lavoro di sviluppo e di test più recente venga acquisito e conservato a livello centrale.
- Documenta completamente le modifiche: Aggiungi il maggior numero possibile di dettagli e informazioni di supporto in tutti i commit e le richieste di pull del tuo sistema di controllo delle versioni per documentare tutte le modifiche (chi ha apportato la modifica, di cosa si tratta, perché è stata fatta, ecc.)
Migliori pratiche per il flusso di lavoro
Quando si sviluppano, si testano e si distribuiscono gli script, seguire le best practice del flusso di lavoro aiuta a massimizzare le prestazioni degli script e a ridurre al minimo i potenziali errori e problemi. Alcuni dei principali pilastri del flusso di lavoro di sviluppo includono:
- Eseguire lo sviluppo iniziale e i test unitari nel proprio ambiente di sviluppo.
- Trasferisci lo script in un'area di lavoro di staging o in un'altra area controllata per eseguire i test di integrazione in Workiva. Utilizzare dati non di produzione.
- Distribuire lo script nell'ambiente di produzione solo dopo aver completato i test.
Trasferimento del codice a Workiva
Una volta completate le fasi di sviluppo e collaudo, trasferisci il codice su Workiva. È possibile aggiornare le fonti manualmente nell'Editor di script, ma consigliamo vivamente di automatizzare la distribuzione dal proprio sistema di controllo delle versioni tramite l'API di scripting di Workiva. L'implementazione automatizzata consente di risparmiare tempo, riduce gli errori manuali e aiuta a mantenere Workiva sincronizzato con la vostra fonte soggetta a controllo di versione.
L'implementazione automatizzata del codice sorgente richiede un'autorizzazione API con l'ambito script:write . Se l'implementazione prevede anche il recupero o la verifica delle fonti, è necessario lo script : read . Invia X-Version: 2026-01-01 con ogni richiesta API. Per le istruzioni relative alle autorizzazioni, consultare Configurazione dell'API di Workiva . Per le operazioni supportate, consultare la guida all’API di scripting di all’indirizzo .
Esecuzione e monitoraggio degli script
Gli script possono essere attivati direttamente dall'editor di scripting, dalle catene, dalle API di scripting o dalle automazioni integrate. Indipendentemente dal modo in cui gli script vengono attivati, ti consigliamo di utilizzare l'Editor di script per monitorare le esecuzioni e risolvere i problemi.
Registrazione
L'Editor di script include una sezione dedicata ai log di . Raccomandiamo vivamente che i vostri script utilizzino una registrazione dettagliata e strutturata per documentare le operazioni importanti, i cambiamenti di stato, gli avvisi e gli errori. Una corretta registrazione dei log è fondamentale per monitorare le prestazioni, risolvere i problemi e comprendere il comportamento degli script.
Il pacchetto standard di Python per la registrazione degli eventi ( ) può includere informazioni utili quali timestamp, livelli di log e messaggi. Utilizzare livelli appropriati, quali DEBUG , INFO , WARNING e ERROR , per controllare la quantità di informazioni generate. Non registrare credenziali, token di accesso, dati inseriti durante l'esecuzione o altre informazioni sensibili.
Molti utenti avanzati includono anche la funzionalità di inviare i log a un foglio di lavoro Workiva designato nello stesso spazio di lavoro. Ciò consente un accesso più semplice, un'analisi più rapida e un'interrogazione efficiente dei registri. Ecco un esempio di output di log in un foglio di lavoro Workiva (gli ID del foglio di lavoro e del foglio sono stati offuscati):
Debug e aggiunta di nuove funzionalità
Se si verificano problemi durante le operazioni dello script, ti consigliamo di eseguire il debug e l'aggiornamento nel tuo ambiente di sviluppo, non in quello di produzione. Una volta che le correzioni/aggiornamenti sono stati completati, testati e inseriti nel sistema di controllo delle versioni, puoi inviare lo script aggiornato a Workiva in tutta sicurezza.
Lo stesso flusso di lavoro deve essere utilizzato per aggiungere nuove funzionalità agli script esistenti: esegui tutti gli aggiornamenti e i test nel tuo ambiente di sviluppo. Una volta che tutti gli aggiornamenti dello script sono stati completati, testati e inseriti nel sistema di controllo della versione, puoi inviare lo script aggiornato a Workiva.