Questa guida completa ti aiuterà a utilizzare l'attività JavaScript all'interno di Workflow builder. Scoprirai i concetti chiave, le funzioni disponibili, come accedere e modificare il contesto del flusso di lavoro e le best practice per scrivere codice JavaScript efficace. Alla fine di questo articolo, avrai una chiara comprensione di come sfruttare JavaScript per migliorare i tuoi flussi di lavoro.

Comprendere l'attività JavaScript

L'attività JavaScript in Workflow Builder ti consente di eseguire codice JavaScript personalizzato direttamente all'interno dei tuoi flussi di lavoro. Questa funzione consente una manipolazione avanzata dei dati, l'impostazione della logica condizionale e l'integrazione con altri sistemi, a seconda della configurazione del flusso di lavoro. Il codice JavaScript viene eseguito in un ambiente sicuro basato su Goja, che è un'implementazione Go pura di ECMAScript 5.1, garantendo stabilità e sicurezza.

Funzioni e oggetti disponibili

Nell'attività JavaScript, hai accesso a un set limitato di oggetti JavaScript integrati e a una funzione personalizzata log per registrare i messaggi. Gli oggetti disponibili includono:

Math: fornisce funzioni e costanti matematiche (ad esempio Math.random(), Math.floor()).
JSON: metodi per l'analisi e la conversione in stringa dei dati JSON (ad esempio, JSON.parse(), JSON.stringify()).
Date: funzioni per la gestione di date e orari (ad esempio, new Date(), Date.now()).
Array: l'oggetto Array globale per la manipolazione degli array.
String: l'oggetto String globale per la manipolazione del testo.
Number: l'oggetto Number globale per le operazioni numeriche.
Boolean: l'oggetto Boolean globale per i valori true/false.
Errore: l'oggetto globale Errore per la gestione degli errori.
log: una funzione personalizzata per inviare messaggi ai log dell'attività.

Esempio di utilizzo della funzione log:

JavaScript

log("This message will appear in the activity logs.");log("The value of a variable is: " + someVariable);

Accesso al contesto del workflow

Il tuo codice JavaScript può accedere all'intero contesto del workflow tramite una variabile globale denominata context. Questo oggetto contiene lo stato e i dati attuali del tuo workflow, consentendoti di leggere e modificare i valori come consentito dalla configurazione del tuo workflow.

Ecco un esempio di una tipica struttura context:

JSON

{  "flow:batch:0": {    "batchUid": "692576827",    "batchedBy": {      "CoatingType": "glossy-lamination",      "ColorType": "4-4"    },    "quantity": "1"  },  "payload": {    "facility": {      "countryId": "DE",      "name": "DE_GCSB",      "timeZone": "Europe/Berlin"    },    "files": {      "default": "https://..."    },    "order": {      "amount": "19.99",      "clientId": "test-orders",      "deliveryAddress": {        "address_line_1": "123 Test St",        "city": "Testville",        // ... more address details      },      // ... more order details    },    "part": {      "id": "7101535136",      "productDetails": {        "attributes": {          "CoatingType": "glossy-lamination",          "ColorType": "4-4",          // ... more attributes        },        "derivedAttributes": {          "height": {            "value": "55"          },          // ... more derived attributes        }      }    }    // ... more payload data  },  "step:print:0": {    "machine": {      "0": "digital-presses-hp-indigo-7900",      "#": "1"    },    "machineTypes": "digital-presses",    "sheetSizes": {      "0": "sra3",      "#": "1"    }  }}

L'oggetto context contiene molti dati, tra cui payload, flow:batch:0 e step:print:0.

Esempi di accesso ai valori dal context:

JavaScript

// Get the client ID from the order payloadvar clientId = context.payload.order.clientId;log("Client ID: " + clientId);// Access a product attributevar coatingType = context.payload.part.productDetails.attributes.CoatingType;log("Product Coating Type: " + coatingType);// Access a derived attribute's valuevar productHeight = context.payload.part.productDetails.derivedAttributes.height.value;log("Product Height: " + productHeight);// Get the customer's city from the delivery addressvar city = context.payload.order.deliveryAddress.city;log("Delivery City: " + city);// You can also modify context values (if allowed by workflow permissions)context.payload.order.deliveryAddress.city = "New Testville";log("Updated Delivery City: " + context.payload.order.deliveryAddress.city);

Nota importante: la struttura dell'oggetto context varia in base al flusso di lavoro specifico. Fai sempre riferimento all'input del flusso di lavoro e agli output delle attività precedenti per individuare i percorsi dei dati corretti.

Scrivere il tuo codice JavaScript

Il tuo codice JavaScript verrà automaticamente racchiuso in un'espressione di funzione invocata immediatamente (IIFE) per un'esecuzione sicura. Non è necessario includere questo wrapper nel tuo codice; scrivi semplicemente le istruzioni JavaScript che desideri eseguire.

Restituzione dei risultati

L'attività JavaScript può restituire valori che verranno memorizzati nell'output dell'attività. Il formato del valore restituito dipende dal suo tipo:

Restituzione di un oggetto JavaScript: le proprietà verranno mappate come coppie chiave-valore nel JSCodeOutput.
Restituzione di altri valori: valori come stringhe, numeri, booleani o array saranno racchiusi sotto una chiave predefinita chiamata "result" nel JSCodeOutput.

Esempio: restituzione di un oggetto

JavaScript

var myResult = {  status: "success",  message: "Order processed",  orderId: context.payload.order.id};return myResult;

Questo produrrà un risultato simile a:

JSON

{  "flow:js-script:1": {    "message": "Order processed",    "orderId": "048aa79f-7d6e-45bd-930a-81be07be0f19",    "status": "success"  },  "payload": {...}}

Esempio: restituzione di un valore non oggetto (stringa)

JavaScript

return "Processing complete for order " + context.payload.order.customerOrderId;

Questo genererà un output come:

JSON

{  "result": "Processing complete for order test-order-ref"}

Esempio: restituzione di un array

JavaScript

var attributes = context.payload.part.productDetails.attributes;var attributeNames = Object.keys(attributes);return attributeNames;

Questo genererà un output come:

JSON

{  "result": ["CoatingType", "ColorType", "Orientation", "PaperFormat", "PaperType", "ProductStatus", "ProtectionType", "ShapeEdgeType", "SpotFinishingType", "State", "Variable"]}

Debug e registrazione

La funzione log() è essenziale per il debug all'interno dell'attività JavaScript. Tutti i messaggi inviati a log() verranno visualizzati nella sezione Log dell'output dell'attività, permettendoti di monitorare il flusso di esecuzione e ispezionare i valori delle variabili.

Buone pratiche

Rimani concentrato: utilizza l'attività JavaScript per trasformazioni di dati specifiche o controlli condizionali. La logica più complessa è meglio gestita da passaggi di workflow dedicati o servizi esterni.
Usa try...catch: racchiudi il tuo codice in blocchi try...catch per gestire con eleganza gli errori imprevisti ed evitare che il workflow fallisca.
Convalida gli input: verifica sempre che i dati del contesto esistano e siano nel formato previsto prima di utilizzarli.
Testa accuratamente: testa rigorosamente il tuo codice JavaScript con vari input per garantire un comportamento corretto in diversi scenari.

Seguendo queste linee guida, potrai utilizzare efficacemente l'attività JavaScript per introdurre una logica personalizzata potente e flessibile nei tuoi flussi di lavoro di Workflow builder.

📝 Non era quello che cercavi?

Aiutaci a migliorare questo articolo, inviaci un'email a [email protected] — ricordati di includere il titolo dell'articolo.