L'app desktop

L'app desktop di Noeva ETL mostra i processi del workspace, il loro grafo e le loro esecuzioni, e permette di avviarli. Non modifica i processi: la loro struttura sta nel codice, e si cambia con una revisione (Creare con Claude Code).

Accesso

Si accede con le credenziali Noeva. Il pulsante Guida nell'header apre nel browser di sistema la documentazione servita dal server ETL a cui l'app è collegata: quella del tuo cliente su /guida/, e da lì questa guida su /guida/core/.

La lista dei processi

Dopo l'accesso si apre la lista dei processi ETL. Per ciascuno trovi la descrizione, qualche metrica sulla topologia e l'esito e la data dell'ultima esecuzione. Puoi cercare per nome, ordinare e filtrare per esito.

L'esito mostrato è quello dell'ultima run del workspace, chiunque l'abbia avviata: un processo lanciato da un collega non risulta "mai eseguito".

Se la lista mostra un errore

La lista chiede gli esiti delle ultime run al server Noeva. Se non risponde, al posto dei processi compare l'errore con il pulsante Riprova: non viene mostrata una lista parziale, che darebbe esiti sbagliati.

Il pannello del processo

Selezionare un processo non apre subito il grafo: apre un pannello laterale con lo storico delle esecuzioni e due azioni, Apri il grafo ed Esegui. Dallo storico puoi andare direttamente al grafo nello stato di una run passata.

Il grafo

Il grafo di un processo ha un indirizzo suo, che puoi condividere. I nodi hanno lo stesso colore in tutta la documentazione e nell'app:

Nodo	Cosa rappresenta
source	da dove entrano i dati: una tabella, una cartella di file
transform	un controllo o una trasformazione, senza accesso a sistemi esterni
lookup	una query in sola lettura per arricchire i record
ai	una domanda a un modello, la cui risposta arricchisce il record
action	una scrittura per record, dopo la quale il grafo prosegue
route	uno smistamento: ogni record va su una sola porta con nome
join	l'unione di due flussi su una chiave
union	N flussi con la stessa forma messi in fila, record invariati
try-catch	un punto che cattura gli errori a valle e li devia su un ramo
sink	dove i dati vengono scritti
dead-letter	il ramo rosso tratteggiato degli scarti

L'app disegna anche il nodo task (grigio ardesia, senza colonne) e gli edge di controllo, puntinati: dicono che un nodo parte solo dopo che un altro è riuscito. Un nodo che non parte perché un altro non è riuscito appare saltato, con un contorno tratteggiato, e il pannello di dettaglio dice chi l'ha bloccato.

Ogni card mostra il tipo di connettore e dove punta, e le colonne che attraversano il nodo, in entrata e in uscita. Selezionando un nodo si apre il pannello di dettaglio con tutta la configurazione del connettore, in sola lettura e con i valori sensibili mascherati. Se il nodo ha uno scopo, l'icona di info accanto al titolo lo apre in un riquadro: dice in poche frasi che cosa fa il nodo e perché sta nella pipeline.

Avviare una run

Esegui, dalla lista o dal pannello, avvia la run e porta al grafo, dove l'avanzamento si aggiorna nodo per nodo. Puoi tornare alla lista mentre la run procede: l'avanzamento non si interrompe.

Alcune pipeline chiedono dei parametri di lancio, come il progressivo del bilancio da elaborare. Per quelle Esegui apre prima un dialog con un campo per parametro: sotto ogni campo c'è a cosa serve, e i facoltativi sono segnati. Un campo vuoto ma obbligatorio, o un valore del tipo sbagliato (una lettera dove serve un numero intero, una data che non esiste), blocca il lancio e dice quale campo correggere. Le pipeline senza parametri partono con un clic, come sempre. Anche Esegui con tracciamento chiede i parametri, dopo il dialog della traccia.

I nodi in corso, quelli in cui stanno passando record, si riconoscono subito: hanno un anello blu che pulsa piano attorno alla card, e gli edge di dati che ne escono sono tratteggiati e scorrono. Possono essere in corso più nodi insieme, su rami diversi. Quando un nodo si conclude l'anello lascia il posto a quello dell'esito, verde o rosso, e i suoi edge si fermano. Gli edge di controllo e i rami degli scarti non scorrono mai. Una sub-pipeline chiusa è in corso finché lo è uno dei suoi nodi interni. Se nel sistema è attiva la preferenza Riduci movimento, niente pulsa e niente scorre: l'anello e il tratteggio restano, fermi.

In fondo alla card, appena il nodo inizia a lavorare, compaiono tre numeri che salgono circa una volta al secondo: i record entrati, quelli usciti e quelli in errore, in rosso quando ce n'è almeno uno. Passandoci sopra col mouse se ne legge il significato. Un errore catturato da un try-catch conta sul nodo che ha fallito, non sul try-catch, che mostra a parte quanti ne ha catturati. Un nodo saltato non ha contatori: non è mai partito. Un task non ne ha mai, perché non lavora su record.

Un quarto numero, con la clessidra, compare solo sui nodi che trattengono record: quanti ne stanno tenendo in lavorazione in quel momento. Un sort o un groupBy li accumula tutti prima di emettere, un join tiene da parte i record del lato probe finché non ha finito di leggere l'altro lato, un try-catch mette in coda gli errori per il suo ramo catch, e un nodo con più uscite tiene i record che il ramo più lento non ha ancora preso. Un lookup, un nodo AI o un'action tengono i record che aspettano la risposta di un sistema esterno, e un sink su database le righe accumulate e non ancora scritte. Un sink su database conferma tutto con un solo commit a fine scrittura: fino ad allora i suoi usciti restano a zero, e le righe già scritte nella transazione non compaiono né fra gli usciti né in lavorazione. Con un retry sul nodo il sink scrive a blocchi e i suoi usciti salgono a ogni blocco confermato. È il numero che spiega perché a valle non arriva ancora niente, quale ramo frena gli altri, o quale sistema esterno sta rispondendo lento. Sparisce quando torna a zero, e su un filtro o una map non c'è mai, perché lì non si può sapere. Dal server ETL locale i contatori arrivano ogni secondo; se l'app non lo raggiunge, o la run gira sul worker, li legge da Noeva e salgono a scatti di circa cinque secondi.

Una run tracciata

Esegui con tracciamento, nella barra del grafo, avvia una run che conserva anche il percorso dei primi record di ogni source e dei record che ne derivano, come gli aggregati e le uscite di un join: per ciascuno, da quali nodi è passato e com'era a ogni passaggio. Il dialog chiede quanti record per source tracciare, 100 se non lo cambi, e il tetto del campione, 1000 record letti e derivati in tutto. Dei record che vanno in errore fuori dal campione la run conserva il cammino fino al nodo che ha fallito e il valore che l'ha fatto fallire: il tetto dei record in errore, 1000 se non lo cambi, dice quanti al massimo. Avvisa anche che la traccia salva i valori dei record in chiaro, compresi i dati personali a monte di un mask. La run scrive sui sink come una run normale.

Una run tracciata parte dal server ETL locale e non dal server Noeva: funziona solo se l'app e etl serve girano sulla stessa macchina, e la run finisce nello storico locale, non in quello del workspace. Nello storico le run che hanno ancora una traccia portano il segno Traccia, e il cestino accanto la elimina lasciando il report. Se la run ha raggiunto il tetto compare anche Campione esaurito: la traccia segue solo i record entrati prima del tetto, mentre la run è proseguita normalmente. Le tracce si conservano poco: le 20 più recenti, salvo una configurazione diversa del server. Formato e regole: La traccia di una run.

Il percorso di un record

Su una run che ha ancora la traccia, il pannello di un nodo ha la sezione Record tracciati. La traccia non si scarica aprendo la run: si chiede con Mostra i record tracciati, perché può essere pesante e contiene i valori in chiaro. L'elenco ha i record del campione passati da quel nodo, con il loro valore all'uscita, il segno derivato per quelli nati da un join o da un aggregato, in errore per quelli che ci sono falliti e, su un try-catch, catturato per quelli che ha mandato sul ramo catch.

Scegliendo un record, il grafo evidenzia nodi e collegamenti attraversati, nello stesso blu della lineage delle colonne, e attenua il resto. Al posto del pannello di dettaglio compare il percorso: i passaggi in ordine, ciascuno col nodo, la porta su cui è uscito (la condizione di un route, out o catch di un try-catch), il valore e, se il record è fallito, l'errore e il nodo che l'ha fatto fallire. In testa Deriva da elenca i record da cui è nato, in fondo Ha generato quelli nati da lui: un clic ne apre il percorso. Un'istanza di sub-pipeline conta come un passaggio solo, con il valore a ogni uscita. Si apre dal grafo principale, non da dentro un'istanza.

La X in alto chiude il percorso e riporta il grafo com'era. I valori sono quelli della traccia, in chiaro, come il corpo di un errore nel pannello del try-catch.

Il percorso di un errore

Su una run tracciata il percorso si apre anche da un errore, con Mostra percorso. Il pulsante sta accanto a ogni errore catturato nel pannello del try-catch, e nella sezione Errori nella traccia del nodo che ha fallito, che elenca i record rifiutati da quel nodo e quelli catturati più avanti. Se la traccia non è ancora scaricata, il pulsante la chiede e il percorso si apre appena arriva; la sezione del nodo, invece, la chiede col suo pulsante Mostra gli errori tracciati.

• Se il record era nel campione, il percorso è completo, coi valori a ogni passaggio.
• Se era fuori dal campione, il grafo evidenzia il cammino ma il pannello dice che i valori intermedi non sono stati salvati: si vede solo il valore che ha fatto fallire il nodo.
• Se l'errore non è nella traccia, di solito perché la run ha superato il tetto dei record in errore, al posto del pulsante lo dice.

Su una run non tracciata il pulsante non c'è.

Un processo appena creato

Due cose da sapere quando un processo nuovo è appena stato approvato:

1. Compare nella lista solo dopo un riavvio del server ETL. L'elenco dei grafi si costruisce all'avvio di etl serve: aggiornare la pagina non basta.
2. Il pulsante Esegui lo abilita il worker. Al proprio avvio il worker dichiara al server Noeva i processi che sa eseguire, con i loro parametri di lancio: finché il worker con il processo nuovo non è ripartito, il processo si vede ma Esegui risponde con un errore.

Rivedere una run passata

Nel grafo, lo storico delle esecuzioni sta in un pannello laterale. Selezionare una run ne proietta l'esito sul grafo: ogni nodo si colora per come è andato, con i suoi contatori in fondo alla card, gli stessi visti durante la run. Quando un try-catch ha catturato più errori di quanti il report ne elenchi, parte di quegli errori non si può più attribuire a un nodo. In quel caso «in errore» è un minimo, e lo segna un «≥». La barra del grafo dice sempre quale esecuzione stai guardando, e l'indirizzo della pagina la include: condividerlo porta un collega esattamente lì.

Il messaggio d'errore di una run fallita è troncato a una riga nell'elenco; il comando accanto lo apre per intero in una finestra, da cui si può selezionare e copiare.

Prossimo passo

Leggere l'esito di una run: cosa significano gli stati e i contatori, e dove finiscono i record scartati.