Modulo di scripting

Il Modulo di Scripting integra i motori Octave e Python, consentendo agli utenti di scrivere ed eseguire calcoli usando uno dei due linguaggi all’interno di Requirements & Systems Portal. Il modulo è progettato per eseguire calcoli complessi che non sono possibili tramite il ValiEngine standard.

Se gli utenti desiderano manipolare altri oggetti oltre ai Valis numerici, devono utilizzare la Python API di Requirements & Systems Portal. Esempi di casi d’uso includono:

• Creare un valore e aggiungerlo in blocco a più Block

• Apportare modifiche in blocco agli identificatori dei requisiti

• Eseguire simulazioni usando Python

• Convertire le unità dei valori di potenza in kW.

• Eseguire un comportamento di workflow personalizzato basato su trigger automatici

Flusso del Modulo di Scripting

Per utilizzare il modulo, l’utente crea un nuovo script, aggiunge input/output, scrive il codice in .m o .py ed esegue il codice per ottenere l’output desiderato.

Workflow del Modulo di Scripting.

Creazione di un nuovo script

Per creare un nuovo script, fare clic sull’opzione “+ Script” (1) all’interno dei moduli di scripting.

Verrà visualizzata una finestra di dialogo che consente di inserire il nome dello script, selezionare il motore (Octave o Python) e avere opzioni aggiuntive da usare/riutilizzare dai template.

Opzione Crea nuovo script

Una volta creato un nuovo script, gli utenti possono anche creare file aggiuntivi di tipo Text, JSON e YAML per i propri script. Per aggiungere un nuovo file, fare clic sull’opzione “+Add file” (1), aggiungere un nome e selezionare un tipo di file nella finestra di dialogo. In questo modo viene aggiunto un file allo script.

Per utilizzare uno qualsiasi dei file extra creati, gli utenti devono includere le seguenti due righe di codice all’inizio del file main.py:

import site
site.addsitedir('script_code/')

Dopo queste due righe, qualsiasi file extra può essere richiamato usando l’istruzione standard import statement.

Gestione dei segreti:

Per non esporre l’uso delle credenziali necessarie quando si utilizzano script che si connettono alla nostra API o a quella di altri strumenti, è possibile definire variabili segrete personali che possono essere richiamate in fase di esecuzione dello script, senza rischiare di esporle ad altri utenti del deployment memorizzandole nei file dello script.

Come e dove aggiungerli

I segreti possono essere definiti nel pannello Settings sotto User Secrets. Questi segreti possono essere riutilizzati all’interno dello script per accedere a Requirements & Systems Portal. Ecco un breve video che mostra come creare i segreti utente.

Come suggerisce il nome, questi segreti sono univoci per ciascun utente e accessibili solo da chi li ha definiti.

Come usare i Secrets in uno script

Importando il nome del segreto dal modulo “.settings”, gli utenti possono usare i segreti per l’autenticazione all’interno degli script.

from .settings import USERNAME, PASSWORD  #case sensitive, use the same word used in the user secrets.

LOGIN_DATA = {
    'domain': 'API_URL',
    'username': USERNAME,
    'password': PASSWORD
}

In fase di esecuzione, gli script recupereranno il valore di queste variabili dai segreti definiti nelle impostazioni utente dell’utente che attiva lo script, e dipenderanno dai permessi di quell’utente. Gli script non devono contenere funzioni di output di queste variabili, per non esporre i segreti utente.

Gli script di uso generale impostati per essere attivati con automazioni possono essere configurati con autenticazione da un utente di livello Admin che può rimuovere i permessi di lettura a tutti gli altri utenti, mantenendo così lo script nascosto.

Sistema di coda

Con il sistema di coda, gli utenti possono essere certi che i loro script verranno sempre eseguiti, soprattutto se automazioni predefinite attivano regolarmente script di workflow personalizzati. Per questo, accedere alla sezione “Runs”. È possibile visualizzare tutte le esecuzioni di tutti gli script oppure le esecuzioni di uno script specifico.

Tutte le esecuzioni degli script verranno ora salvate nel deployment e potranno essere consultate per singolo script o per tutti gli script selezionando l’opzione “All scripting” nella parte superiore dell’albero del Modulo Script.

È possibile interrompere uno script in esecuzione facendo clic sul pulsante “Stop” nel menu a discesa Actions.

Azione Stop per uno script.

Gestione dei permessi

Gli script hanno permessi propri che possono essere gestiti direttamente dal Modulo di Scripting oppure dal Modulo Progetto sotto “Permissions”.

Eseguire script da una dashboard

Gli utenti possono anche creare dashboard di interazione personalizzate usando pulsanti “Run Script”. Questi sono simili ai pulsanti Request precedentemente disponibili usati per attivare chiamate REST, ma possono essere configurati per eseguire uno o più script con la pressione di un pulsante.

Utilizzando la Python API negli script richiamati, è possibile configurare dashboard di interazione personalizzate in cui elementi come caselle di testo standard possono essere usati come campi di input e output per uno script, che può quindi anche influenzare, direttamente e indirettamente, altri elementi visualizzati.

Per farlo, andare nel Modulo Progetto e poi in “Dashboards”. Quindi entrare nella dashboard personalizzata e fare clic sull’icona Plus nell’angolo in basso a destra. Poi selezionare l’opzione “Run script” dal menu a discesa “Actions”.

Questo crea un pulsante da cui è possibile eseguire script che aggiornano blocchi specifici della dashboard.

Un caso d’uso interessante è quello in cui i test run passati e falliti vengono conteggiati e visualizzati in un blocco di testo sulla stessa dashboard.

Script & Automazioni

Le automazioni preimpostate possono attivare script. Ad esempio, un calcolo complesso può essere impostato per essere eseguito automaticamente se i suoi input definiti vengono modificati. Inoltre, usando la Python API di Requirements & Systems Portal, è anche possibile programmare comportamenti complessi su misura per creare workflow personalizzati.

Le automazioni non solo attiveranno gli script, ma trasmetteranno anche le informazioni su quali oggetti le hanno attivate, in modo che gli script possano agire direttamente su tali oggetti. Le informazioni sugli oggetti sono rese disponibili nella variabile dizionario “kwargs”, sotto la chiave ‘triggered_objects', come nel seguente esempio:

object_data = kwargs['triggered_objects'][0]

Le automazioni eseguiranno gli script anche se attivate da utenti che non hanno i permessi per visualizzare tali script, consentendo così la personalizzazione dei workflow e dei calcoli da parte degli utenti admin, limitando al contempo l’accesso al codice sottostante, come modelli matematici e fisici proprietari.

Esempi di script di workflow sono disponibili nella cartella templates del repository pubblico valifn.

Immagini Valifn personalizzate

Gli utenti on-prem dispongono della funzionalità aggiuntiva di personalizzare la propria istanza valifn per eseguire qualsiasi pacchetto Python desiderino, a condizione che l’hardware del server sia in grado di gestirlo. Gli utenti on-prem avranno anche la possibilità di gestire quale immagine valifn utilizzare in fase di esecuzione dello script.

Come mostrato, questa opzione è disponibile come campo di testo nelle General Settings di ciascun singolo script.

Come creare un’immagine personalizzata

Ulteriori istruzioni su come configurare le proprie immagini valifn sono disponibili nelle pagine di documentazione del repository pubblico:

• Usage · valispace/valifn-octave Wiki (github.com)

• Usage · valispace/valifn-python Wiki (github.com)

Esempi di script Python

Esempi di script utilizzabili sono disponibili sia nel progetto di esempio Valicopter 5000 di un deployment (nuovi deployment) sia nel repository pubblico Github di ValiFn.

Questi esempi possono essere attivati manualmente o tramite automazioni (esclusivamente in alcuni casi) e possono essere usati così come sono oppure modificati dagli utenti per eseguire qualsiasi comportamento personalizzato.

Molti di questi esempi sono stati creati come dimostrazione delle possibilità del modulo di scripting e delle automazioni per creare workflow automatizzati su misura. Gli utenti sono incoraggiati a personalizzare qualsiasi script esistente in base alle proprie esigenze e a condividere eventuali script di uso generale e miglioramenti nel repository pubblico di ValiFn.

Avviso di sospetto per i figli (Automazione)

Motivazione

Questo script viene attivato da un’automazione che deve essere impostata per attivarsi in caso di modifica di un requisito esistente, poiché lo script agisce sulle proprietà del requisito modificato. L’azione attualmente definita consiste nell’inserire una discussione in ciascuno dei suoi figli (se presenti) con un messaggio personalizzato relativo allo stato di modifica del requisito padre.

Personalizzazione suggerita

Altre azioni possibili potrebbero essere creare un task o aggiungere il requisito modificato a una review.

Azioni correnti

• Verifica se il requisito che ha attivato l’automazione preimpostata ha figli

• Se ha figli, pubblica una discussione in ciascun requisito figlio indicando che il padre è stato aggiornato.

• La discussione include l’identità dell’utente che ha modificato il requisito, attivando così l’automazione.

Nuovo task (Automazione)

Motivazione

Durante la creazione di un nuovo Block, un potenziale cliente ha richiesto che i task venissero creati automaticamente e assegnati a un utente specifico. In questo esempio, un’automazione preimpostata attivata dalla creazione di un nuovo Block creerà un nuovo task e vi assegnerà un utente. Era stato concepito per aggiungere l’oggetto che attiva l’evento come input, ma quello sviluppo non è stato finalizzato.

Personalizzazione suggerita

Usa il kwargs['triggered_objects'][0] per estrarre le informazioni dell’oggetto che ha attivato l’automazione e aggiungerle al campo di input dell’attività.

Azioni correnti

• Pubblica una nuova attività assegnata a un utente specificato.

Statistiche dei requisiti

Motivazione

Un semplice esempio di come si possa creare un contatore più personalizzato con più valori statistici rispetto a quelli forniti nei blocchi predefiniti disponibili nei documenti Dashboard e Analysis. Può essere eseguito manualmente oppure impostato per essere eseguito da un’automazione ogni volta che un requisito viene creato, modificato o eliminato.

Personalizzazioni suggerite

1. Prendi le informazioni estratte sui requisiti e ricava da esse statistiche più complesse confrontandole con valori aggiornati in precedenza. Ogni valore può indicare di quanto è aumentato/diminuito espresso in percentuale.

2. Confronta le statistiche di deployment eseguendo singolarmente lo script in ciascun progetto e aggiungendo un’istanza speciale che ricava statistiche da ogni progetto, visualizzandole in una dashboard.

3. Imposta un avviso personalizzato per gli amministratori del progetto se le statistiche mostrano un calo improvviso del numero di requisiti, segnalando una possibile modifica drastica al progetto.

Azioni correnti

• Costruisce statistiche complessive dei requisiti per un singolo progetto nel deployment.

• Applica i risultati a Valis precreati.

Generazione delle specifiche

Motivazione

Uno script di esempio che dimostra la potenza della Python API per creare report completamente automatizzati. Sebbene lo script principale sia disponibile anche nella pagina della documentazione delle integrazioni, questa particolare versione è stata adattata per essere eseguita dal modulo di scripting del deployment.

Può essere attivato da un’automazione o manualmente.

Personalizzazioni suggerite

1. Crea un report completo adattando l’attuale processo di recupero dei requisiti per estrarre Blocks e altri oggetti da compilare nel report

2. Aggiungi altri campi personalizzabili, che possono essere recuperati da blocchi di testo personalizzati della dashboard, da cui può anche essere attivato.

3. Modifica il file di output finale in un PDF invece che in un file Word modificabile.

Azioni correnti

• Prende un file Word come modello, da un determinato deployment, e restituisce come output file generati, tanti quante sono le specifiche, collocati nel Files Management del deployment (vedi Esportazione delle specifiche basata su modello Microsoft Word per maggiori dettagli).

Dashboard di test

Motivazione

I contatori della dashboard non hanno ancora raggiunto il modulo Testing e non esistono ancora contatori automatici per i test. Questo script è stato sviluppato come proof of concept per un contatore personalizzato che non è ancora stato implementato. Inizialmente era stato concepito per essere eseguito tramite attivazione manuale da un pulsante Run Script in una Dashboard.

Personalizzazioni suggerite

1. Espandi le statistiche dei test che vengono ripubblicate nelle Dashboard.

2. Se un’esecuzione di test ha esito positivo, pubblica il risultato in un’attività collegata e cambia il suo stato in “Done”.

Azioni correnti

• Restituisce una stringa, inserita in blocchi di testo predefiniti della Dashboard, con statistiche calcolate sull’esecuzione dei test.

• Può ricevere input da un’automazione oppure può essere attivato manualmente.