Custom Adapter

Oltre ai connettori standard (source e destination), Flowlyze può essere esteso tramite App esterne chiamate Custom Adapter.
Non esistono vincoli sulla tecnologia utilizzata: l'unico requisito è il supporto al protocollo HTTP, seguendo le regole definite dal protocollo di comunicazione.

Nel contesto del protocollo, il ruolo di System Integrator è svolto da Flowlyze, che invia richieste HTTP al Custom Adapter ed elabora le risposte.

Architettura e flussi di integrazione

Modalità di esecuzione

Il Custom Adapter prevede due modalità operative:

Modalità sincrona

• Flowlyze invia i dati in batch (ad esempio 1000 righe per volta) via API.
• Il Custom Adapter elabora il batch entro la singola chiamata HTTP e restituisce un payload standard che, per ogni messaggio, riporta:
  • esito dell'elaborazione,
  • eventuali errori e metadati.
• La chiamata è soggetta a timeout e a limitazioni sulla durata massima (tipicamente 30 secondi).

Questa modalità è adatta a integrazioni veloci, idempotenti e con volumi limitati per singolo batch.

Modalità asincrona

• Flowlyze invia i dati in batch come nel caso sincrono, ma il Custom Adapter può processarli in modo differito (job in background, code interne, ecc.).
• Nella risposta iniziale il Custom Adapter segnala che l'elaborazione è asincrona.
• Flowlyze effettua polling sul sistema di destinazione (tramite l'azione progress) fino al completamento del job.

Questa modalità è ideale per elaborazioni più pesanti o lente, dove non è realistico concludere tutto entro il timeout di una singola richiesta HTTP.

Timeout

La modalità sincrona ha un timeout tipico di 30 secondi. Se l'elaborazione richiede più tempo, utilizza la modalità asincrona.

Protocollo di comunicazione sincrono

Ogni sistema esterno che voglia ricevere dati da Flowlyze tramite Custom Adapter deve esporre uno o più endpoint HTTP.
Tutti gli endpoint condividono la stessa struttura di base del body:

{
  "action": "execute",
  "payload": { ... }
}

• action: tipo di richiesta. I valori previsti sono:
  • "execute" → avvia l'elaborazione dei messaggi,
  • "progress" → (utilizzato nel flusso asincrono) richiede lo stato di avanzamento.
• payload: contenuto specifico della richiesta, che varia in base all'azione.

Endpoint di esecuzione

`POST <dominio>/system-integrator/handler1 (action "execute")`

Questo endpoint viene chiamato da Flowlyze per consegnare un batch di messaggi da elaborare.

Request

{
  "action": "execute",
  "payload": {
    "requestId": "<guid>",
    "messages": [
      {
        "msgId": "<guid>",
        "msg": {
          "...": "..."
        },
        "meta": {
          "...": "..."
        }
      }
    ],
    "meta": {
      "...": "..."
    }
  }
}

Significato dei campi:

• payload.requestId Identificatore univoco della richiesta (batch) inviato da Flowlyze.
• payload.messages Array dei messaggi da processare.
• payload.messages[i].msgId Identificatore univoco del singolo messaggio all'interno del batch.
• payload.messages[i].msg Payload effettivo del messaggio (record dati da elaborare).
• payload.messages[i].meta Metadati riferiti al singolo messaggio (contesto, configurazioni specifiche, ecc.).
• payload.meta `` Metadati condivisi da tutto il batch (es. stringhe di connessione, credenziali, endpoint downstream, parametri di configurazione).

Vincoli temporali e di esito

• Il sistema esterno deve processare la richiesta entro 30 secondi dall'invio.
• Obbligo HTTP 200:
  • Se il sistema risponde con uno status diverso da 200, l'intera richiesta viene considerata fallita, e tutti i messaggi del batch risultano non elaborati.
  • Le politiche di retry configurate in Flowlyze si occuperanno di reinviare il batch o i messaggi non processati, secondo configurazione.

Response sincrona

Se l'elaborazione viene gestita in modalità sincrona, il Custom Adapter risponde con:

{    
  "requestId": "<requestId>",
  "isAsync": false,
  "messages": [
    {
      "msgId": "<guid>",
      "status": "success",
      "date": "<date>",
      "meta": { }
    }
  ]
}

• requestId `` Deve coincidere con quello ricevuto nella richiesta.

• isAsync false indica che l'elaborazione è stata gestita tutta all'interno di questa chiamata.

• messages Array di esiti per ogni messaggio inviato.

• messages[i].msgId Deve corrispondere a un msgId precedentemente inviato da Flowlyze.

• messages[i].status Stato dell'elaborazione del singolo messaggio:

  • "success" → messaggio elaborato correttamente,
  • "error" → elaborazione fallita,
  • "in_progress" → usato solo in scenari asincroni, quando l'elaborazione non è ancora terminata.

• messages[i].date Data/ora di fine elaborazione in formato ISO8601.

• messages[i].meta Eventuali metadati restituiti dal sistema esterno (es. ID di risorsa creata, messaggi di errore, log sintetico).

In caso di errore di elaborazione, i messaggi con status = "error" verranno gestiti da Flowlyze secondo le policy di retry configurate (nuovi tentativi, dead-letter, logging, ecc.).

Protocollo di comunicazione asincrono

In modalità asincrona:

1. Flowlyze invia una richiesta action = "execute" identica al caso sincrono.

2. Il Custom Adapter:

   • risponde con HTTP 200,
   • imposta isAsync: true,
   • può marcare i messaggi come "in_progress" finché l'elaborazione non è conclusa.

3. Flowlyze effettua chiamate successive con action = "progress" per aggiornare lo stato dei messaggi associati a uno specifico requestId.

4. Il Custom Adapter restituisce via via lo stato aggiornato (success / error) per ogni msgId.

La struttura del body rimane allineata al contratto descritto in precedenza (stesso requestId, stessa lista messages con stato aggiornato).

Manifesto e discovery degli endpoint

Per permettere a Flowlyze di scoprire in modo dinamico quali handler sono esposti da un Custom Adapter, il sistema esterno deve pubblicare un manifesto in un endpoint ben noto.

Endpoint di discovery

**GET <dominio>/.well-known/system-integrator.json **

Risponde con un JSON della forma:

{
  "version": 1, 
  "handlers": {  
    "handler1": "<dominio>/system-integrator/handler1",  
    "handler2": "<dominio>/system-integrator/handler2"  
  }
}

• version Versione del manifesto, utilizzata per compatibilità futura.
• handlers Mappa [nome handler] → [endpoint handler] . Ogni handler rappresenta un punto di ingresso per l'elaborazione dei dati provenienti da un subscriber/flow diverso. In questo modo, un unico Custom Adapter può servire più flussi Flowlyze con logiche dedicate.
• handlers.<handler> URL dell'endpoint a cui Flowlyze invia le richieste execute progress relative a quello specifico handler.

Vincoli:

• L'endpoint di discovery DEVE essere sempre esposto esattamente su /.well-known/system-integrator.json.
• Gli URL degli altri endpoint (handler) sono liberi, a discrezione del sistema esterno; l'esempio con /system-integrator/handler1 e /system-integrator/handler2 rappresenta solo una convenzione consigliata.

Librerie

Vedi sezione Piattaforme\Custom per librerie e template di progetto