Workflow

Accesso dal menu: Processi → Workflow

Un workflow è un'automazione che esegue una sequenza di passaggi sui tuoi dati Amazon, sia su richiesta sia secondo una pianificazione. Ti permette di auditare prodotti, rilevare problemi e creare attività di revisione senza doverlo fare manualmente.

Come si creano?

Oggi ci sono due modi per creare un workflow in Epinium:

• Da un modello — clonando uno della Libreria di modelli. È la via consigliata e più rapida.
• Con VelaxAI — descrivi in linguaggio naturale ciò che vuoi automatizzare e VelaxAI genera il workflow.

Non esiste ancora un'opzione per creare un workflow da zero su una tela vuota. Una volta creato il workflow (clonato da un modello o generato da VelaxAI), puoi modificarlo liberamente: cambiare il suo trigger, le sue condizioni, il codice, le connessioni, ecc.

Workflow, Attività o VelaxAI?

• Workflow — per regole ricorrenti che si eseguono periodicamente (ogni lunedì, ogni 1° del mese).
• Attività — per revisionare e approvare i suggerimenti che un workflow (o VelaxAI) genera.
• VelaxAI — per consultazioni puntuali in linguaggio naturale e per creare nuovi workflow.

Stati del workflow

Un workflow può essere in uno di questi tre stati:

Stato	Significato
In pausa	Configurato ma non si eseguirà automaticamente. È lo stato di default al momento della clonazione di un modello. Può comunque essere eseguito manualmente.
Attivo	Si eseguirà automaticamente secondo il suo trigger.
Con errori di validazione	L'editor ha rilevato un problema nel grafo (nodo non collegato, condizione vuota, riferimento rotto). Non può essere attivato finché non viene corretto.

L'editor visuale

L'editor mostra il workflow come un grafo: ogni casella è un nodo (un passaggio) e ogni linea è una connessione (cosa viene dopo).

• Tela — puoi spostare i nodi per riorganizzare visivamente. Non influisce sulla logica.
• Connessioni — alcune sono semplici (un solo percorso in uscita). Altre si biforcano: una Condizione ha uscite Sì e No; un Ciclo ha per elemento (per ogni elemento) e alla fine (quando l'iterazione termina).
• Configurare un nodo — un clic su un nodo apre una finestra dove puoi modificare i suoi parametri: messaggio, URL, condizione, assegnazione di variabili, ecc.
• Modificare il codice di un nodo — il nodo Esegui codice apre un editor dove puoi leggere e modificare lo script (generato da VelaxAI o copiato dal modello).
• Validazione automatica — l'editor evidenzia gli errori in rosso (nodi orfani, connessioni rotte, condizioni senza operatore). Se ci sono errori, il workflow non può essere attivato.

La finestra di configurazione di un nodo

L'icona dell'ingranaggio (⚙️) di ogni nodo apre la sua configurazione. A seconda del tipo di nodo compaiono schede diverse:

Scheda	Cosa contiene
Generale	Il nome del nodo — il testo che si vede nel diagramma. Presente in tutti i nodi
Configurazione	I parametri propri del tipo di nodo: la condizione, i dati dell'attività, l'URL della richiesta HTTP…
Filtri	Solo nei cicli Per ogni con origine Query: quali elementi verranno iterati. Vedi § Filtri del ciclo
Codice reduce	Solo nei cicli Per ogni che raccolgono risultati: il codice che li aggrega. Vedi § Codice reduce

Rinominare un nodo — cambialo nella scheda Generale. Dagli un nome che dica cosa fa («Controlla titolo», «Avvisa su Slack») invece di quello generico: i nomi compaiono nel diagramma, nello storico delle esecuzioni e nei riferimenti a variabili di altri nodi, quindi un nome chiaro si ripaga da solo quando si fa debug. Se lasci il campo vuoto, si conserva il nome predefinito.

Cronologia versioni

Ogni volta che salvi un workflow, Epinium archivia la versione precedente prima di sovrascriverla. Il pulsante Cronologia versioni apre l'elenco, con una riga per versione: nome, stato, numero di nodi, errori di validazione e data.

Da lì il pulsante Ripristina riporta il workflow a qualsiasi versione precedente. Anche la versione attuale viene archiviata prima del ripristino, quindi tornare indietro non perde nulla: se la versione recuperata non era quella che volevi, ripristina la precedente.

Al ripristino il grafo viene validato di nuovo. Se la versione recuperata aveva errori, il workflow resta con errori di validazione e non potrà essere attivato finché non li correggi.

Tipi di nodi

Questi sono i nodi disponibili:

Nodo	Cosa fa
Inizio	Indica da dove inizia il flusso. Ogni workflow ha esattamente un nodo di inizio.
Fine	Indica un punto di fine. Un workflow può avere più nodi di fine (uno per ramo, ad esempio).
Azione	Esegue un compito concreto. Ha diversi sottotipi (vedi tabella successiva).
Condizione	Biforcazione Sì / No basata su un campo e un operatore (uguale, maggiore di, contiene, è vuoto…).
Multi-ramo	Come una condizione ma con più uscite in base al valore di un campo. Utile quando ci sono più di due casi possibili.
Ciclo (Per ogni)	Itera su un insieme di elementi (prodotti, campagne, search terms…). Vedi § Cicli.
Attesa	Mette in pausa il flusso per un periodo (secondi, minuti, ore) prima di continuare.

Sottotipi del nodo Azione:

Sottotipo	Cosa fa
Messaggio nel log	Scrive un messaggio nel registro di esecuzione. Utile per debug o per lasciare tracce.
Richiesta HTTP	Chiama un URL esterno (un webhook, un'integrazione con un altro sistema). Permette di inviare dati a strumenti di terze parti.
Esegui codice	Esegue logica personalizzata in un ambiente sicuro. È il motore dei check dei modelli di audit: valuta regole complesse su un prodotto e restituisce un risultato strutturato. Puoi leggere e modificare lo script dall'editor.
Crea attività	Genera o aggiorna un'attività con uno o più elementi per la revisione umana. Vedi § Attività e supervisione umana.
Risolvi attività	Segna come risolti gli elementi di un'attività i cui problemi non esistono più (perché sono stati corretti).

Trigger

Un workflow può essere lanciato in due modi:

• Manuale — pulsante Esegui dalla pagina del workflow. Apre una finestra che mostra il costo massimo stimato prima di confermare.
• Pianificato — il workflow si lancia da solo seguendo una pianificazione:
  • Cron — espressione cron standard a 5 campi. Esempi: ogni lunedì alle 9:00, il 1° di ogni mese alle 5:00.
  • Intervallo — ogni N minuti, ore o giorni.
  • Data singola — una sola esecuzione in una data/ora precise.
• Fuso orario — configurabile per workflow (ad esempio Europe/Rome). Il trigger viene interpretato in questo fuso, non in UTC.

Costo stimato

Prima di eseguire manualmente un workflow, Epinium calcola e mostra il costo massimo in crediti. Questo numero riflette il caso peggiore (tutti i prodotti auditati, tutti i nodi eseguiti senza salti).

Controlla il costo prima di attivare

Se stai per attivare un workflow pianificato che itera su tutto il catalogo, lancia prima un'esecuzione manuale per vedere il costo reale. Su cataloghi grandi, un'esecuzione quotidiana involontaria può consumare più crediti del previsto.

Cicli (Per ogni)

Un nodo Per ogni ripete i passaggi al suo interno una volta per ogni elemento di una lista.

Origine dei dati — due modalità:

• Query — scegli una collezione del tuo account (prodotti, campagne, search terms, ad group, product ads, keyword, cluster) e applichi filtri per restringerla. È la modalità più usata.
• Riferimento — itera su una lista prodotta da un nodo precedente (ad esempio, il risultato di una Richiesta HTTP).

Gestione errori per elemento — se la valutazione di un elemento fallisce, il ciclo può:

• Continuare (default) — prosegue elaborando gli altri elementi.
• Interrompere — ferma l'intero ciclo.

Raccogliere risultati — opzionalmente, il ciclo può aggregare ciò che produce ogni iterazione in un riepilogo finale. I modelli di audit lo usano per contare quanti prodotti sono conformi e quanti no, e mostrare il riepilogo nel log.

Il ciclo ha due uscite: per elemento (ciò che si esegue per ogni elemento) e alla fine (ciò che si esegue una volta elaborati tutti).

Filtri del ciclo

Con l'origine in modalità Query, la scheda Filtri del nodo restringe quali elementi verranno iterati. Senza filtri, il ciclo percorre tutti gli elementi della collezione.

I filtri si organizzano in gruppi di regole, e il modo in cui si combinano è il punto chiave:

• Le regole dentro lo stesso gruppo si combinano con O — basta che una sia vera.
• I gruppi tra loro si combinano con E — tutti i gruppi devono essere veri.

È così che si esprimono condizioni del tipo «(marchio A o marchio B) e (senza immagine principale)»: un marchio per regola nel primo gruppo e la condizione dell'immagine in un secondo gruppo.

Ogni regola ha tre parti e un interruttore:

Parte	A cosa serve
Campo	Il percorso del dato nell'elemento, per esempio commonFields.ASIN
Valore	Con cosa si confronta
Formato	Come interpretare il valore: Testo, ObjectId, Booleano, Data o Esiste (numero) — quest'ultimo prende gli elementi che hanno un numero in quel campo
Attivo	Disattiva la regola senza cancellarla, utile per fare prove

Il formato conta

Lo stesso valore filtra in modo diverso secondo il formato. true come Testo cerca la stringa «true»; come Booleano cerca il valore vero; come Esiste (numero) verifica che il campo contenga un numero (per esempio un'offerta massima configurata). Se un filtro non restituisce quello che ti aspetti, il formato è la prima cosa da controllare.

In modalità Riferimento la scheda Filtri non si applica: il ciclo itera su ciò che ha prodotto un nodo precedente, quindi il filtraggio va fatto in quel nodo.

Codice reduce

Quando il ciclo ha Raccogli risultati attivo, la scheda Codice reduce permette di aggregare ciò che restituisce ogni iterazione in un unico risultato finale.

Funziona a lotti (streaming): il codice si esegue una volta per lotto, non una volta per elemento. Riceve input.items (il lotto corrente) e input.accumulator (il risultato del lotto precedente, null nel primo) e deve restituire l'accumulatore per il lotto successivo.

È così che si ottengono i totali di un audit — quanti prodotti sono conformi e quanti no — senza tenere in memoria l'intero catalogo. Il risultato finale è visibile sul nodo, nell'ispettore dell'esecuzione.

Variabili e contesto

I workflow usano variabili per passare dati tra i nodi. La sintassi è {{ ... }} e ci sono tre origini:

Variabile	Da dove proviene	Esempio
{{trigger.X}}	Dati inviati al workflow al momento dell'esecuzione manuale.	{{trigger.email}}
{{nodes.NOME.result.X}}	Output di un nodo precedente.	{{nodes.checkTitle.result.titleTooLong}}
{{forEach.NOME}}	L'elemento corrente quando sei all'interno di un ciclo. Per default si chiama item, ma i modelli usano nomi più leggibili come product.	{{forEach.product}}

Esempio d'uso in una Condizione: valutare se il risultato di un nodo di codice indica che il titolo è troppo corto:

• Campo: {{nodes.checkTitle.result.titleTooLong}}
• Operatore: è vero

Selezione delle campagne (Smart Campaigns)

Il workflow Smart Campaigns Optimizer offre, nella sua scheda Variabili, un controllo per decidere su quali campagne agisce.

Prendere tutte le campagne con ACOS obiettivo configurato (interruttore):

• Attivo — il workflow gestisce automaticamente ogni campagna che ha l'ACOS/ROAS obiettivo e l'offerta massima configurati.
• Disattivato — selezione manuale: il workflow agisce solo sulle campagne che scegli. Quando aggiungi un nuovo workflow, l'interruttore nasce disattivato. Si salva all'istante (senza premere «Salva modifiche»).

Con l'interruttore disattivato si abilita il pulsante Campagne dell'algoritmo, che apre una tabella dove, per ogni campagna (Sponsored Products):

Colonna	Cosa fa
Ottimizza	Se il workflow deve ottimizzare quella campagna. Attivabile solo se la campagna ha un obiettivo definito.
Obiettivo	Tipo di obiettivo — ACOS o ROAS.
Valore	Il valore obiettivo (es. 25% di ACOS).

La tabella è paginata, ha una ricerca e mostra prima le campagne già gestite. Le modifiche si salvano con il pulsante Salva della finestra.

Relazione con le Impostazioni IA per campagna

Selezionare una campagna qui equivale a forzare quel workflow dalle Impostazioni IA della campagna: è la stessa informazione vista dal lato del workflow, e l'obiettivo che modifichi è quello della campagna.

Se, con l'interruttore disattivato, non selezioni nessuna campagna, il workflow non ne elabora nessuna — non fallisce, semplicemente non agisce finché non scegli.

Attività e supervisione umana

I workflow possono generare attività affinché un umano riveda i loro risultati prima di applicare modifiche. Questo è il punto di forza del sistema: l'automazione rileva problemi, ma non applica nulla finché tu non approvi.

Nodo Crea attività

Quando un workflow rileva un problema, questo nodo crea un'attività (o aggiunge elementi a un'attività esistente). Gli elementi possono includere un valore suggerito (auto-correzione) che l'utente può accettare con un clic.

• Idempotenza — il workflow usa una chiave univoca per problema. Riavviare il workflow non duplica attività: aggiunge elementi nuovi se compaiono problemi nuovi, e lascia in pace quelli già presenti.
• HITL (Human-in-the-Loop) — se attivato, gli elementi non si applicano automaticamente. Un umano li revisiona e approva prima che arrivino al prodotto o alla campagna.

Nodo Risolvi attività

Segna come risolti gli elementi di un'attività i cui problemi non esistono più. Utile quando rilanci un workflow e un prodotto che prima falliva ora è conforme — il nodo chiude automaticamente gli elementi associati.

Più dettagli sul sistema di attività in Attività.

Storico delle esecuzioni

Ogni volta che un workflow si esegue, l'esecuzione viene registrata e consultabile dalla sua pagina. Gli stati possibili sono:

Stato	Significato
In attesa	In coda, non è ancora partita.
In esecuzione	In corso.
Completata	Terminata senza errori.
Parziale	Terminata, ma alcuni elementi sono falliti e non sono stati elaborati. Compare nei workflow che iterano: per esempio una campagna che fallisce mentre le altre vengono ottimizzate normalmente.
Fallita	Un nodo è fallito e ha interrotto il flusso.
Annullata	Fermata manualmente.

Ispettore di esecuzione

Clicca su un nodo all'interno di un'esecuzione per aprire l'ispettore e vedere:

• Input — le variabili risolte che il nodo ha ricevuto.
• Output — il risultato che ha prodotto.
• Errore — se applicabile, con un messaggio leggibile.

Debug di un'esecuzione fallita

Inizia dal primo nodo segnato in rosso. Leggi il suo output o il suo errore. Controlla le variabili di input — la maggior parte dei fallimenti deriva da un riferimento rotto a un nodo precedente o da dati vuoti dove era atteso un valore.

Creare workflow con VelaxAI

VelaxAI include un agente specializzato che genera workflow dal linguaggio naturale. L'utente descrive cosa vuole automatizzare e VelaxAI propone un workflow completo: nodi, connessioni, condizioni e, quando serve, il codice dei nodi Esegui codice.

Cosa puoi fare:

• Descrivere la tua esigenza in una conversazione.
• Chiedere modifiche alla proposta iniziale.
• Revisionare e modificare manualmente il codice generato nei nodi Esegui codice.
• Regolare il trigger (pianificazione, intervallo).
• Attivare il workflow quando sei soddisfatto.

Generazione in evoluzione

La generazione con VelaxAI continua a migliorare. Workflow molto complessi possono richiedere aggiustamenti manuali dopo la generazione iniziale — VelaxAI ti indicherà cosa manca o cosa validare.

Di più su VelaxAI in VelaxAI.

Buone pratiche e limiti

• Attiva HITL quando il workflow modifica dati sensibili (prezzi, titoli, descrizioni, budget di campagna). Ti dà un punto di controllo prima che la modifica arrivi ad Amazon.
• Controlla il costo stimato prima di attivare un workflow pianificato, soprattutto se itera su tutto il catalogo. Un'esecuzione manuale preliminare ti mostra il costo reale.
• Inizia in pausa. Lancia il workflow manualmente una volta per validare il risultato, e solo allora attiva il cron.
• Le esecuzioni fallite non si ritentano da sole. Se un'esecuzione fallisce, apri lo storico, identifica il nodo in errore, correggi la causa e rilancia manualmente.
• Per audit massivi, preferisci i modelli — sono ottimizzati per elaborare grandi cataloghi con batch e gestione errori per elemento.