RuleNodes

I RuleNode sono i blocchi funzionali di una RuleChain in optiCLOUD. Determinano come i messaggi in ingresso vengono filtrati, arricchiti, trasformati, salvati o inoltrati ad altri sistemi.

Questa pagina serve come orientamento pratico sui nodi disponibili e sui loro ambiti di impiego:

Quali nodi esistono?
A cosa servono?
Quali uscite o relazioni hanno?

Panoramica per categorie

Nodi di filtro

RuleNode	Scopo
Message Type Filter	Lascia passare solo determinati tipi di messaggio
Message Type Switch	Distribuisce i messaggi su percorsi diversi in base al tipo di messaggio
File Type Switch	Ramifica i messaggi di file in base al tipo di file
File Names Filter	Filtra i nomi dei file in base ai prefissi
Device Filter	Limita l'elaborazione a determinati dispositivi
Script (Filter)	Esegue una logica di filtro definita liberamente tramite JavaScript
Switch	Inoltra i messaggi a uscite dinamiche tramite script
Check Existence Fields	Verifica se i campi sono presenti nel messaggio o nei metadati
GPS Geofencing Filter	Lascia passare solo i messaggi all'interno di un geofence

Nodi di azione

RuleNode	Scopo
Save Timeseries	Salva la telemetria come serie temporale
Save Attributes	Salva gli attributi in uno scope selezionato
Save Alarms	Salva gli stati di allarme dai messaggi di allarme
Create Alarm	Crea o aggiorna un allarme
Clear Alarm	Termina un allarme esistente
Alarm Counter	Conta gli allarmi all'interno di una finestra temporale
Log	Scrive output di debug o di log
Generator	Genera messaggi periodicamente
Message Count	Conta i messaggi in ingresso e pubblica il contatore
Delay	Ritarda l'inoltro di un messaggio
Aggregate OSF File	Legge file OSF e ne ricava telemetria
Aggregate JSONL File	Legge file JSONL e ne ricava telemetria
Process Raw Data File	Elabora le operazioni sui file nel blob storage
Generate Report	Crea rapporti su un periodo definito
Device System	Aggrega dati di più dispositivi
GPS Geofencing Events	Genera eventi all'ingresso o all'uscita da un geofence
RPC Call Request	Invia una chiamata RPC a un dispositivo
RPC Call Reply	Risponde a una chiamata RPC in ingresso

Nodi di arricchimento

RuleNode	Scopo
Originator Attributes	Carica gli attributi dell'elemento di origine nei metadati
Originator Telemetry	Carica la telemetria dell'elemento di origine nei metadati
Originator Fields	Integra i dati anagrafici dell'elemento di origine
Tenant Details	Integra le informazioni del tenant

Nodi di trasformazione

RuleNode	Scopo
Script (Transform)	Modifica messaggio, metadati o tipo di messaggio tramite JavaScript
To Email	Costruisce un oggetto e-mail a partire da un messaggio

Nodi esterni

RuleNode	Scopo
REST API Call	Invia dati a un'interfaccia REST esterna
MQTT	Pubblica messaggi su un broker MQTT
Kafka	Pubblica messaggi in un topic Kafka
RabbitMQ	Invia messaggi a RabbitMQ
AWS SQS	Invia messaggi a una coda SQS
AWS SNS	Pubblica messaggi su un topic SNS
GCP Pub/Sub	Pubblica messaggi su Google Pub/Sub
Send Email	Invia un'e-mail tramite SMTP

Nodi scheduler

RuleNode	Scopo
Create Scheduled Task	Pianifica un'esecuzione singola differita nel tempo
Clear Scheduled Task	Elimina un'attività pianificata in precedenza

Nodi di eventi e allarmi

RuleNode	Scopo
Complex Alarm	Crea allarmi in base a schemi complessi in tempo reale
Complex Event Processing	Valuta i dati dei file con regole di evento
Enrich Alarm	Integra gli allarmi esistenti con informazioni aggiuntive

Panoramica di dettaglio

Nodi di filtro

Message Type Filter

Categoria: Filtro
Uscite: True, False

Il nodo verifica se il tipo di messaggio del messaggio in ingresso è contenuto in un elenco configurato. In caso di corrispondenza il messaggio prosegue tramite True, altrimenti tramite False.

Configurazione

Label	Obbligatorio	Descrizione
Message Types Filter	Sì	Elenco dei tipi di messaggio consentiti. Deve essere inserito almeno un tipo.

I valori supportati sono, tra gli altri, POST_ATTRIBUTES_REQUEST, POST_TELEMETRY_REQUEST, TO_SERVER_RPC_REQUEST, TO_DEVICE_RPC_REQUEST, ACTIVITY_EVENT, INACTIVITY_EVENT, CONNECT_EVENT, DISCONNECT_EVENT, BLOB_STORE_REQUEST e POST_ALARMS.

Esempio

Utilizzare questo nodo quando, ad es., devono essere elaborati ulteriormente solo i dati di telemetria. In questo caso si configura POST_TELEMETRY_REQUEST e si collega l'uscita TRUE a un ulteriore nodo, che riceverà quindi con certezza solo messaggi di tipo POST_TELEMETRY_REQUEST.

Message Type Switch

Categoria: Filtro
Uscite: una per tipo di messaggio più Other

Il nodo distribuisce i messaggi su uscite fisse in base al loro tipo di messaggio. È adatto come distributore iniziale in una RuleChain, quando tipi di messaggio diversi devono essere elaborati in rami separati.

Configurazione

Questo nodo non ha opzioni configurabili. Le uscite sono definite in modo fisso.

Uscita	Condizione
`POST_ATTRIBUTES`	Il tipo di messaggio è `POST_ATTRIBUTES_REQUEST`
`POST_TELEMETRY`	Il tipo di messaggio è `POST_TELEMETRY_REQUEST`
`POST_ALARMS`	Il tipo di messaggio è `POST_ALARMS`
`BLOB_STORE_REQUEST`	Il tipo di messaggio è `BLOB_STORE_REQUEST`
`RPC_REQUEST_FROM_DEVICE`	Il tipo di messaggio è `TO_SERVER_RPC_REQUEST`
`RPC_REQUEST_TO_DEVICE`	Il tipo di messaggio è `TO_DEVICE_RPC_REQUEST`
`ACTIVITY_EVENT`	Il tipo di messaggio è `ACTIVITY_EVENT`
`INACTIVITY_EVENT`	Il tipo di messaggio è `INACTIVITY_EVENT`
`CONNECT_EVENT`	Il tipo di messaggio è `CONNECT_EVENT`
`DISCONNECT_EVENT`	Il tipo di messaggio è `DISCONNECT_EVENT`
`Other`	Tutti gli altri tipi di messaggio

Esempio

In una Root RuleChain questo nodo può trovarsi subito dopo l'ingresso, per suddividere telemetria, attributi, allarmi, messaggi RPC e operazioni sui file in rami di elaborazione separati.

File Type Switch

Categoria: Filtro
Uscite: OSF, JSONL, Other

Il nodo ramifica i messaggi di file in base all'estensione del file. Viene impiegato nelle pipeline di file, dopo che un'operazione su file è stata riconosciuta come BLOB_STORE_REQUEST.

Configurazione

Questo nodo non ha opzioni configurabili. Il riconoscimento avviene in base all'estensione del file nei metadati.

Uscita	Estensioni di file riconosciute
`OSF`	`.osf`, `.osfz`
`JSONL`	`.log`, `.log.gz`
`Other`	Tutte le altre estensioni di file

Esempio

Inoltrare i file .osf ad es. a Aggregate OSF File.

File Names Filter

Categoria: Filtro
Uscite: True, False

Il nodo lascia proseguire i messaggi di file tramite True solo se il nome del file inizia con uno dei prefissi configurati.

Configurazione

Label	Obbligatorio	Descrizione
File Prefixes	Sì	Elenco di prefissi di nomi di file. Il controllo è case-sensitive.

Note

Un elenco di prefissi vuoto comporta che tutti i messaggi proseguano tramite False.
Il nome del file viene letto dai metadati del messaggio, di norma da fileName.

Esempio

Se un dispositivo carica file con data_ e config_, è possibile utilizzare due File Names Filter per elaborare separatamente i due gruppi di file.

Device Filter

Categoria: Filtro
Uscite: True, False

Il nodo limita l'elaborazione a determinati dispositivi. L'elenco dei dispositivi può essere utilizzato, a seconda dell'impostazione, come elenco di abilitazione o elenco di blocco.

Configurazione

Label	Obbligatorio	Descrizione
Devices	Sì	Selezione dei dispositivi tramite selezione multipla.
Allow selected devices	Sì	Attivato: solo i dispositivi selezionati proseguono tramite `True`. Disattivato: i dispositivi selezionati vengono bloccati.

Uscite

Uscita	Condizione
`True`	Il dispositivo è consentito o non bloccato
`False`	Il dispositivo non è consentito o è bloccato esplicitamente

Esempio

Se una regola deve essere eseguita solo per determinati dispositivi, è possibile anteporre alla regola il DeviceFilter, in modo che inoltri alla regola successiva solo una selezione di dispositivi.

Script (Filter)

Categoria: Filtro
Uscite: True, False

Il nodo esegue una funzione JavaScript. Se lo script restituisce true, il messaggio prosegue tramite True. Con false o in caso di errore dello script, prosegue tramite False.

Configurazione

Label	Obbligatorio	Descrizione
Filter Function	Sì	Funzione JavaScript con la firma `Filter(msg, metadata, msgType)`.

Contesto dello script

Variabile	Descrizione
`msg`	Corpo del messaggio JSON
`metadata`	Metadati del messaggio
`msgType`	Tipo di messaggio

Esempio

var threshold = parseFloat(metadata.tempThreshold) || 50;
return msg.temperature > threshold;

Switch

Categoria: Filtro
Uscite: dinamiche tramite script

Il nodo inoltra un messaggio a una o più uscite denominate. I nomi delle uscite vengono restituiti come array da una funzione JavaScript.

Configurazione

Label	Obbligatorio	Descrizione
Switch Function	Sì	Funzione JavaScript con la firma `Switch(msg, metadata, msgType)`.

Lo script deve restituire un array di stringhe. Ogni stringa corrisponde a un nome di uscita.

Note

I nomi di uscita non collegati vengono ignorati.
Un array vuoto scarta il messaggio.
Per tutti i possibili valori restituiti dovrebbero essere create nella RuleChain le connessioni corrispondenti.

Esempio

Con la seguente funzione è possibile, ad es., verificare il valore di temperatura di un messaggio e inoltrare i messaggi in modo diverso in base al valore.

La connessione "highTemp" potrebbe essere inoltrata, ad es., a un nodo di allarme che genera un allarme "High Temperature"
La connessione "lowTemp" potrebbe essere inoltrata, ad es., a un nodo di allarme che genera un allarme "Low Temperature"
La connessione "normalTemp" potrebbe essere inoltrata, ad es., a un nodo che imposta un attributo "TempStatus = OK"

function nextRelation(msg) {
    if(msg.temperature > 50){
      return ['highTemp'];
    } else if (msg.temperature < 20){
      return ['lowTemp'];
    } else {
      return ['normalTemp'];
    }
    
}
return nextRelation(msg);

Check Existence Fields

Categoria: Filtro
Uscite: True, False

Il nodo verifica se determinati campi sono presenti nel corpo del messaggio e/o nei metadati. In questo modo i nodi successivi possono essere protetti da messaggi incompleti.

Configurazione

Label	Obbligatorio	Descrizione
Message Data	No	Nomi dei campi che devono essere presenti nel corpo del messaggio.
Message Metadata	No	Nomi dei campi che devono essere presenti nei metadati.
Check All Keys Present	Sì	Attivato: tutti i campi indicati devono essere presenti. Disattivato: deve essere presente almeno un campo.

Almeno uno dei due campi messageNames o metadataNames deve contenere voci.

Esempio

Prima di un nodo Script è possibile verificare, ad es., se tutti i canali utilizzati nello script sono presenti anche nel messaggio. Ciò evita che lo script fallisca e riduce la complessità dello script, in cui altrimenti si dovrebbero eventualmente adottare precauzioni tramite condizioni if/else per verificare se i canali sono presenti. Se questo nodo è anteposto a un nodo Script, nel nodo Script si può partire dal presupposto che i canali siano presenti nel messaggio.

GPS Geofencing Filter

Categoria: Filtro
Uscite: True, False

Il nodo verifica se le coordinate GPS si trovano all'interno di un geofence definito. Il controllo è privo di stato e valuta di volta in volta il messaggio corrente.

Configurazione

Label	Obbligatorio	Descrizione
Latitude Key Name	Sì	Nome del campo per la latitudine nel corpo del messaggio.
Longitude Key Name	Sì	Nome del campo per la longitudine nel corpo del messaggio.
Fetch Perimeter Info from Metadata	Sì	Attivato: la definizione del geofence viene letta dai metadati. Disattivato: il geofence viene configurato in modo statico nel nodo.
Perimeter Type	Sì, con configurazione statica	`Circle` o `Polygon`.
Campi Circle	Sì, con cerchio	Centro, raggio e unità del cerchio.
Polygon Definition	Sì, con poligono	Definizione GeoJSON o WKT del poligono.

Nota

Per gli eventi di ingresso/uscita basati sullo stato si utilizza GPS Geofencing Events.

Esempio

Elaborare, ad es., la telemetria solo quando un veicolo si trova all'interno di una zona definita; in caso contrario la telemetria viene scartata.

Nodi di azione

Save Timeseries

Categoria: Azione
Uscite: Success, Failure

Il nodo salva i dati di telemetria dal corpo del messaggio come valori di serie temporale nel database.

Configurazione

Label	Obbligatorio	Descrizione
Default TTL	Sì	Durata di vita dei punti dati salvati in secondi. `0` significa nessuna eliminazione automatica.
Enable Type Cast	Sì	Converte valori numerici o booleani da stringhe in tipi di dati nativi.

Ingresso

Il tipo di messaggio deve essere POST_TELEMETRY_REQUEST. Il corpo del messaggio deve essere un oggetto JSON oppure contenere un array di oggetti JSON con timestamp ts.

Save Attributes

Categoria: Azione
Uscite: Success, Failure

Il nodo salva le coppie chiave-valore dal corpo del messaggio come attributi dell'entità di origine.

Configurazione

Label	Obbligatorio	Descrizione
Attribute Scope	Sì	Scope di destinazione per gli attributi.
Enable Type Cast	Sì	Converte valori numerici o booleani da stringhe in tipi di dati nativi.

Scope	Significato
`CLIENT_SCOPE`	Attributi comunicati dal dispositivo, visibili al dispositivo.
`SHARED_SCOPE`	Attributi impostati lato server, che possono essere distribuiti al dispositivo.
`SERVER_SCOPE`	Attributi interni al server, che non vengono inviati al dispositivo.

Ingresso

Il corpo del messaggio deve essere un oggetto JSON. Ogni chiave viene salvata come nome di attributo.

Save Alarms

Categoria: Azione
Uscite: Activated, Deactivated, Sustained

Il nodo elabora i messaggi di tipo POST_ALARMS e salva gli stati di allarme nel database. In questo modo rappresenta i cambiamenti di stato degli allarmi.

Uscite

Uscita	Significato
`Activated`	Un nuovo allarme è stato aperto oppure un allarme eliminato è tornato attivo.
`Deactivated`	Un allarme attivo è stato terminato.
`Sustained`	Un allarme già attivo rimane attivo.

Configurazione

Label	Obbligatorio	Descrizione
Propagate	Sì	Indica se gli allarmi vengono propagati alle entità sovraordinate.

Ingresso

Il messaggio deve essere di tipo POST_ALARMS e contenere i dati dell'allarme secondo il modello di allarme della piattaforma.

Create Alarm

Categoria: Azione
Uscite: Created, Updated, False

Il nodo crea un allarme per l'origine del messaggio oppure aggiorna un allarme già esistente dello stesso tipo. I dettagli dell'allarme vengono costruiti tramite JavaScript a partire da messaggio e metadati.

Uscite

Uscita	Significato
`Created`	È stato creato un nuovo allarme.
`Updated`	È stato aggiornato un allarme esistente di questo tipo.
`False`	Lo script non ha generato alcun allarme.

Configurazione

Label	Obbligatorio	Descrizione
Alarm Details Builder	Sì	Funzione JavaScript `Details(msg, metadata, msgType)` per i dettagli dell'allarme.
Alarm Type	Sì	Tipo di allarme. Supporta pattern `${metadata.key}`.
Alarm Severity	Sì	Livello di gravità: `CRITICAL`, `MAJOR`, `MINOR`, `WARNING`, `INDETERMINATE`.
Propagate	Sì	Propaga l'allarme alle entità sovraordinate.

Metadati dopo l'elaborazione

Il nodo aggiunge, tra l'altro, alarmType, alarmIsNew, alarmSeverity e alarmId.

Esempio

Uno Script Filter a monte verifica msg.temperature > 80. Con True questo nodo crea un allarme HighTemperature con livello di gravità MAJOR. Nei dettagli potrebbe trovarsi, ad es., una funzione che registra il valore massimo di temperatura per tutto il tempo in cui un allarme è stato attivo e aggiornato

var details = {};
if (metadata.prevAlarmDetails) {
    details = JSON.parse(metadata.prevAlarmDetails);
    if (parseFloat(details.highestTemp) < msg.temperature){
        details.highestTemp = msg.temperature;
    }
}
return details;

Clear Alarm

Categoria: Azione
Uscite: Cleared, False

Il nodo termina un allarme attivo del tipo configurato per l'origine del messaggio.

Uscite

Uscita	Significato
`Cleared`	È stato trovato e terminato un allarme attivo corrispondente.
`False`	Non è stato trovato alcun allarme attivo corrispondente.

Configurazione

Label	Obbligatorio	Descrizione
Alarm Details Builder	Sì	Funzione JavaScript per i dettagli finali dell'allarme al momento della chiusura.
Alarm Type	Sì	Tipo di allarme, che deve corrispondere esattamente all'allarme generato in precedenza.

Metadati dopo l'elaborazione

Il nodo aggiunge alarmType e alarmId.

Esempio

Se un dispositivo comunica nuovamente temperature < 70, Clear Alarm può terminare l'allarme HighTemperature creato in precedenza.

informazioni

Il tipo di allarme è case-sensitive! Se con un nodo Create Alarm è stato creato un allarme di tipo HighTemperature, nel nodo Clear Alarm deve essere inserito esattamente questo tipo di allarme HighTemperature, affinché possa essere cancellato.

Alarm Counter

Categoria: Azione
Uscite: Success, Failure

Il nodo conta gli allarmi secondo i criteri configurati all'interno di una finestra temporale e salva i risultati come attributi server sull'origine del messaggio.

Configurazione

Il nodo contiene un elenco di definizioni di contatori.

Label	Obbligatorio	Descrizione
Find by Field Name	Sì	Campo dell'allarme in base al quale si filtra, ad es. `severity` o `type`.
With Field Value	Sì	Valore che il campo deve avere, ad es. `CRITICAL`.
Save in Server Attribute	Sì	Nome dell'attributo server in cui viene salvato il contatore.
Time Period Alarm Considered	Sì	Finestra temporale considerata in secondi. `0` significa senza limitazione temporale.

Esempio

Con

fieldName = severity
fieldValue = CRITICAL
attributeName = criticalAlarms24h
periodInSeconds = 86400

viene contato il numero di allarmi critici delle ultime 24 ore e salvato nell'attributo server criticalAlarms24h.

Log

Categoria: Azione
Uscite: Success, Failure

Il nodo scrive nel log del server un testo generato tramite JavaScript e inoltra il messaggio originale invariato.

Configurazione

Label	Obbligatorio	Descrizione
Log Function	Sì	Funzione JavaScript `ToString(msg, metadata, msgType)`, che restituisce il testo del log.

Note

Il nodo è pensato soprattutto per sviluppo, analisi e risoluzione degli errori.
Dovrebbe essere utilizzato con parsimonia e preferibilmente solo dopo aver consultato OptiMEAS, poiché un nodo Log ha sostanzialmente senso solo se in precedenza si sono verificati errori che eventualmente l'utente non può risolvere autonomamente.

Generator

Categoria: Azione
Uscite: Success, Failure

Il nodo genera messaggi periodicamente tramite JavaScript e li immette nella RuleChain. Può essere utilizzato per test, simulazioni o flussi temporizzati.

Configurazione

Label	Obbligatorio	Descrizione
Message Count	Sì	Numero di messaggi da generare. `0` significa illimitato.
Period in Seconds	Sì	Intervallo tra i messaggi generati in secondi.
Originator	Sì	Dispositivo di origine per i messaggi generati.
Generator Function	Sì	Funzione JavaScript `Generate(prevMsg, prevMetadata, prevMsgType)`.

La funzione deve restituire msg, metadata e msgType.

Esempio

Se, ad es., si vuole creare e testare una RuleChain ma al momento non si ha a disposizione un dispositivo reale, oppure ne è disponibile uno che proprio in quel momento non invia dati live, con il nodo Generator è possibile generare messaggi artificiali. Per un test adeguato, questi messaggi generati artificialmente dovrebbero riflettere nel modo migliore i messaggi previsti di un dispositivo reale.

Il seguente esempio genera messaggi con:

Canali di telemetria: {"temperature": 42} e {"humidity": 77}

Metadati: {"data": 40}

Tipo: POST_TELEMETRY_REQUEST

var msg = { temperature: 42, humidity: 77 };
var metadata = { data: 40 };
var msgType = "POST_TELEMETRY_REQUEST";

return { msg: msg, metadata: metadata, msgType: msgType };

Nell'esempio precedente si tratta di messaggi statici con sempre gli stessi valori (42,77,40). Un Generator può però generare anche dati variabili, ad es. tramite:

var temp = Math.floor(Math.random() * max);
var hum = Math.floor(Math.random() * max);
var meta = Math.floor(Math.random() * max);

var msg = { temperature: temp, humidity: hum };
var metadata = { data: meta };
var msgType = "POST_TELEMETRY_REQUEST";

return { msg: msg, metadata: metadata, msgType: msgType };

Nota

Negli ambienti di produzione il periodo dovrebbe essere scelto con attenzione, in modo da non generare un carico di messaggi inutilmente elevato.

Message Count

Categoria: Azione
Uscite: Success, Failure

Il nodo conta i messaggi all'interno di un intervallo di tempo e pubblica il valore del contatore come telemetria.

Configurazione

Label	Obbligatorio	Descrizione
Interval in Seconds	Sì	Durata della finestra di conteggio in secondi.
Output Timeseries Key Prefix	Sì	Chiave di telemetria per il valore del contatore.

Output

Al termine di ogni intervallo viene generato un messaggio POST_TELEMETRY_REQUEST, ad es.:

{
  "messageCount": 42
}

I messaggi in ingresso vengono inoltre inoltrati invariati tramite Success.

Delay

Categoria: Azione
Uscite: Success, Failure

Il nodo trattiene i messaggi per una durata configurata e li inoltra successivamente. Il ritardo può essere determinato in modo statico o tramite i metadati.

Configurazione

Label	Obbligatorio	Descrizione
Use Metadata Period Pattern	Sì	Attiva un ritardo dinamico tramite i metadati.
Period in Seconds	Sì, se statico	Ritardo statico in secondi.
Period in Seconds Pattern	Sì, se dinamico	Campo dei metadati o espressione `${...}` per il ritardo.
Max Pending Messages	Sì	Numero massimo di messaggi memorizzati temporaneamente.

Note

In caso di riavvio del server i messaggi in attesa vanno persi, poiché non vengono salvati in modo persistente
Se si raggiunge il numero massimo di messaggi, i nuovi messaggi proseguono tramite Failure.

Aggregate OSF File

Categoria: Azione
Uscite: Success, Failure

Il nodo carica un file OSF referenziato da un BLOB_STORE_REQUEST e lo elabora.

Ingresso e output

Ingresso: BLOB_STORE_REQUEST con metodo GET.
I metadati devono contenere il riferimento al file salvato.
Per ogni intervallo di tempo riconosciuto il nodo genera un messaggio POST_TELEMETRY_REQUEST con i valori di misura.

Catena di elaborazione

File Type Switch [OSF]
  -> Aggregate OSF File [Success]
  -> Save Timeseries

Aggregate JSONL File

Categoria: Azione
Uscite: Success, Failure

Il nodo carica un file JSONL da un BLOB_STORE_REQUEST e lo elabora.

Ingresso e output

Ingresso: BLOB_STORE_REQUEST con metodo GET.
Il file deve contenere JSONL valido.
Ogni riga genera un messaggio POST_TELEMETRY_REQUEST tramite Success.

Catena di elaborazione

File Type Switch [JSONL]
  -> Aggregate JSONL File [Success]
  -> Save Timeseries

Process Raw Data File

Categoria: Azione
Uscite: Download, Upload, Delete, Other

Il nodo classifica i messaggi BLOB_STORE_REQUEST in base all'operazione sul file e li inoltra all'uscita appropriata.

Configurazione

Label	Obbligatorio	Descrizione
Selected Scopes	Sì	Scope degli attributi che devono essere elaborati.
Selected Methods	Sì	Metodi HTTP o operazioni sui file che devono essere inoltrati.

Metodo	Uscita	Significato
`PUT`	`Upload`	Il file è stato caricato.
`GET`	`Download`	Il file deve essere scaricato.
`DELETE`	`Delete`	Il file è stato eliminato.
altri	`Other`	Operazione sconosciuta o non configurata.

Esempio

Upload può essere collegato a File Type Switch per distinguere ulteriormente i file OSF e JSONL.

Generate Report

Categoria: Azione
Uscite: Success, Failure

Il nodo genera un rapporto per l'origine del messaggio su una finestra temporale configurata.

Configurazione

Area	Campi
Tipo di rapporto	`reportType` con valori come `DEVICE_ACTIVITY`, `TELEMETRY`, `DEVICE_STATISTIC`, `ALARM`, `OSF_DATA`, `JASPER_TEMPLATE`.
Campi condizionali	`alarmSearchStatus`, `templateId`, `keys`, `sources`, a seconda del tipo di rapporto.
Finestra temporale	`useMetadataIntervalPatterns`, `startInterval`, `startIntervalTimeUnit`, `endInterval`, `endIntervalTimeUnit`, `startIntervalPattern`, `endIntervalPattern`.

Esempio

Per un'esportazione giornaliera della telemetria è possibile configurare reportType = TELEMETRY con una finestra temporale di un giorno e le chiavi di telemetria desiderate.

Device System

Categoria: Azione
Uscite: Success, Failure

Il nodo elabora dati provenienti da un Device System. In questo modo i dati di più dispositivi correlati vengono aggregati o correlati tra loro.

Configurazione

Il nodo non ha opzioni UI configurabili. La versione interna viene impostata dalla piattaforma.

Note

L'origine deve appartenere a un Device System configurato.
La struttura del Device System viene letta dal database.
Il nodo è rilevante solo se viene utilizzata la funzione Device System.

GPS Geofencing Events

Categoria: Azione
Uscite: Entered, Left, Inside, Outside

Il nodo tiene traccia dello stato del geofence per ogni dispositivo e genera eventi all'ingresso o all'uscita da un'area. A differenza del GPS Geofencing Filter, questo nodo è dotato di stato.

Configurazione

I campi delle coordinate e del geofence corrispondono a quelli del GPS Geofencing Filter. Inoltre vengono configurate durate minime:

Label	Descrizione
Minimal Inside Duration	Durata per cui un dispositivo deve trovarsi all'interno dell'area prima che venga generato `Entered`.
Inside Duration Unit	Unità di tempo per `minInsideDuration`.
Minimal Outside Duration	Durata all'esterno dell'area prima che venga generato `Left`.
Outside Duration Unit	Unità di tempo per `minOutsideDuration`.

Uscite

Uscita	Significato
`Entered`	Il dispositivo è rimasto all'interno dell'area abbastanza a lungo e prima si trovava all'esterno.
`Left`	Il dispositivo è rimasto all'esterno dell'area abbastanza a lungo e prima si trovava all'interno.
`Inside`	Il dispositivo è all'interno, ma la durata minima non è ancora stata raggiunta.
`Outside`	Il dispositivo è all'esterno, ma la durata minima non è ancora stata raggiunta.

RPC Call Request

Categoria: Azione
Uscite: Success, Failure, Timeout

Il nodo invia una chiamata RPC dal server a un dispositivo e attende la risposta.

Configurazione

Label	Obbligatorio	Descrizione
Timeout	Sì	Tempo di attesa in secondi, trascorso il quale il messaggio prosegue tramite `Timeout`.

Ingresso e output

Il corpo del messaggio deve contenere method e params. L'origine deve essere un dispositivo. In caso di Success la risposta del dispositivo sostituisce il corpo del messaggio.

Esempio

{
  "method": "emergencyShutdown",
  "params": { "reason": "HighTemperature" }
}

informazioni

Il dispositivo deve essere configurato in modo corrispondente per poter eseguire effettivamente le Remote Procedure Call specifiche.

RPC Call Reply

Categoria: Azione
Uscite: Success, Failure

Il nodo invia una risposta a una richiesta RPC proveniente dal dispositivo. Il contenuto della risposta viene costruito a partire dal corpo del messaggio corrente.

Configurazione

Label	Obbligatorio	Descrizione
Request ID Metadata Attribute	No	Campo dei metadati con l'ID della richiesta RPC.

Ingresso

Il messaggio deve essere di tipo TO_SERVER_RPC_REQUEST. serviceId, sessionId e requestId vengono di norma impostati dalla piattaforma.

Nodi di arricchimento

Originator Attributes

Categoria: Arricchimento
Uscite: Success, Failure

Il nodo legge dal database gli attributi e gli ultimi valori di telemetria dell'origine e li scrive nei metadati del messaggio.

Prefissi dei metadati

Origine	Prefisso nei metadati
Attributi client	`cs_`
Attributi shared	`shared_`
Attributi server	`ss_`
Ultima telemetria	nessun prefisso

Configurazione

Label	Obbligatorio	Descrizione
Client Attributes	No	Attributi client che vengono aggiunti come `cs_<name>`.
Shared Attributes	No	Attributi shared che vengono aggiunti come `shared_<name>`.
Server Attributes	No	Attributi server che vengono aggiunti come `ss_<name>`.
Latest Timeseries	No	Ultimi valori di telemetria che vengono aggiunti senza prefisso.
Tell Failure	Sì	Attivato: i valori mancanti portano a `Failure`. Disattivato: i valori mancanti vengono ignorati.

Deve essere inserita almeno una chiave di attributo o di telemetria.

Esempio

Se, ad es., si desidera definire manualmente un valore di offset per un canale di temperatura, si potrebbe creare un attributo server nella forma offset : 5. Tramite questo nodo è quindi possibile leggere questo valore e arricchire i metadati per continuare a lavorare con tale valore, selezionando il canale offset in Server Attributes. Nel nodo Script successivo è possibile accedere a questo valore tramite:

var offset = metadata.ss_offset;
var correctedTemperature = msg.temperature + offset;
return {
    msg: msg,
    metadata: metadata,
    msgType: msgType
};

Originator Telemetry

Categoria: Arricchimento
Uscite: Success, Failure

Il nodo legge i valori di telemetria storici dell'origine da una finestra temporale e li aggiunge ai metadati.

Configurazione

Area	Campi
Selezione dei dati	`latestTsKeyNames`, `fetchMode` con `FIRST`, `LAST` o `ALL`.
Campi aggiuntivi con `ALL`	`aggregation`, `orderBy`, `limit`.
Finestra temporale	`useMetadataIntervalPatterns`, `startInterval`, `startIntervalTimeUnit`, `endInterval`, `endIntervalTimeUnit`, `startIntervalPattern`, `endIntervalPattern`.

Note

Con FIRST o LAST viene aggiunto un singolo valore per chiave.
Con ALL i valori vengono memorizzati nei metadati come array JSON.

Esempio

Per un confronto con la media degli ultimi cinque minuti è possibile caricare temperature con fetchMode = ALL e successivamente valutarla in uno script Transform.

*Nodo Script

var temperatureArray = metadata.temperatureArray;
var total = 0;
var avgTemp = 0;

for (var i = 0; i < temperatureArray.length; i++) {
    total += temperatureArray[i];
}

if (temperatureArray.length > 0) {
    avgTemp = total / temperatureArray.length;
}

msg.avgTemp = avgTemp;

return {
    msg: msg,
    metadata: metadata,
    msgType: msgType
};

Originator Fields

Categoria: Arricchimento
Uscite: Success, Failure

Il nodo legge i campi anagrafici dell'origine, ad esempio nome o tipo, e li scrive nei metadati con nomi configurabili.

Configurazione

Label	Obbligatorio	Descrizione
Fields Mapping	Sì	Associazione tra i nomi dei campi dell'entità e le chiavi dei metadati.

Campo di origine	Significato
`name`	Nome visualizzato del dispositivo
`type`	Tipo di entità, `DEVICE`
`label`	Etichetta dell'entità
`additionalInfo`	Informazioni aggiuntive come JSON
`createdTime`	Data e ora di creazione come millisecondi Epoch

Esempio

Con name -> deviceName un successivo nodo To Email può utilizzare ${deviceName} nell'oggetto.

Tenant Details

Categoria: Arricchimento
Uscite: Success, Failure

Il nodo aggiunge i dati di contatto e di indirizzo del tenant al corpo del messaggio o ai metadati.

Configurazione

Label	Obbligatorio	Descrizione
Details	Sì	Campi del tenant selezionati. Deve essere selezionato almeno un campo.
Add Details to Metadata	Sì	Attivato: i valori vengono scritti nei metadati. Disattivato: i valori vengono scritti nel corpo del messaggio.

I campi disponibili sono TITLE, EMAIL, PHONE, COUNTRY, CITY, STATE, ZIP, ADDRESS, ADDRESS2 e ADDITIONAL_INFO.

Nodi di trasformazione

Script (Transform)

Categoria: Trasformazione
Uscite: Success, Failure

Il nodo modifica il corpo del messaggio, i metadati e/o il tipo di messaggio tramite JavaScript. Il risultato dello script viene inoltrato ai nodi successivi.

Configurazione

Label	Obbligatorio	Descrizione
Transform Function	Sì	Funzione JavaScript `Transform(msg, metadata, msgType)`.

Valore restituito

Lo script deve restituire un oggetto con msg, metadata e msgType.

Esempio

var newMsg = {};
newMsg.temperatureF = msg.temperature * 9 / 5 + 32;
newMsg.humidity = msg.humidity;

return {
    msg: newMsg,
    metadata: metadata,
    msgType: msgType
};

To Email

Categoria: Trasformazione
Uscite: Success, Failure

Il nodo crea un oggetto e-mail a partire dal messaggio corrente e dai relativi metadati.

Configurazione

Label	Obbligatorio	Descrizione
From	Sì	Indirizzo del mittente.
To	Sì	Indirizzo del destinatario oppure più destinatari separati da virgola.
CC	No	Destinatari in CC.
BCC	No	Destinatari in BCC.
Subject	Sì	Oggetto.
Body	Sì	Contenuto dell'e-mail.

Tutti i campi supportano segnaposto nel formato ${metadataKey}.

informazioni

Il nodo to Email genera solo l'e-mail. L'e-mail viene inviata con il nodo Send Email, che gestisce la comunicazione con il server SMTP.

Catena di elaborazione

Nodi esterni

REST API Call

Categoria: Esterno
Uscite: Success, Failure

Il nodo invia una richiesta HTTP a un'interfaccia REST esterna. Il corpo del messaggio corrente viene utilizzato come payload della richiesta.

Configurazione

Label	Obbligatorio	Descrizione
Endpoint URL Pattern	Sì	URL di destinazione. Supporta segnaposto `${metadata}`.
Request Method	Sì	Metodo HTTP: `GET`, `POST`, `PUT`, `DELETE`.
Use Simple Client HTTP Factory	No	Utilizza un semplice client HTTP, ad es. per risposte di grandi dimensioni.
Headers	No	Header HTTP come elenco chiave-valore.

Output

In caso di successo status, statusCode, statusReason e headers vengono scritti nei metadati. Il response body diventa il nuovo corpo del messaggio.

MQTT

Categoria: Esterno
Uscite: Success, Failure

Il nodo pubblica il corpo del messaggio corrente su un broker MQTT esterno. Il topic può essere costruito dinamicamente tramite i metadati.

Configurazione

Label	Obbligatorio	Descrizione
Topic Pattern	Sì	Topic MQTT con eventuali segnaposto `${metadata}`.
Host	Sì	Nome host o indirizzo IP del broker.
Port	Sì	Porta del broker, ad es. `1883` o `8883`.
Connection Timeout	Sì	Timeout di connessione in secondi.
Client ID	No	ID client MQTT.
Clean Session	No	Controlla se i dati di sessione del broker vengono scartati.
Enable SSL	No	Attiva TLS/SSL.

Credenziali

Sono supportati anonymous, basic con nome utente/password e cert.PEM per mTLS con certificati PEM.

Kafka

Categoria: Esterno
Uscite: Success, Failure

Il nodo pubblica il corpo del messaggio corrente come record in un topic Kafka.

Configurazione

Label	Obbligatorio	Descrizione
Topic Pattern	Sì	Topic Kafka, eventualmente con segnaposto dei metadati.
Bootstrap Servers	Sì	Elenco di broker separati da virgola.
Auto Retry Times	No	Numero di nuovi tentativi di invio.
Batch Size	No	Dimensione del batch in byte.
Time to Buffer	No	Tempo di attesa per raccogliere i record in millisecondi.
Buffer Max Size	No	Buffer massimo del producer.
Acks	Sì	Comportamento di conferma del broker.
Serializer	Sì	Classi di serializzazione.
Other Properties	No	Ulteriori proprietà del producer Kafka.

Output

In caso di successo offset, partition e topic vengono scritti nei metadati.

RabbitMQ

Categoria: Esterno
Uscite: Success, Failure

Il nodo pubblica il corpo del messaggio su un exchange RabbitMQ. Exchange e routing key possono essere costruiti dai metadati.

Configurazione

Label	Obbligatorio	Descrizione
Exchange Name Pattern	No	Nome dell'exchange. Vuoto significa Default Exchange.
Routing Key Pattern	No	Routing key.
Message Properties	No	Proprietà del messaggio AMQP.
Host	Sì	Host RabbitMQ.
Port	Sì	Porta AMQP.
Virtual Host	No	Virtual host RabbitMQ.
Credenziali	No	Autenticazione.
Automatic Recovery	No	Riconnessione automatica.
Timeouts	No	Timeout di connessione e di handshake.
Client Properties	No	Ulteriori proprietà del client.

AWS SQS

Categoria: Esterno
Uscite: Success, Failure

Il nodo invia il corpo del messaggio corrente a una coda AWS SQS. Sono supportate code Standard e FIFO.

Configurazione

Label	Obbligatorio	Descrizione
Queue Type	Sì	Coda Standard o FIFO.
Queue URL Pattern	Sì	URL della coda SQS. Supporta segnaposto dei metadati.
Delay Seconds	No	Ritardo per le code Standard.
Message Attributes	No	Ulteriori attributi SQS.
Credenziali AWS	Sì	Credenziali IAM.
AWS Region	Sì	Regione AWS della coda.

Output

In caso di successo vengono aggiunti, tra l'altro, messageId, requestId, messageBodyMd5, messageAttributesMd5 e, per le code FIFO, sequenceNumber.

AWS SNS

Categoria: Esterno
Uscite: Success, Failure

Il nodo pubblica il corpo del messaggio corrente su un topic AWS SNS.

Configurazione

Label	Obbligatorio	Descrizione
Topic ARN Pattern	Sì	ARN del topic SNS. Supporta segnaposto dei metadati.
Credenziali AWS	Sì	Credenziali IAM.
AWS Region	Sì	Regione AWS del topic.

Output

In caso di successo messageId e requestId vengono scritti nei metadati.

GCP Pub/Sub

Categoria: Esterno
Uscite: Success, Failure

Il nodo pubblica il corpo del messaggio corrente in un topic Google Cloud Pub/Sub.

Configurazione

Label	Obbligatorio	Descrizione
GCP Project ID	Sì	ID del progetto Google Cloud.
Topic Name	Sì	Nome del topic Pub/Sub.
GCP Service Account Key	Sì	Upload di un file JSON con le credenziali del service account.
Message Attributes	No	Ulteriori attributi Pub/Sub.

Nota

Il service account richiede l'autorizzazione roles/pubsub.publisher per il topic di destinazione.

Output

In caso di successo messageId viene scritto nei metadati.

Send Email

Categoria: Esterno
Uscite: Success, Failure

Il nodo invia un oggetto e-mail tramite SMTP. L'oggetto e-mail deve essere stato generato in precedenza tramite il nodo To Email.

Configurazione

Label	Obbligatorio	Descrizione
Use General SMTP Settings	Sì	Attiva le impostazioni SMTP a livello di sistema.

Se le impostazioni SMTP a livello di sistema vengono disattivate, è possibile configurare smtpProtocol, smtpHost, smtpPort, username, password, timeout, enableTls, requireTls, checkServerIdentity e sslTrustHost.

Nota

Se il messaggio in ingresso non è un oggetto e-mail valido, prosegue tramite Failure.

Nodi scheduler

Create Scheduled Task

Categoria: Scheduler
Uscite: Success, Failure

Il nodo pianifica un'attività singola per un momento successivo. L'attività può generare un rapporto o attivare una RuleChain.

Configurazione

Label	Obbligatorio	Descrizione
Job Name	Sì	Nome univoco dell'attività pianificata.
Delay Before Start	Sì	Ritardo fino all'esecuzione.
Type	Sì	`REPORT` o `RULE_CHAIN`.
Rule Chain	Sì, con `RULE_CHAIN`	RuleChain da eseguire.
Campi Report	a seconda del tipo di rapporto	Configurazione per i rapporti pianificati.

Note

Un'attività con lo stesso jobName per la stessa entità viene sovrascritta.

Clear Scheduled Task

Categoria: Scheduler
Uscite: Success, Failure

Il nodo elimina un'attività pianificata in precedenza prima che venga eseguita.

Configurazione

Label	Obbligatorio	Descrizione
Job Name	Sì	Nome esatto dell'attività da eliminare.

Note

Il nome deve corrispondere al nome utilizzato in Create Scheduled Task.
L'associazione avviene per entità di origine.
Se non esiste alcuna attività corrispondente, il messaggio prosegue tramite Failure.

Nodi di eventi e allarmi

Complex Alarm

Categoria: Regola di evento
Uscite: Success, Created, Cleared

Il nodo genera o termina allarmi in base a una regola di evento per la telemetria in tempo reale. È adatto a schemi che non possono essere rappresentati con una semplice verifica di un singolo valore.

Configurazione

Label	Obbligatorio	Descrizione
Event Rule	Sì	Selezione di una regola di evento esistente.

Note

La regola di evento deve essere stata creata prima dell'utilizzo del nodo. Vedere Event Processing
Created significa che è stato aperto un nuovo allarme.
Cleared significa che un allarme esistente è stato terminato.
Success significa che non si è verificata alcuna modifica dello stato dell'allarme.

Complex Event Processing

Categoria: Regola di evento
Uscite: Success, Created, Cleared

Il nodo applica il Complex Event Processing ai dati di file OSF già caricati. È la variante basata su file di Complex Alarm.

Configurazione

Label	Obbligatorio	Descrizione
Event Rule	Sì	Selezione della regola di evento per la valutazione CEP.

Note

Il nodo viene posizionato dopo Aggregate OSF File.
La regola di evento deve essere stata creata in anticipo nella piattaforma. Vedere Event Processing

Enrich Alarm

Categoria: Regola di evento
Uscite: Success, Failure

Il nodo arricchisce un allarme esistente con informazioni aggiuntive provenienti da una regola di evento basata su Excel.

Configurazione

Label	Obbligatorio	Descrizione
Event Rule	Sì	Selezione di una regola di evento con il relativo file Excel per l'arricchimento.

Note

La regola di evento deve essere stata creata in anticipo nella piattaforma. Vedere Event Processing
La regola di evento deve avere un file Excel con le associazioni per tipi di allarme o condizioni.
Il nodo viene impiegato dopo Create Alarm o Complex Alarm.
I dettagli aggiunti vengono riscritti nel record dell'allarme.

RuleNodes​

Panoramica per categorie​

Nodi di filtro​

Nodi di azione​

Nodi di arricchimento​

Nodi di trasformazione​

Nodi esterni​

Nodi scheduler​

Nodi di eventi e allarmi​

Panoramica di dettaglio​

Nodi di filtro​

Message Type Filter​

Configurazione​

Esempio​

Message Type Switch​

Configurazione​

Esempio​

File Type Switch​

Configurazione​

Esempio​

File Names Filter​

Configurazione​

Note​

Esempio​

Device Filter​

Configurazione​

Uscite​

Esempio​

Script (Filter)​

Configurazione​

Contesto dello script​

Esempio​

Switch​

Configurazione​

Note​

Esempio​

Check Existence Fields​

Configurazione​

Esempio​

GPS Geofencing Filter​

Configurazione​

Nota​

Esempio​

Nodi di azione​

Save Timeseries​

Configurazione​

Ingresso​

Save Attributes​

Configurazione​

Ingresso​

Save Alarms​

Uscite​

Configurazione​

Ingresso​

Create Alarm​

Uscite​

Configurazione​

Metadati dopo l'elaborazione​

Esempio​

Clear Alarm​

Uscite​

Configurazione​

Metadati dopo l'elaborazione​

Esempio​

Alarm Counter​

Configurazione​

Esempio​

Log​

Configurazione​

Note​

Generator​

Configurazione​

Esempio​

Nota​

Message Count​

Configurazione​

Output​

Delay​

Configurazione​

Note​

RuleNodes

Panoramica per categorie

Nodi di filtro

Nodi di azione

Nodi di arricchimento

Nodi di trasformazione

Nodi esterni

Nodi scheduler

Nodi di eventi e allarmi

Panoramica di dettaglio

Nodi di filtro

Message Type Filter

Configurazione

Esempio

Message Type Switch

Configurazione

Esempio

File Type Switch

Configurazione

Esempio

File Names Filter

Configurazione

Note

Esempio

Device Filter

Configurazione

Uscite

Esempio

Script (Filter)

Configurazione

Contesto dello script

Esempio

Switch

Configurazione

Note

Esempio

Check Existence Fields

Configurazione

Esempio

GPS Geofencing Filter

Configurazione

Nota

Esempio

Nodi di azione

Save Timeseries

Configurazione

Ingresso

Save Attributes

Configurazione

Ingresso

Save Alarms

Uscite

Configurazione

Ingresso

Create Alarm

Uscite

Configurazione

Metadati dopo l'elaborazione

Esempio

Clear Alarm

Uscite

Configurazione

Metadati dopo l'elaborazione

Esempio

Alarm Counter

Configurazione

Esempio

Log

Configurazione

Note

Generator

Configurazione

Esempio

Nota

Message Count

Configurazione

Output

Delay

Configurazione

Note