> For the complete documentation index, see [llms.txt](https://docs.devolutions.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.devolutions.net/powershell-universal/it/automazione/workflows.md). # Flussi di lavoro I workflow di PowerShell Universal consentono di concatenare script e prompt IA in un unico flusso di automazione. I workflow sono utili quando è necessario passare l'output da un passaggio al successivo, creare diramazioni in base ai risultati precedenti o aggiungere elaborazione assistita dall'IA tra i passaggi di automazione. I workflow possono essere creati nella console di amministrazione e gestiti da PowerShell. Quando un workflow viene eseguito, crea un job di workflow che è possibile monitorare dalla stessa cronologia dei job utilizzata per gli script. ## Creazione di un workflow Per creare un workflow nella console di amministrazione, vada su Automation / Workflows e clicchi su Create Workflow. I workflow richiedono un nome e possono facoltativamente definire dei parametri. Questi parametri vengono mostrati quando il workflow viene avviato manualmente e sono disponibili per le espressioni e le attività durante l'esecuzione. ## Utilizzo del designer di workflow Il designer di workflow fornisce un editor visuale per organizzare e configurare il workflow. Quando apre un workflow, PSU visualizza il designer per quella definizione di workflow. ### Aggiunta di attività PowerShell Universal supporta attività di tipo script e prompt IA nei workflow. Internamente, i workflow utilizzano anche attività contenitore come i nodi flowchart e sequence per definire la struttura complessiva. Per aggiungere un'attività, la trascini dal riquadro delle attività sul lato sinistro del designer in una zona di rilascio sul canvas. ### Impostazione delle proprietà delle attività Selezioni un'attività per modificarne le proprietà nel riquadro a destra. Le proprietà disponibili dipendono dal tipo di attività. Per le attività di tipo script, PSU espone i parametri PowerShell dello script come proprietà dell'attività. Questo rende possibile associare valori fissi o espressioni di runtime senza riscrivere lo script solo per l'uso nei workflow. ### Utilizzo delle espressioni PowerShell Alcune proprietà delle attività supportano espressioni PowerShell. Le espressioni vengono valutate in fase di esecuzione e possono fare riferimento ai valori di input del workflow e all'output dell'attività precedente. Utilizzi le espressioni quando il valore di una proprietà deve essere calcolato in fase di esecuzione invece di essere memorizzato come valore fisso. Ad esempio, può abilitare o disabilitare un comportamento in base a un parametro del workflow oppure selezionare valori dall'output del passaggio precedente. ## Dati del workflow Le espressioni e le attività possono accedere allo stato del workflow tramite variabili integrate. ### Oggetto Workflow Utilizzi la variabile `$Workflow` nelle espressioni PowerShell per accedere ai valori dei parametri del workflow. Ad esempio, può impostare una proprietà booleana in base all'ambiente selezionato. {% code overflow="wrap" %} ```powershell $Workflow.Environment -eq "Production" ``` {% endcode %} È anche possibile passare un parametro di workflow di tipo stringa direttamente a una proprietà dell'attività. {% code overflow="wrap" %} ```powershell $Workflow.Environment ``` {% endcode %} I parametri del workflow sono definiti sul workflow stesso. Li utilizzi per i valori che devono essere forniti all'avvio del workflow, come il nome di un ambiente, un periodo di conservazione o un target di approvazione. ### PSUItem La variabile `$PSUItem` fornisce l'accesso all'output dell'attività precedente. Il tipo di oggetto dipende da ciò che tale attività ha restituito. Ad esempio, uno script può accettare `$PSUItem` come input. {% code overflow="wrap" %} ```powershell param($PSUItem) $PSUItem.MyValue ``` {% endcode %} È anche possibile fare riferimento a `PSUItem` nei prompt IA. {% code overflow="wrap" %} ``` PSUItem contains a list of processes. Return the process using the most memory as JSON. ``` {% endcode %} Può anche utilizzare `$PSUItem` o `$Output` nelle espressioni PowerShell per modificare il comportamento di un'attività in base all'output dell'attività precedente. {% code overflow="wrap" %} ```powershell $PSUItem.ProcessMemory -gt 100 ``` {% endcode %} Utilizzi `$PSUItem` quando desidera passare output strutturato da un'attività alla successiva. Questo è il modo principale per creare workflow a più passaggi senza memorizzare stati intermedi altrove. ### Deconstruct Hashtable Output **Panoramica**\ \ `Deconstruct Hashtable Output` controlla cosa accade al valore restituito da un passaggio di tipo Script una volta completato il passaggio. Quando è abilitato, PowerShell Universal prende una `Hashtable` a oggetto singolo restituita dallo script e ne distribuisce le chiavi/valori nello stato di output con ambito workflow, in modo che i passaggi successivi possano fare riferimento a ciascuna chiave come output di prima classe del workflow invece di dover scavare in `$PSUItem`.\ \ Quando è disabilitato, tale distribuzione non avviene. Il passaggio successivo vede comunque l'output grezzo del passaggio precedente tramite `$PSUItem`, ma ogni chiave deve essere estratta manualmente.\ \ **Comportamento**\ \ Quando l'attività Script termina, PowerShell Universal:\ \ 1\. Legge l'output della pipeline del passaggio.\ 2\. Se `DeconstructHashtableOutput` è `true`:\ • Prosegue solo se il passaggio ha restituito esattamente un oggetto di output con dati non vuoti.\ • Se l'oggetto di base è una `Hashtable`, percorre ogni chiave e copia ciascuna coppia `key → value` nello stato di output del workflow (accessibile dai passaggi successivi).\ 3\. In ogni caso, memorizza l'output grezzo per `$PSUItem` nel passaggio successivo (stato dell'attività precedente).\ \ Esempio\ \ Script del passaggio 1: ```powershell @{ Server = 'web01' Port = 443 Region = 'us-east' } ``` Con `DeconstructHashtableOutput = $true` (impostazione predefinita), il passaggio 2 può fare riferimento a ciascuna chiave direttamente tramite lo stato di output del workflow: ```powershell $Workflow.Output.Server # 'web01' $Workflow.Output.Port # 443 $Workflow.Output.Region # 'us-east' ``` Impostando lo stato di output dell'attività del workflow, l'attività successiva può ricevere l'output come input per i parametri corrispondenti. Con `DeconstructHashtableOutput = $false`, il passaggio 2 vede comunque la hashtable tramite `$PSUItem` e deve estrarla esplicitamente: ```powershell $PSUItem.Server $PSUItem.Port $PSUItem.Region ``` **Aspetti da tenere presenti**\ \ • Esattamente un oggetto della pipeline. La decostruzione si attiva solo quando lo script emette un singolo output. Qualsiasi `Write-Output` involontario, espressione non soppressa o emissione accidentale di più valori la disabilita silenziosamente, anche con l'impostazione attiva. Se vede output del workflow vuoti, converta l'output indesiderato in `$null` o lo invii tramite pipe a `Out-Null` per mantenere la pipeline a una singola hashtable.\ • Solo `Hashtable`, non `PSCustomObject`. Il codice verifica la presenza di `Hashtable` sull'oggetto di base. `[pscustomobject]@{ ... }` non verrà decostruito. Utilizzi `@{ ... }` se desidera il comportamento di distribuzione.\ • L'output vuoto o composto da spazi viene ignorato. Se il singolo output dello script non contiene dati, la decostruzione viene saltata.\ • `$PSUItem` funziona comunque in entrambi i casi. Disattivare l'impostazione non impedisce l'accesso all'output del passaggio precedente: cambia solo se le chiavi vengono esposte come output del workflow con nome.\ \ **Quando disattivarla**\ \ L'impostazione predefinita (`$true`) è la scelta giusta per la maggior parte dei workflow. La disattivi quando:\ \ • Il suo script deve legittimamente emettere più oggetti della pipeline e non desidera che PSU tenti la semantica di distribuzione.\ • Desidera che i passaggi successivi ricevano la hashtable come singolo oggetto opaco tramite `$PSUItem` e ne gestiscano autonomamente l'estrazione.\ • Sta restituendo una `Hashtable` le cui chiavi entrano in conflitto con nomi già presenti nello stato di output del workflow e desidera evitare di sovrascriverli.\ \ **Impostare il valore tramite `New-PSUWorkflowActivity`** ```powershell New-PSUWorkflowActivity ` -Type Script ` -ScriptFullPath 'C:\ProgramData\UniversalAutomation\Repository\scripts\Deploy.ps1' ` -Name 'Deploy' ` -FailOnScriptError $true ` -DeconstructHashtableOutput $true ``` ## Esempio di pattern di workflow Un pattern comune è: 1. Eseguire uno script per raccogliere i dati. 2. Passare l'output a un prompt IA o a un altro script. 3. Utilizzare il risultato in uno script finale per intraprendere un'azione. Ad esempio: * Un'attività di tipo script restituisce un elenco di processi. * Un prompt IA identifica il processo che utilizza più memoria. * Uno script finale riceve tale risultato tramite `$PSUItem` e invia una notifica. Questo approccio mantiene ogni passaggio mirato e rende il workflow più facile da testare e su cui risolvere i problemi. ## Esecuzione dei workflow ### Su richiesta I workflow possono essere eseguiti su richiesta cliccando sull'icona Play nella console di amministrazione. Se il workflow definisce dei parametri, PSU li richiede nella finestra di dialogo di esecuzione. Dopo l'avvio del workflow, PSU la reindirizza alla pagina del job del workflow. ### Pianificazione I workflow supportano le stesse opzioni di pianificazione degli script, incluse le pianificazioni CRON, una tantum e continue. Può creare pianificazioni di workflow da Automation / Schedules oppure assegnando una pianificazione direttamente al workflow. Utilizzi le pianificazioni quando il workflow deve essere eseguito senza input manuale, ad esempio per la pulizia notturna, la convalida dell'ambiente o la classificazione periodica assistita dall'IA. ### Invoke-PSUWorkflow `Invoke-PSUWorkflow` consente di eseguire workflow da PowerShell o da altre parti della piattaforma PowerShell Universal. Come con `Invoke-PSUScript`, può fornire i valori dei parametri quando invoca il workflow. ## Gestione dei workflow con PowerShell Può gestire i workflow tramite il modulo Universal oltre che dalla console di amministrazione. I cmdlet principali per i workflow sono: * `Get-PSUWorkflow` * `New-PSUWorkflow` * `Set-PSUWorkflow` * `Remove-PSUWorkflow` * `New-PSUWorkflowParameter` * `New-PSUWorkflowActivity` * `Invoke-PSUWorkflow` ### Definizione dei parametri del workflow Utilizzi `New-PSUWorkflowParameter` per definire i metadati di input del workflow, come un valore predefinito, se il parametro è obbligatorio e il testo della guida mostrato agli utenti. ```powershell $Parameters = @( New-PSUWorkflowParameter -Name Environment -DefaultValue Development -Required -HelpText 'Target environment' ) ``` ### Definizione delle attività in PowerShell Utilizzi `New-PSUWorkflowActivity` per creare definizioni di attività del workflow. * Utilizzi `-Parameters` per i valori letterali. * Utilizzi `-Expressions` per le espressioni PowerShell valutate in fase di esecuzione. * Per `-Type Script`, PSU può esporre parametri dinamici dallo script di destinazione. ```powershell $Deploy = New-PSUWorkflowActivity -Type Script ` -Name Deploy ` -ScriptFullPath 'C:\ProgramData\UniversalAutomation\Repository\scripts\Deploy.ps1' ` -FailOnScriptError $true $Root = New-PSUWorkflowActivity -Type Sequence -Name Deployment -Parameters @{ Activities = @($Deploy) } ``` ### Creazione di un workflow in PowerShell `New-PSUWorkflow` accetta una stringa di definizione grezza oppure uno script block che restituisce una singola definizione di attività di workflow. ```powershell $Parameters = @( New-PSUWorkflowParameter -Name Environment -DefaultValue Development -Required -HelpText 'Target environment' ) $Deploy = New-PSUWorkflowActivity -Type Script ` -Name Deploy ` -ScriptFullPath 'C:\ProgramData\UniversalAutomation\Repository\scripts\Deploy.ps1' ` -Expressions @{ Environment = '$Workflow.Environment' } $Root = New-PSUWorkflowActivity -Type Sequence -Name Deployment -Parameters @{ Activities = @($Deploy) } New-PSUWorkflow -Name ApplicationDeployment -Description 'Deploy an application through a workflow' -WorkflowParameters $Parameters -Definition { $Root } ``` ## Monitoraggio delle esecuzioni dei workflow Le esecuzioni dei workflow compaiono nella cronologia dei job esattamente come i job degli script. Utilizzi la pagina del job per esaminare: * stato attuale * output dello stream * output della pipeline * errori Questo è il posto migliore per risolvere i problemi dei passaggi di workflow non riusciti e verificare i dati passati tra le attività. ## Risoluzione dei problemi * Se una proprietà deve essere calcolata in fase di esecuzione, utilizzi un'espressione invece di un valore fisso. * `$PSUItem` contiene solo l'output dell'attività precedente. La prima attività di un workflow non avrà output precedente. * Le proprietà delle attività di tipo script si basano sui metadati dello script di destinazione. Se un parametro dello script non compare come previsto, verifichi il percorso dello script e il nome del parametro. * I nomi dei parametri delle attività e le chiavi delle espressioni devono corrispondere a proprietà valide per quel tipo di attività. * Se ha bisogno di un'esecuzione ricorrente, colleghi una pianificazione invece di invocare manualmente il workflow. ## Argomenti correlati * [Job](/powershell-universal/it/automazione/jobs.md) * [Pianificazioni](/powershell-universal/it/automazione/schedules.md) * [Script](/powershell-universal/it/automazione/scripts.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.devolutions.net/powershell-universal/it/automazione/workflows.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.