Come funzionano gli snippet di codice in Automation

Gli snippet di codice ti permettono di aggiungere un tuo step JavaScript a un workflow di Automation. Usali quando le condizioni e le azioni predefinite non bastano: per chiamare il tuo OMS, ERP o sistema di magazzino, per calcolare un punteggio o un valore a partire dai dati dell'ordine, o per bloccare un ordine prima della spedizione quando un sistema esterno lo richiede.

Come funziona

L'azione Run code snippet esegue uno snippet di codice: una piccola funzione JavaScript che scrivi una volta e riutilizzi in qualsiasi workflow. Quando il workflow viene eseguito, ShippyPro passa allo snippet i dati dell'ordine che hai selezionato, lo esegue in una sandbox sicura e restituisce i risultati al workflow.

1. Scrivi lo snippet nella sezione Snippet di codice di Automation: il codice, i dati dell'ordine che legge (input), i risultati che restituisce (output), i secret che usa e gli host esterni che può chiamare.
2. Testalo con valori di esempio prima di salvarlo.
3. Invialo in revisione. Ogni versione viene controllata automaticamente prima di poter essere eseguita.
4. Aggiungilo a un workflow con l'azione Run code snippet, associa i suoi input ai campi dell'ordine e salva il workflow.

Trigger disponibili

Un workflow con l'azione Run code snippet può partire con questi trigger:

• Ordine importato
• Etichetta di spedizione creata
• Etichetta stampata
• Ordine in errore
• Qualsiasi altro trigger disponibile in ShippyPro

Ogni snippet esporta una funzione asincrona chiamata main. Riceve un event e restituisce un oggetto con outputFields:

export async function main(event) {
const { orderId, orderTotal, destinationCountry } = event.inputFields;
const { MY_API_KEY } = event.secrets;

const res = await fetch('https://api.example.com/orders/check', {
method: 'POST',
headers: { 'content-type': 'application/json', 'x-api-key': MY_API_KEY },
body: JSON.stringify({ orderId, orderTotal, destinationCountry }),
});

if (!res.ok) {
throw new Error(`Check failed: HTTP ${res.status}`);
}

const { approved, reason } = await res.json();
return { outputFields: { approved, reason } };
}

Input

Gli input sono i campi dell'ordine che lo snippet legge, ad esempio ID ordine, totale, valuta, paese di destinazione, indirizzo o articoli. Assegni a ogni input un nome e lo associ a un campo dell'ordine quando aggiungi lo step a un workflow. Nel codice sono disponibili in event.inputFields. Gli articoli dell'ordine arrivano come lista, in cui ogni articolo ha nome, SKU, EAN, quantità e peso.

Output

Gli output sono i valori che lo snippet restituisce. Dichiara ciascuno con un nome e un tipo: testo (string), numero (number), vero/falso (boolean), data e ora (datetime) o una lista di valori consentiti (enum). I valori restituiti devono corrispondere ai tipi dichiarati.

Puoi usare gli output nelle note scritte dalle azioni successive dello stesso workflow, ad esempio per salvare il magazzino scelto dal tuo OMS o il motivo per cui un ordine è stato bloccato.

Secret

Salva chiavi API e token come secret, mai nel codice. Il nome di un secret usa lettere maiuscole, numeri e underscore (ad esempio OMS_API_KEY). Nel codice leggilo da event.secrets. Dopo il salvataggio, i valori dei secret non vengono più mostrati.

Chiamate esterne

Gli snippet possono chiamare API esterne con fetch. Per sicurezza, uno snippet può chiamare solo gli host indicati nelle sue impostazioni (fino a 10, ad esempio api.example.com o *.example.com) e solo tramite HTTPS.

Limiti

La sandbox mette a disposizione JavaScript standard (JSON, Math, Date, URL), fetch e console.log. Timer, accesso ai file, moduli Node.js e import di pacchetti non sono disponibili.

Quando lo snippet fallisce

Uno snippet fallisce quando genera un errore, va in timeout o restituisce valori che non corrispondono ai suoi output. Sei tu a scegliere cosa succede all'ordine, nell'impostazione If the snippet fails dello snippet:

• Stop the workflow (interrompi il workflow): all'ordine vengono aggiunti il tag automation-blocked e una nota con il messaggio di errore, così il tuo team vede perché è stato bloccato. Generare un errore con un messaggio chiaro è il modo per bloccare un ordine di proposito, ad esempio quando il tuo controllo antifrode o di disponibilità di magazzino indica che non deve essere spedito.
• Skip this step and continue (salta lo step e continua): lo step viene saltato e il resto del workflow viene eseguito.
• Retry, then stop the workflow (riprova, poi interrompi il workflow): lo step viene ritentato alcune volte prima che il workflow si interrompa.

Versioni e revisione

Ogni volta che modifichi uno snippet salvi una nuova versione, che viene revisionata prima di poter essere eseguita. Le versioni già salvate non cambiano mai. Un workflow continua a usare la versione con cui è stato salvato: per passare a una versione più recente, apri lo step Run code snippet, seleziona la nuova versione e salva il workflow.

Consigli

• Uno snippet per ramo del workflow. Per eseguire più snippet sullo stesso ordine, crea un workflow per ciascuno e imposta le loro priorità: i workflow con priorità più alta vengono eseguiti per primi.
• Rendi gli snippet sicuri da eseguire due volte. Un workflow può essere eseguito di nuovo sullo stesso ordine, quindi verifica se il tuo sistema esterno ha già l'ordine prima di creare o modificare qualcosa.
• Scrivi messaggi di errore chiari. Con Stop the workflow il messaggio diventa la nota sull'ordine, quindi scrivilo pensando a chi lo leggerà.
• Registra nei log ciò che conta. Usa console.log per i valori che vuoi controllare in seguito; non registrare mai i secret.

Esempi di utilizzo

• Invia gli ordini al tuo OMS e salva in una nota il magazzino che ha scelto.
• Calcola il rischio dell'ordine (valore, destinazione, metodo di pagamento) e blocca gli ordini ad alto rischio per una verifica.
• Conferma la spedizione al tuo OMS o ERP quando viene generata l'etichetta.