L’editor Jinja di FortiSOAR non serve a scrivere espressioni: serve a verificarle prima di metterle in un playbook. È l’unico posto del prodotto dove puoi applicare un template a un JSON di prova e guardare l’output senza far partire nulla, e in un SOC questa differenza vale parecchie esecuzioni sbagliate su record veri.

Come è fatto e cosa ti dice

Lo apri dal designer, con Tools > Jinja Editor. Ha tre aree: Jinja Template, dove scrivi l’espressione fra parentesi graffe; JSON, dove metti l’input in coppie chiave-valore, anche annidate; e Output, dove compare il risultato dopo aver cliccato Render. Se l’output è un oggetto, viene mostrato come oggetto e non come testo.

L’area JSON ha due viste. In vista Tree espandi, comprimi e cerchi dentro i dati; in vista Code hai i pulsanti Format JSON Data, Compact JSON Data, Repair JSON, Undo e Redo. Repair JSON è quello che usi più spesso in diagnosi: sistema virgolette, caratteri di escape e commenti in un payload incollato da un connettore.

⚠️ Se l’editor mostra il messaggio Bad String, l’errore è nel JSON di input, non nella tua Jinja. Continuare a limare l’espressione mentre il JSON è malformato è il modo più comune di perdere mezz’ora.

Load Env JSON: il caso d’uso che conta

La funzione che trasforma l’editor in uno strumento di troubleshooting è il menu a tendina Choose A Recent Playbook Execution, seguito dal pulsante Load Env JSON: carica nell’area JSON l’ambiente reale di una esecuzione passata di quel playbook. Non stai più immaginando i dati, stai riprovando l’espressione sugli stessi dati che l’hanno fatta fallire.

🔴 Dettaglio che vale il punto intero: quel menu compare solo se il playbook è stato eseguito almeno una volta in modalità DEBUG. Con le sole esecuzioni in INFO non hai nessun ambiente da caricare. Ed è un vincolo a doppio taglio, perché è la stessa condizione richiesta dall’opzione Show Last Run Result if Available in Step Results.

Altri limiti da ricordare, perché sono esattamente il tipo di dettaglio su cui si costruisce una domanda:

  • L’elenco mostra le ultime 30 esecuzioni, filtrabili per modulo, stato e Record ID.
  • Se il trigger dello step è impostato su Does not require a record input to run, il campo Record ID non è disponibile.
  • Se il trigger è Referenced o Custom API Endpoint, puoi filtrare solo per stato.
  • Dal rilascio 7.6.0 i dati degli step, cioè vars.steps, sono inclusi nell’ambiente ENV: prima l’ambiente caricato non conteneva l’output dei singoli step, e questa è la ragione per cui molte guide più vecchie dicono di ricostruirlo a mano.

Nota di lettura sul JSON: dal rilascio 7.2.1 la radice dell’albero è vars, mentre in passato era scritta ENV. Se copi Jinja da materiale vecchio e ti aspetti un nodo ENV, non lo trovi.

Le espressioni che si rompono, e come le riconosci

Ci sono errori che l’editor ti mostra subito, se sai cosa cercare.

Il primo è la stringa vuota restituita da un if senza else. Un’espressione condizionale che non produce nulla non è compatibile con il tipo di campo definito nel database e fa fallire il playbook. La forma corretta prevede sempre il ramo alternativo:

{% if vars.currentValue == "Aftermath" %}{{Current_Date}}{% else %} None {% endif %}

Il secondo è l’indice degli array. L’output di uno step è spesso una lista, e la posizione va indicata esplicitamente, partendo da zero: il quarto elemento si scrive con indice [3]. Senza indice, l’espressione non restituisce quello che ti aspetti.

Il terzo è il tipo di dato. Il filtro type_debug esiste apposta per questo, e ti dice il tipo Python sottostante di una variabile:

{{ myvar | type_debug }}
{{ my_variable | default('my_variable non è definita') }}
{{ vars.steps.step_name.keyname | json_query("[?state=='running'].name") }}

Il filtro default distingue un valore assente da un valore falso, e va invocato con secondo parametro true se vuoi che intercetti anche le stringhe vuote. Il filtro json_query, costruito su jmespath, è l’arma giusta quando devi estrarre pochi campi da una struttura profonda restituita da un connettore.

Quello che l’editor non può salvare

Dal rilascio 7.4.0 i template Jinja sono eseguiti in sandbox e non possono accedere a membri privati di funzioni, moduli e classi. Un playbook che usa __setitem__ fallisce con l’errore CS-WF-7: Invalid Jinja template, e la correzione consigliata è riscriverlo con update. Esiste il parametro USE_SANDBOX_ENV per disattivare la restrizione, ma la documentazione lo marca come NON raccomandato: nell’esame è la risposta sbagliata quasi per definizione.

C’è anche una lista di filtri bloccabili, DISALLOWED_JINJA_FILTERS, che oggi contiene readfile. Un’espressione perfettamente valida può quindi fallire per configurazione, non per sintassi.

⚠️ Infine un limite che l’editor non segnala e che genera comportamenti inspiegabili: non si usa do until insieme a when o a for each sullo stesso step. Se la tua diagnosi finisce su un loop che si comporta in modo incoerente, controlla prima la combinazione di opzioni dello step, non la Jinja.