Quando un playbook non si comporta come previsto, la prima domanda non è dove sia il difetto, ma quanto il sistema ha registrato di quella esecuzione. In FortiSOAR la risposta dipende da una scelta fatta prima che il playbook parta: se hai scelto male, ti tocca rilanciare.

Il livello di log si decide prima dell’esecuzione

Ogni playbook ha un proprio livello di esecuzione, INFO (predefinito) oppure DEBUG. Lo cambi aprendo il playbook nel designer e cliccando l’indicatore INFO o DEBUG in cima alla tela: si apre la finestra Playbook Execution Log Level, selezioni il livello, clicchi Apply e poi devi salvare il playbook. L’amministratore imposta il livello globale e può abilitare l’override sul singolo playbook.

La regola operativa è netta: INFO in produzione, DEBUG solo mentre progetti o indaghi, perché DEBUG riempie in fretta lo spazio disco. Dal rilascio 7.4.0 esiste però una scorciatoia preziosa: per i playbook falliti il livello predefinito è DEBUG, quindi per capire la causa di un errore in genere non serve rieseguire nulla.

🔴 Dettaglio che costa il punto intero: un playbook figlio eredita il livello del padre indipendentemente dal proprio. L’esempio della documentazione è il figlio impostato a INFO con il padre a DEBUG: il figlio finisce a DEBUG. Su una catena di playbook referenziati, quindi, il livello che conta è quello del padre, non quello che hai messo con cura sul figlio.

Lo stato dice più del messaggio d’errore

I log si aprono dall’icona Executed Playbook Logs in alto a destra, da Tools > Execution History nel designer, o dalla vista di dettaglio di un record, dove compaiono come diagramma di flusso con il commutatore fra vista Record e vista Global. Vale la RBAC dei playbook: vedi solo i log dei playbook di cui tu o il tuo team siete proprietari.

Gli stati filtrabili sono Incipient, Active, Awaiting, Paused, Failed, Finished e Finished with error, e qui si annidano due trappole.

La prima: uno step con Ignore Error attivo che fallisce non produce Failed, ma Finished with error. Se filtri su Failed non lo vedi, e il playbook risulta «andato bene» mentre un’azione non è stata eseguita. L’errore è nel campo result dello step.

La seconda: nell’elenco globale il tag #system è escluso per impostazione predefinita. Un playbook di sistema che «non ha lasciato traccia» quasi sempre ha girato: è il filtro per tag a nasconderlo. Lo trovi in Settings, alla voce Filter Logs by Tags, e le modalità Only Include ed Exclude non sono mescolabili.

input_args contro evaluated_args

Cliccando uno step il log mostra le schede Input, Output (o Error, se lo step è fallito), Config e, negli step referenziati, Instances. Nella scheda Input convivono tre cose diverse: data, le informazioni del trigger; input_args, la Jinja esattamente come l’hai scritta; evaluated_args, il valore in cui quella Jinja si è risolta al momento dell’esecuzione.

Il confronto fra le ultime due è la diagnosi più rapida che hai:

input_args:     "ip": "{{vars.input.records[0].sourceIp}}"
evaluated_args: "ip": ""

Se evaluated_args è vuoto o contiene il testo letterale dell’espressione, il problema è la Jinja o il contesto, non il connettore a valle. Se invece è corretto e l’errore arriva dalla scheda Error, il guasto è dall’altra parte: configurazione, credenziali o rete.

La scheda Config completa il quadro: mostra le variabili dello step e se sono attivi ignore_errors, MockOutputUsed e la condizione when, con valore true o false.

⚠️ Sul mock output c’è una trappola classica. Non basta compilare il Mock Output nello step: devi dichiarare nel trigger, tramite l’opzione Variables, una variabile chiamata useMockOutput con valore true. Il nome è case-sensitive e va scritto esattamente così; se manca o vale false, il playbook usa gli output reali e il tuo test tocca i sistemi di produzione.

I guasti tipici dei connettori

Sul connettore, il primo gesto è l’Health Check dalla finestra di configurazione: restituisce Available se parametri e connettività sono a posto, Disconnected altrimenti. Ma il difetto più insidioso non è il Disconnected.

Dopo l’aggiornamento di un connettore, un campo di configurazione diventato obbligatorio e privo di valore predefinito nel file info.json lascia la configurazione in stato Partially Configured, e l’errore compare nel log di esecuzione del playbook, non sulla scheda del connettore che stai guardando. Ricorda anche che almeno una configurazione deve essere marcata come predefinita con Mark As Default Configuration, altrimenti il connettore non sa quale usare; per il connettore SMTP questo è obbligatorio per le notifiche di sistema.

Due errori ricorrenti che non sembrano errori di connettore:

  • Picklist. Dal rilascio 7.2.0 il confronto sui filtri picklist è a corrispondenza esatta, maiuscole comprese: un playbook che cerca MEDIUM fallisce se il valore reale è Medium.
  • Verify SSL. Il campo vale True per impostazione predefinita. Con un certificato self-signed devi accodare la CA al file cacert.pem usato dalla libreria requests, e l’indirizzo del server nella configurazione deve coincidere con il CN del certificato.

Corretta la causa, il pulsante Rerun From Last Failed Step riprende la stessa istanza dallo step fallito: vale solo se non hai toccato il playbook, perché modificarne gli step trasforma la ripresa in una nuova esecuzione.