Http

Una Source di tipo HTTP in Flowlyze è progettata per leggere e acquisire dati da endpoint remoti accessibili via protocollo HTTP o HTTPS, tipicamente esposti da servizi web, API REST o microservizi.
I dati ricevuti vengono elaborati in formato JSON, che rappresenta il formato standard per l’interscambio strutturato di informazioni tra sistemi.

Le configurazioni avanzate disponibili nella Source HTTP permettono di gestire in modo flessibile ed efficiente diversi aspetti dell’integrazione.

Lettura incrementale (Delta Reading)

La sorgente HTTP può essere configurata per effettuare letture incrementali, ossia per acquisire solo i dati nuovi o modificati rispetto all’ultima esecuzione.
Questo meccanismo sfrutta il sistema di memoria interno di Flowlyze e consente di ottimizzare le prestazioni riducendo il volume dei dati trasferiti.

Parsing del Payload

Flowlyze consente di definire regole di parsing e trasformazione del payload JSON restituito dall'endpoint HTTP, utilizzando espressioni JSONPath per identificare campi specifici, estrarre porzioni di dati o strutturare il messaggio in modo coerente con il flusso di destinazione.

Le opzioni di parsing sono disponibili nelle impostazioni della Source:

Campo	Descrizione
Extract From Response Field	Espressione JSONPath (o più espressioni separate da virgola) che indica da quale campo della risposta estrarre i record. Se lasciato vuoto, Flowlyze applica le regole di parsing predefinite descritte di seguito.
Wrap as Single Object	Se abilitato, i record estratti vengono riuniti in un unico messaggio JSON anziché inviati come messaggi separati.
Wrap Under Target Field	Chiave personalizzata sotto cui annidare i dati quando Wrap as Single Object è attivo. Se vuoto, un array viene messo sotto la chiave data, mentre un singolo oggetto viene usato direttamente come radice del messaggio.

Comportamento predefinito (senza dataField)

Quando Extract From Response Field non è valorizzato, Flowlyze analizza l'intera risposta JSON:

• Se la risposta è un array JSON, ogni elemento dell'array diventa un messaggio distinto.
• Se la risposta è un oggetto JSON:
  • se contiene un campo data di tipo array, ogni elemento di data diventa un messaggio distinto;
  • altrimenti, l'intero oggetto viene trattato come un singolo messaggio.

Estrazione personalizzata con JSONPath (dataField)

Quando Extract From Response Field è valorizzato, Flowlyze usa JSONPath per individuare i dati nella risposta. È possibile indicare più espressioni separate da virgola per estrarre dati da più percorsi contemporaneamente.

Per ogni valore trovato:

• se è un array, ogni elemento viene aggiunto come messaggio;
• se è un oggetto, viene aggiunto come singolo messaggio;
• se è un valore primitivo (stringa, numero, booleano, null), viene avvolto in un oggetto { "value": <valore> }.

Esempio: se la risposta è:

{
  "meta": { "page": 1 },
  "result": {
    "items": [{ "id": 1 }, { "id": 2 }]
  }
}

con dataField = $.result.items vengono estratti due messaggi: { "id": 1 } e { "id": 2 }.

Unificazione in un singolo messaggio (isSingleObject)

Con Wrap as Single Object abilitato, tutti i record estratti vengono combinati in un solo messaggio prima di essere inviati al flusso:

• se Wrap Under Target Field è valorizzato (es. result), i dati estratti vengono annidati sotto quella chiave: un singolo record resta un oggetto, più record diventano un array;
• se Wrap Under Target Field è vuoto:
  • con più record, viene prodotto { "data": [ ... ] };
  • con un solo record, il messaggio coincide con l'oggetto estratto.

Esempio: estraendo tre record con Wrap as Single Object attivo e senza Wrap Under Target Field, il risultato è:

{
  "data": [{ "id": 1 }, { "id": 2 }, { "id": 3 }]
}

Con la stessa configurazione e Wrap Under Target Field = items:

{
  "items": [{ "id": 1 }, { "id": 2 }, { "id": 3 }]
}

Modalità di autenticazione supportate

OAuth2 (Bearer Token)

Cosa fa: ottiene un access token da un Authorization Server e lo invia all’API come Authorization: Bearer <token>.

Quando usarla: API enterprise e pubbliche moderne (OpenAPI), sicurezza elevata, scadenza/rotazione token, gestione di scope/permessi.

Configurazione tipica in Flowlyze

• Grant type: di solito Client Credentials per integrazioni server-to-server (opz. Authorization Code se c’è un utente interattivo).
• Token URL: endpoint OAuth2 (es. https://auth.example.com/oauth/token)
• Client ID / Client Secret
• Scope (opzionale)
• Header in uscita: Authorization: Bearer {{access_token}} (inserito automaticamente una volta ottenuto il token)

Custom JWT Bearer

Cosa fa: costruisce un JWT firmato (tipicamente RS256) con claims concordati e lo invia direttamente come Bearer oppure lo scambia con un access token su un endpoint custom.

Quando usarla: API proprietarie che richiedono un JWT firmato invece del classico token OAuth, o un flusso “JWT → access token” personalizzato.

Configurazione tipica in Flowlyze

• Algoritmo: RS256/ES256/HS256 (di norma RS256)

• Chiave privata / Key ID (kid)

• Claims: iss, sub, aud, iat, exp, eventuali custom-claims

• Emissione token:

  • Direct Bearer: invia il JWT come Authorization: Bearer <jwt>
  • Exchange: invia il JWT a un endpoint per ottenere un access token e poi lo usa come Bearer

Esempio header finale (direct bearer)

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Template Variable (opzionale)

Controlla dove viene utilizzato il token ottenuto:

• Non specificata (default): il token viene aggiunto automaticamente nell'header Authorization: Bearer <token>.
• Specificata: il token non viene inviato nell'header Authorization, ma sostituisce il placeholder {{nomeVariabile}} nei campi configurabili della richiesta HTTP (URL, headers, query string, body).

Nel campo Template Variable inserire solo il nome della variabile (es. templateVariableField); negli altri campi usare la stessa sintassi Handlebars, ad esempio {{templateVariableField}}.

Esempio (token nell'URL)

• URL: http://example/{{templateVariableField}}/test
• Template Variable: templateVariableField

Flowlyze sostituirà {{templateVariableField}} con il valore del token generato.

Custom Auth Token

Cosa fa: ottiene un token di accesso chiamando un endpoint custom (tipicamente via POST con body JSON) e lo utilizza per autenticare le richieste verso l'API di origine.

Quando usarla: API proprietarie con flussi di autenticazione personalizzati che restituiscono un token in un campo JSON della risposta, senza un flusso OAuth2 standard.

Configurazione tipica in Flowlyze

• Endpoint: URL del servizio di autenticazione (es. https://auth.example.com/token)
• JsonBody: corpo JSON inviato nella richiesta di autenticazione
• Headers: eventuali header aggiuntivi per la chiamata di autenticazione
• TokenJsonPathField: nome del campo JSON nella risposta che contiene il token (es. access_token)

Template Variable (opzionale)

Stesso comportamento descritto per Custom JWT Bearer: se non specificata, il token va nell'header Authorization; se specificata, sostituisce {{nomeVariabile}} nei campi della richiesta (URL, headers, query string, body).

Esempio (token nell'URL)

• URL: http://example/{{templateVariableField}}/test
• Template Variable: templateVariableField

Basic Auth

Cosa fa: invia username:password codificati Base64 nell’header Authorization.

Quando usarla: servizi legacy o interni dove l’API espone Basic Auth su HTTPS.

Configurazione tipica in Flowlyze

• Username
• Password
• Header in uscita (automatico):

Nota: usare sempre HTTPS perché altrimenti le credenziali esposte via basic auth sono in chiaro.

API Key

Cosa fa: invia una chiave statica come header o query string.

Quando usarla: servizi semplici o pubblici, dove non è richiesto OAuth.

Configurazione tipica in Flowlyze

• Valore della chiave
• Posizione: Header (es. x-api-key: <key>) oppure Query (es. ?apikey=<key>)

Esempio completo

https://api.example.com/data?filter=update_date>{{last_update}}

Il placeholder {last_update} è valorizzato da Flowlyze con l’ultimo valore incrementale memorizzato (es. massimo update_date visto).

Se l’oggetto di ritorno delle API è nella forma:

{
  "data": [{}, {}, {}]
}

e Extract From Response Field è lasciato vuoto, Flowlyze rileva automaticamente l'array data e invia ogni elemento come messaggio distinto.