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 scripting di Workiva è stato creato per aiutare a integrare il codice di produzione in Workiva, a monitorare la produzione e a risolvere i problemi iniziali in caso di problemi. Non è un editor di codice completo e non abbiamo intenzione di renderlo tale.
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: Creare, gestire e rigenerare in modo efficace il token del portatore appropriato garantisce che solo gli utenti o i sistemi autorizzati possano accedere alle risorse, ai dati o alle funzionalità dell'area di lavoro.
- 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: Includi la registrazione verbosa per catturare gli eventi chiave e i messaggi di stato, il che è fondamentale per monitorare le prestazioni e risolvere eventuali problemi.
-
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 dipendere da esso per compensare o mascherare le conseguenze sulle prestazioni di un design di script non ottimale (ad esempio, se il tuo script genera un gran numero di risposte 429/Too Many Requests, il design e il flusso di lavoro dello script dovrebbero essere modificati per ottimizzare le chiamate API, non dovresti fare affidamento sulla gestione efficace di un gran numero di 429 per 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:
- Conduci tutti i test e lo sviluppo dello script nell'ambiente di sviluppo e non nell'ambiente di produzione.
- Trasferisci lo script in un'area/spazio di lavoro di staging dove potrai testare lo script su Workiva.
IMPORTANTE: Usa i dati non di produzione per i tuoi test. - Distribuisci il tuo script nell'area di lavoro di produzione solo dopo averlo testato con successo.
Trasferimento del codice a Workiva
Una volta che lo sviluppo principale e i test sono stati completati e tutto funziona come previsto, puoi trasferire il tuo codice a Workiva. Anche se puoi inviare manualmente le modifiche a Workiva dall'editor di scripting di Workiva, ti consigliamo vivamente di automatizzare l'invio del codice dal tuo sistema di controllo della versione a Workiva utilizzando le API di scripting. Questa è la procedura consigliata in quanto l'automazione fa risparmiare tempo e riduce gli errori.
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 scripting include una sezione "Logs"; consigliamo ai tuoi script di incorporare la registrazione verbosa per fornire informazioni dettagliate e complete sulle operazioni dello script. Queste informazioni sono spesso molto utili per il debug, il monitoraggio e la comprensione delle operazioni dello script. Il pacchetto standard Python logging è un esempio di utilità di log che può essere impostata per fornire informazioni utili sulle operazioni di script (ad esempio: timestamp, livello di log, messaggio, ecc.). Assicurati di utilizzare i vari livelli di log (INFO, DEBUG, ERROR, ecc.) e di includere messaggi di log dettagliati e utili.
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.