Scrittura di script Python e HCL in Robot

L'applicazione Robot fornisce script nativi basati sul cloud che è possibile utilizzare per l'analisi dei dati o per automatizzare parti del flusso di lavoro Diligent One della propria organizzazione. La scrittura di script in Robot combina tutta la potenza di Python e di tutte le librerie supportate con HighBond Command Language (HCL), la nostra libreria Python personalizzata per l'analisi dei dati incentrata sul dominio e l'automazione Diligent One.

Robot continua a supportare l'analisi e l'automazione dei dati utilizzando ACLScript e gli script caricati da Analytics. In questo modo è possibile trarre vantaggio da qualsiasi investimento esistente in ACL (Audit Command Language) e da tutte le possibilità offerte da Python, un linguaggio di programmazione standard del settore, nonché da HCL.

Tre tipi di robot

L'applicazione Robot contiene tre tipi di robot. Sebbene simili sotto molti aspetti, i diversi tipi di robot supportano diversi scenari di scrittura di script:

• Robot ACL Supporta l'analisi completa dei dati con script caricati da Analytics e attività pianificate. Gli script possono essere eseguiti nel cloud o on-premise.

• Robot HighBond Supporta l'analisi dei dati su vasta scala con script Python/HCL creati direttamente nel robot e attività pianificate. Gli script possono essere eseguiti solo nel cloud.

• Robot del workflow Supporta l'analisi leggera dei dati o l'automazione di parti del flusso di lavoro di Diligent One, con script Python/HCL creati direttamente nel robot e attività pianificate o basate su eventi. Gli script possono essere eseguiti solo nel cloud.

  Nota

  Per accedere ai robot del workflow, è necessario avere un'assegnazione come tipo di utente Amministratore di sistema con una sottoscrizione Professionale.

  L'obiettivo è che un amministratore di sistema con una sottoscrizione Professionale possa configurare le attività nei robot del workflow attivate dagli eventi Diligent One. Questa funzionalità è ancora in fase di sviluppo e non è ancora disponibile.

Confronto tra i tipi di robot

I tre tipi di robot sono concepiti per scopi diversi e sono funzionalmente separati l'uno dall'altro. Non è possibile combinare ACLScript e Python/HCL in un unico robot.

Caratteristiche del robot	robot ACL	robot HighBond	robot del workflow
Finalità prevista	analisi e automazione dei dati		automazione della piattaforma Diligent One
Lingua supportata	ACLScript	Python Pandas, NumPy, Requests e altre librerie Python standard Libreria Python personalizzata HCL (HighBond Command Language)
Luogo di creazione dello script	Analytics	Robot
Luogo di esecuzione dello script	cloud on-premise	cloud
Opzioni per l'esecuzione di un'attività	pianificato esecuzione ad hoc (manuale)		attivato da evento Diligent One pianificato esecuzione ad hoc (manuale)
Tempo massimo di esecuzione dell'attività	Agente Robot basato su cloud: 60 minuti Agente Robot on-premise: controllato dalla rete del cliente	Nessun limite Nota È previsto un limite di 12 ore, ma non è ancora stato implementato. Se è necessario interrompere un'attività in esecuzione da troppo tempo, è possibile fare clic su Annulla esecuzione dell'attività nella scheda Esecuzioni dell'attività.	15 minuti
Numero massimo di attività eseguite contemporaneamente	5	5	50
Autorizzazioni obbligatorie	essere un collaboratore per il robot grado di accesso controllato dal ruolo del robot collaboratore (proprietario, redattore, revisore)		Tipo di utente amministratore di sistema con sottoscrizione Professionale

Editor di script di Robot

I robot HighBond e i robot del workflow contengono un editor di script integrato per la creazione di script Python/HCL e la loro esecuzione interattiva (manuale). L'editor di script è modellato sull'applicazione Jupyter Notebook, un ambiente di sviluppo molto diffuso nella comunità degli esperti di data science. L'editor di script utilizza un Approccio basato su celle alla creazione di script.

Approccio basato su celle alla creazione di script

La caratteristica più evidente dell'editor di script è la possibilità di utilizzare più celle per contenere i singoli blocchi di codice che compongono un singolo script. Se non si ha familiarità con Jupyter Notebook, l'approccio basato su celle per la creazione di script potrebbe inizialmente sembrare complicato. Infatti, è facile da usare e offre vantaggi che si apprezzano rapidamente.

Caratteristiche principali della creazione di script basati su celle

• Le celle multiple sono facoltative Non è necessario utilizzare più celle se non lo si desidera. È possibile creare ed eseguire un intero script utilizzando una singola cella.

• Divisioni logiche: le celle consentono di suddividere uno script in blocchi logici a propria scelta e di eseguire manualmente i blocchi singolarmente, in qualsiasi ordine o come sequenza completa.

  Ad esempio, una disposizione di base a quattro celle per uno script potrebbe essere:

  • prima cella: importare librerie Python

  • seconda cella: importare dati

  • terza cella: eseguire l'analisi sui dati

  • quarta cella: restituire i risultati dell'analisi

• Vantaggi delle celle: l'utilizzo delle celle per lo sviluppo degli script presenta i seguenti vantaggi:

  • È possibile lavorare su singole celle in modo isolato, testandole e migliorandole, ignorando temporaneamente la logica di script contenuta in altre celle.

  • Dopo aver eseguito una volta le celle di importazione iniziali, non è più necessario continuare a eseguirle mentre si sviluppano e si testano ripetutamente le celle successive.

  • È possibile utilizzare le celle per imporre un ordine visivo agli script, rendendo più facile per l'utente o per qualcun altro vedere e comprendere la relazione tra i diversi blocchi logici.

• Indicatore di sequenza Accanto a ogni cella è presente un indicatore numerico che mostra l'ordine in cui la cella è stata eseguita durante una sessione di scrittura di script. Per esempio: [7].

  Quando si esegue una cella, l'indicatore aumenta, tenendo conto di tutte le altre celle eseguite nel frattempo. Quindi, ad esempio, un indicatore potrebbe cambiare da [7] a [10] se sono state eseguite altre due celle nel frattempo o un'altra cella due volte.

• Memoria di sessione e valori memorizzati: i dataframe e i valori delle variabili conservati nella memoria durante una sessione di scrittura di script vengono aggiornati in base alla sequenza in cui si eseguono le celle.

  In genere, le celle vengono strutturate in modo che vengano eseguite in sequenza dall'alto verso il basso durante l'esecuzione pianificata e non supervisionata di uno script. Alcuni dataframe o valori variabili possono essere aggiornati progressivamente in base alla logica dello script. Se si eseguono manualmente le celle fuori ordine, lo stato corrente di un dataframe o di un valore variabile potrebbe non essere quello presunto e potrebbe verificarsi un errore o un risultato impreciso. Per ripristinare il dataframe o il valore della variabile allo stato previsto, è sufficiente eseguire nuovamente tutte le celle che fanno riferimento al dataframe o alla variabile nell'ordine previsto.

• Visualizzazione dell'output della cella Per impostazione predefinita, l'esecuzione di una cella visualizza solo l'output dell'ultima espressione nella cella. Per visualizzare il risultato di più espressioni in una cella, è possibile inserire le espressioni in celle separate. Tuttavia, un approccio più comodo consiste nell'impostare un'opzione di configurazione nell'editor di script.

  • Configurare le celle per visualizzare l'output di tutte le espressioni:

    from IPython.core.interactiveshell import InteractiveShell
    InteractiveShell.ast_node_interactivity = "all"

  • Reimpostare le celle per visualizzare l'output solo dell'ultima espressione:

    from IPython.core.interactiveshell import InteractiveShell
    InteractiveShell.ast_node_interactivity = "last_expr"

  Consiglio

  È possibile utilizzare le impostazioni di configurazione per passare da una modalità all'altra a seconda delle esigenze. Per ulteriori opzioni di configurazione per l'output delle celle, consultare la documentazione online di Jupyter o IPython.

Tasti di scelta rapida nell'editor di script di Robot

I tasti di scelta rapida nell'editor di script garantiscono praticità e velocità durante lo sviluppo di uno script. Nell'editor di script, per visualizzare un elenco dei tasti di scelta rapida disponibili, utilizzare uno dei seguenti metodi:

• Premere Ctrl+/.

• Fare clic sull'icona Tasto di scelta rapida nella barra del titolo.

Di seguito sono elencate i tasti di scelta rapida disponibili.

Tasto di scelta rapida	Azione
Ctrl + Maiusc + Invio	Esegui la cella selezionata
Ctrl + Maiusc + M	Esegui tutte le celle in sequenza
Ctrl + Maiusc + Y	Eseguire la cella selezionata e tutte le celle sopra
Ctrl + Maiusc + U	Eseguire la cella selezionata e tutte le celle sotto
Ctrl + Maiusc + I	Interrompere l'esecuzione dello script
Ctrl + Maiusc + K Ctrl + Maiusc + Freccia su	Selezionare la cella sopra
Ctrl + Maiusc + J Ctrl + Maiusc + Freccia giù	Selezionare la cella sotto
Ctrl + Maiusc + H Ctrl + Maiusc + Home	Selezionare la prima cella
Ctrl + Maiusc + L Ctrl + Maiusc + Fine	Selezionare l'ultima cella
Ctrl + Maiusc + A	Aggiungere una cella sopra
Ctrl + Maiusc + B	Aggiungi cella sotto
Ctrl + Maiusc + D	Elimina la cella selezionata
Ctrl + Maiusc + Z	Sposta la cella in alto
Ctrl + Maiusc + X	Sposta la cella in basso

Funzionalità di Jupyter Notebook non incluse nell'editor di script di Robot

Come accennato in precedenza, l'editor di script di Robot è modellato sull'applicazione Jupyter Notebook. Queste funzionalità di Jupyter non sono incluse nell'editor di script, anche se alcune di esse potrebbero esserlo nel tempo man mano che il prodotto continua a evolversi:

• Operazioni a livello di cella:

  • annullare/ripristinare operazioni sulle celle

  • copiare/incollare le celle

  • dividere/unire le celle

• Celle Markdown (per il contenuto di testo)

Salvare l'output dello script in un file di log

Quando si esegue uno script Python/HCL utilizzando un'attività del robot, è possibile salvare l'output dello script nel file di log che accompagna ogni esecuzione dell'attività. Il log è un file JSON con lo stesso nome dell'attività (task_name.json).

Per abilitare l'opzione, selezionare Salva l'output dello script nel file di log dell'esecuzione dell'attività quando si salva e si esegue la conferma di una versione di uno script. L'opzione è configurabile separatamente per ogni versione di uno script, quindi se si desidera salvare l'output dello script, assicurarsi di selezionare l'opzione per la versione specifica dello script eseguita dall'attività.

L'output dello script si riferisce a tutto ciò che è contenuto nel flusso stdout prodotto da uno script. In genere, stdout è tutto ciò che lo script stampa o visualizza sullo schermo quando si esegue uno script in modo interattivo. In pratica, selezionando Salva l'output dello script nel file di log dell'esecuzione dell'attività, si acquisisce in modo permanente tutto ciò che viene visualizzato sullo schermo. Questo output acquisito può essere utile da rivedere durante lo sviluppo e la risoluzione dei problemi degli script.

Informazioni aggiuntive:

• L'opzione si applica solo alle attività Anche se si seleziona Salva l'output dello script nel file di log dell'esecuzione dell'attività nell'editor di script di Robot, l'opzione si applica solo agli script eseguiti da un'attività del robot. L'opzione non ha alcun effetto quando si esegue uno script in modo interattivo nell'editor di script.

• Messaggi di errore nel file di log di esecuzione dell'attività: i messaggi di errore Python (flusso stderr) sono sempre inclusi nel file di log di esecuzione dell'attività, indipendentemente dalla configurazione di Salva l'output dello script nel file di log dell'esecuzione dell'attività.

• Accesso al file di log delle esecuzioni delle attività Per ogni attività eseguita nella scheda Esecuzioni dell'attività è disponibile un file di log delle esecuzioni dell'attività. Selezionare un'esecuzione dell'attività e, nel pannello laterale Dettagli dell'esecuzione dell'attività, il file di log verrà visualizzato nella sezione Output. È possibile scaricare il file sul computer per la revisione.

Eseguire la transizione da ACLScript a Python e HCL

Python è un linguaggio di programmazione di uso generale ed è significativamente più complesso di ACLScript, un linguaggio di scrittura di script relativamente semplice, originariamente progettato per il dominio dell'analisi di audit.

Il nostro obiettivo è che nel tempo HCL replichi molti dei comandi e delle funzioni disponibili in ACLScript. Per iniziare a usare HCL, la nostra libreria Python personalizzata, è necessario avere almeno competenze di base in Python. Il consiglio per chi vuole passare da ACLScript a Python/HCL è di seguire un buon corso introduttivo a Python.

Convenzioni di codifica Python

Sarà necessario abituarsi ad alcune convenzioni di codifica che non sono applicate in ACLScript ma sono applicate in Python e HCL:

• Distinzione tra maiuscole e minuscole: la sintassi Python e HCL è sensibile alle maiuscole e minuscole, mentre la sintassi ACLScript non lo è.

  In Pyhton:

  • print("Hello World!") funziona

  • PRINT("Hello World!") restituisce un errore

• Nessuna abbreviazione I nomi delle funzioni, dei metodi e dei parametri Python e HCL devono essere scritti per intero. A differenza di ACLScript, le abbreviazioni non sono supportate.

• L'indentazione è importante Python utilizza l'indentazione per implementare strutture di controllo come istruzioni condizionali e cicli. Un'indentazione errata causa errori. ACLScript ignora l'indentazione.

Librerie esterne Python

Python supporta un gran numero di librerie esterne, o pacchetti, che è possibile installare per estendere le funzionalità dell'installazione principale di Python e della libreria standard di Python. Una libreria esterna Python è una raccolta di moduli di codice correlati, progettati per svolgere funzioni specifiche che vanno oltre ciò che è possibile realizzare con Python di base e con la libreria standard. Oppure rende certe operazioni più veloci e facili da fare rispetto a quanto non siano nel Python di base.

Librerie esterne incluse in Python Diligent One

L'installazione di Python in Diligent One include di default alcune librerie esterne, quindi non è necessario installarle esplicitamente. Ad eccezione della libreria HCL Python di Diligent, è necessario importare le librerie preinstallate per poterle utilizzare nella logica successiva degli script Python/HCL.

Librerie esterne preinstallate nell'ambiente Python Diligent One:

Libreria	Descrizione	Istruzioni di importazione Python
HCL	La libreria HCL, o HighBond Command Language, è la libreria Python personalizzata di Diligent per l'analisi dei dati incentrata sul dominio e l'automazione di Diligent One.	non obbligatorio
Pandas	La libreria Pandas fornisce un potente set di strumenti per la manipolazione e l'analisi dei dati in Python, tra cui i dataframe, ovvero array di dati bidimensionali simili a fogli di calcolo o tabelle.	import pandas oppure import pandas as pd (facoltativamente crea un alias abbreviato per il nome della libreria)
NumPy	La libreria NumPy offre un'elaborazione scientifica veloce e potente in Python, tra cui operazioni algebriche e statistiche di base, operazioni matematiche avanzate e creazione ed esecuzione di calcoli su array multidimensionali.	import numpy oppure import numpy as np (facoltativamente crea un alias abbreviato per il nome della libreria)
Richieste.	La libreria Requests fornisce una sintassi leggera per effettuare richieste HTTP in Python e interagire con API basate sul web.	import requests oppure import requests as req (facoltativamente crea un alias abbreviato per il nome della libreria)
Cryptography	La libreria Cryptography supporta l'incorporazione di algoritmi crittografici in Python.	import cryptography oppure import cryptography as crypt (facoltativamente crea un alias abbreviato per il nome della libreria)

Installare librerie esterne aggiuntive

I robot HighBond supportano l'installazione di librerie esterne aggiuntive oltre a quelle preinstallate con l'ambiente Python Diligent One. Per installare una libreria aggiuntiva, utilizzare pip, uno strumento per scaricare e installare pacchetti Python. Per impostazione predefinita, pip scarica i pacchetti da Python Package Index (PyPI), un archivio open source di software Python. È possibile utilizzare pip anche per installare pacchetti da altre posizioni.

Ad esempio, per installare pyexcel, una libreria Python per lavorare con file e dati Excel, utilizzare questo comando nell'editor di script di Robot:

pip install pyexcel

Anche se si installa una libreria esterna, non vi è alcuna garanzia che l'editor di script di Robot supporti tutte le funzionalità della libreria esterna. Ad esempio, potrebbe non supportare la visualizzazione di grafici e diagrammi disponibili in alcune librerie esterne.

Utilizzare Python e HCL per lavorare con le API

È possibile utilizzare gli script Python/HCL in Robot per lavorare con le API, sia quelle di terze parti che quelle di Diligent One.

Lavorare con un'API di terze parti

Per lavorare con un'API di terze parti, iniziare importando la libreria Python Requests nell'editor di script di Robot:

import requests

Ora è possibile effettuare richieste API utilizzando la sintassi di richiesta di Python e ricevere risposte. Per un semplice esempio di utilizzo di Python per effettuare una richiesta API di terze parti in Robot, consultare Parte 3: Ampliare la portata in Guida introduttiva alla scrittura di script di Robot e all'API di Diligent HighBond.

Spiegare dettagliatamente come utilizzare Python con API di terze parti va oltre lo scopo della nostra documentazione. Esistono tuttavia numerose risorse online che possono fornire indicazioni dettagliate.

Lavorare con l'API di HighBond

L'API di HighBond è l'interfaccia di sviluppo della piattaforma Diligent One. È possibile utilizzare l'API per automatizzare le interazioni e i flussi di lavoro di Diligent One, creare rapporti e integrare Diligent One con altri sistemi all'interno dell'organizzazione.

HCL include metodi che semplificano l'interazione con l'API di HighBond. Per maggiori informazioni, consultare Metodi API di HighBond HCL.

È inoltre possibile utilizzare la libreria Python Requests con l'API di HighBond. Tuttavia, per semplicità, consigliamo di utilizzare i metodi HCL.

Per un tutorial introduttivo che illustra l'utilizzo di Python e HCL con l'API di HighBond, consultare Guida introduttiva alla scrittura di script di Robot e all'API di Diligent HighBond.