Come decidere quali dati includere in un evento di integrazione

Progettare un evento di integrazione sembra una scelta tecnica, ma determina l'autonomia dei team, la resilienza operativa e la qualità delle informazioni ricevute da ogni processo. Quando un CRM, un ERP, un ecommerce e una piattaforma di assistenza si scambiano eventi, emerge una domanda ricorrente: il messaggio deve includere tutti i dati necessari oppure solo un riferimento per recuperarli dal sistema di origine?

Non esiste una risposta universale. Un evento troppo essenziale impone consultazioni concatenate e rende il sistema di origine una dipendenza costante. Uno eccessivamente ricco duplica informazioni, può propagare dati personali non necessari e rischia di contenere una versione già obsoleta. L'alternativa efficace consiste nel decidere attributo per attributo, in base all'uso reale del consumatore e alle condizioni operative.

Le tre alternative per trasportare il contesto

Un evento può fornire il contesto in tre modi. Ogni modello risolve problemi diversi e introduce costi che devono essere assunti esplicitamente.

Evento con dati completi

Il messaggio include le informazioni necessarie al consumatore per eseguire la propria azione. Per esempio, un evento di ordine confermato può contenere righe d'ordine, indirizzo di consegna, canale di vendita e un'istantanea degli importi confermati.

• È opportuno usarlo quando il consumatore deve agire subito, quando il valore inviato deve essere conservato come evidenza storica o quando la disponibilità del sistema di origine non è garantita.
• Riduce chiamate successive, latenza e accoppiamento in fase di esecuzione.
• Richiede di definire cosa rappresenta l'informazione: in genere un'istantanea al momento dell'evento, non lo stato corrente del record.
• Aumenta la dimensione del messaggio, la complessità del contratto e la superficie di esposizione dei dati.

Evento con identificatore e consultazione successiva

Il messaggio contiene un identificatore, il tipo di evento e metadati minimi; il consumatore consulta poi un'API o una replica autorizzata. È appropriato se serve il dato aggiornato e non una fotografia storica.

• È opportuno usarlo per attributi volatili, cataloghi estesi o informazioni necessarie solo in casi eccezionali.
• Evita di distribuire copie di dati che cambiano frequentemente.
• Introduce dipendenza dalla disponibilità, dai permessi, dai limiti di consumo e dalla latenza del sistema di origine.
• Può generare consultazioni a cascata: un servizio interroga l'ordine, poi il cliente, quindi il prodotto e infine l'inventario. Questa catena è spesso fragile e difficile da diagnosticare.

Modello ibrido

Nella maggior parte delle integrazioni mature, il risultato migliore è ibrido: l'evento trasporta un nucleo autosufficiente per eseguire il flusso e riferimenti per arricchirlo quando necessario. Un ordine può includere identificatore, data, stato confermato, importi, articoli e destinazione logistica, ma fornire soltanto l'identificatore del cliente per recuperare le preferenze di contatto attuali quando una comunicazione lo richiede.

La regola non è “inviare poco” né “inviare tutto”: inviate ciò che serve per completare in modo affidabile la decisione attivata e fornite riferimenti per i dati che devono essere aggiornati, sono onerosi o non sono autorizzati per tutti i destinatari.

Criteri per decidere ogni attributo

L'unità corretta di decisione non è l'evento intero, ma ogni singolo attributo. Lo stesso evento può contenere dati immutabili, volatili, sensibili e derivati, che richiedono trattamenti opposti.

• Immediatezza: se il consumatore deve agire prima di poter interrogare un'API, il dato deve viaggiare nell'evento. La logistica non dovrebbe attendere una consultazione aggiuntiva per conoscere l'indirizzo validato da usare nella spedizione.
• Attualità: se la decisione richiede l'ultimo valore disponibile, è preferibile un riferimento. Le preferenze di comunicazione o lo stato attuale di un account possono cambiare dopo l'ordine.
• Valore storico: se è utile ricostruire ciò che era noto quando si è verificato un fatto, includete un'istantanea datata. Il prezzo accettato e le imposte applicate non devono essere reinterpretati con il catalogo corrente.
• Volume e frequenza: immagini, descrizioni estese, documenti o strutture molto grandi raramente appartengono al messaggio principale. Inviate un riferimento stabile, una versione e, se opportuno, un riepilogo.
• Disponibilità: se un'interruzione del sistema di origine bloccherebbe un processo critico, l'evento deve fornire il minimo necessario per degradare in sicurezza.
• Permessi: non tutti i consumatori che conoscono un identificatore devono ricevere dati personali, finanziari o interni. L'evento non deve aggirare il modello di autorizzazione dei sistemi.
• Tracciabilità: ogni valore determinante deve indicare da quale versione o momento proviene. Un campo senza contesto temporale può indurre decisioni errate.

Classificate inoltre i dati. Quelli immutabili, come l'identificatore di un ordine o la data di creazione, sono candidati evidenti a viaggiare. Quelli volatili, come la disponibilità di inventario, richiedono in genere una consultazione o un evento specifico di aggiornamento. I dati sensibili devono essere minimizzati, limitati per pubblico e protetti secondo le politiche applicabili. Quelli derivati, come una segmentazione o un punteggio, devono indicare regola, versione o validità affinché non appaiano come fatti permanenti.

Matrice pratica e modelli di progettazione

Prima di aggiungere un campo al contratto, i team business, prodotto e tecnologia possono valutarlo con queste domande. Se prevalgono le risposte affermative alla prima parte, probabilmente va incluso; se prevalgono quelle della seconda, è meglio referenziarlo.

1. Il consumatore non può completare la propria azione senza questo valore?
2. Deve essere conservata la versione esatta valida al momento dell'evento?
3. Una consultazione successiva può fallire o arrivare troppo tardi?
4. È piccolo e stabile nel ciclo di vita del processo?
5. Cambia spesso o serve soltanto in casi particolari?
6. Contiene dati sensibili che il consumatore non necessita esplicitamente?
7. Esiste una fonte autorizzata e disponibile da consultare in seguito?
8. Il consumatore può tollerare una risposta differita, una cache o una revisione manuale?

Da questa valutazione derivano tre modelli utili:

• Istantanea tracciabile: trasportate il dato e aggiungete occurred_at, un identificatore dell'evento, la versione dello schema e, quando applicabile, la versione della risorsa. È adatta per importi, condizioni accettate e destinazione operativa.
• Riferimento arricchibile: inviate un identificatore stabile, il tipo di risorsa e, se disponibile, una versione. Il consumatore consulta solo quando serve e registra quale risposta ha usato.
• Dati minimi con cache controllata: includete una selezione minima e consentite l'arricchimento da una copia di lettura con una scadenza definita. È utile per cataloghi o profili non sensibili, nei quali è accettabile un lieve ritardo.

Un contratto semplice può esprimere chiaramente la differenza tra fatto e informazione da consultare:

{
  "event_id": "evt_123",
  "event_type": "order.confirmed",
  "occurred_at": "2025-03-08T10:30:00Z",
  "order": {
    "id": "ord_456",
    "total_confirmed": 125.00,
    "delivery_address_snapshot": { "country": "ES" }
  },
  "customer_ref": { "id": "cus_789" }
}

L'indirizzo incluso è un'istantanea operativa; l'identificatore del cliente permette di consultare attributi attuali con autorizzazione. Non si deve dedurre che tutti i campi del cliente fossero validi o approvati al momento dell'ordine.

Disponibilità, errori e degrado operativo

Scegliere la consultazione successiva impone di progettare cosa accadrà quando questa fallisce. Non basta implementare un tentativo automatico: un'indisponibilità persistente può generare duplicati, saturare l'API di origine e bloccare intere code.

Definite il comportamento di degrado prima di pubblicare l'evento. Per ogni consumatore, concordate se può elaborare dati minimi, ritentare in seguito, passare a una coda di eccezioni o richiedere un intervento manuale. L'assistenza clienti può aprire un caso con informazioni parziali; la logistica potrebbe invece dover trattenere la spedizione se manca un indirizzo verificabile.

• Usate identificatori di evento e idempotenza affinché un nuovo tentativo non esegua due volte la stessa azione.
• Separate gli errori temporanei da quelli permanenti, come un riferimento inesistente o permessi insufficienti.
• Evitate tentativi sincronizzati e illimitati che amplificano un incidente nel sistema di origine.
• Monitorate ritardo delle code, errori di arricchimento, età dell'ultimo dato consultato e percentuale di elaborazione degradata.
• Conservate un percorso di revisione per le decisioni bloccate, con motivo ed evento originale disponibili per l'audit.

Versionamento, sicurezza e governo del contratto

I contratti degli eventi evolvono. Aggiungere un campo opzionale è solitamente meno rischioso che modificare il significato di uno esistente, rendere obbligatorio un campo opzionale o rimuovere informazioni che un consumatore riteneva disponibili. La compatibilità non consiste solo nella possibilità di leggere il messaggio: richiede anche che ne conservi il significato di business.

Stabilite un responsabile per ogni campo e documentatene origine, classificazione, semantica, formato, validità e consumatori autorizzati. Includete una versione dello schema e trattate le modifiche semantiche rilevanti come nuove versioni o nuovi tipi di evento. Non riutilizzate un nome per esprimere altro: un campo chiamato status senza catalogo di valori e definizione temporale è una fonte frequente di interpretazioni incompatibili.

In materia di sicurezza, applicate la minimizzazione dei dati. Un evento distribuito tramite un'infrastruttura condivisa può raggiungere più consumatori del previsto. Non includete dati personali “per ogni evenienza”, segreti, credenziali o attributi privi di una finalità concreta. Se un processo necessita di informazioni sensibili, valutate un canale limitato o una consultazione autorizzata invece di propagarle in un evento generale.

Esempio: ordine per logistica, assistenza e comunicazioni

Immaginate che un ordine confermato attivi tre flussi. La logistica necessita di articoli, quantità, indirizzo di spedizione validato, metodo di consegna e data di conferma. Questi dati devono viaggiare come istantanea, perché consentono di preparare la spedizione anche se l'ecommerce non è disponibile.

L'assistenza clienti necessita dell'identificatore dell'ordine, del suo stato e del riferimento del cliente. Può consultare la cronologia aggiornata del cliente durante la gestione di un problema, purché disponga dei permessi. Le comunicazioni transazionali richiedono il tipo di evento e un riferimento autorizzato al destinatario, ma non devono ricevere l'intero ordine né il profilo completo del cliente.

Questa separazione riduce l'esposizione e impedisce che un unico evento diventi una replica accidentale del CRM o dell'ERP. Chiarisce inoltre le responsabilità: l'ecommerce emette il fatto confermato, la logistica usa l'istantanea per l'evasione e ciascun canale consulta soltanto il contesto attuale di propria pertinenza.

Checklist decisionale prima della pubblicazione

• L'evento descrive un fatto avvenuto o tenta di replicare lo stato completo di un altro sistema?
• Ogni campo ha un consumatore, una finalità e un responsabile identificati?
• È chiaro quali campi sono istantanee e quali devono essere consultati come stato corrente?
• I dati sensibili sono stati minimizzati e i permessi di accesso definiti?
• Il processo continua, viene differito o passa alla gestione manuale se l'arricchimento fallisce?
• Esistono identificatore dell'evento, data di accadimento, idempotenza e versione dello schema?
• I consumatori possono ignorare nuovi campi senza interrompersi?
• Esistono metriche e avvisi per rilevare consultazioni fallite, ritardi e messaggi non elaborati?

La decisione corretta trasforma l'evento in un contratto di business affidabile, non in un contenitore arbitrario di dati. Inviate contesto sufficiente affinché il fatto possa generare valore in modo autonomo; consultate ciò che deve essere aggiornato, è sensibile o non è indispensabile. In questo modo si riduce l'accoppiamento senza sacrificare tracciabilità né continuità operativa.