Data-Coupler/SALESFORCE_COMPOSITE_IMPLEMENTATION.md

Implementazione Salesforce Composite API nel Data Coupler

Panoramica

Questo documento descrive l'implementazione delle chiamate Composite API di Salesforce nel DataCoupler, che sostituiscono le chiamate REST singole con operazioni batch più efficienti.

Modifiche Implementate

1. SalesforceServiceClient.cs

Nuove Classi

• CompositeOperationResult: Risultato di un'operazione composite
• SalesforceCompositeRequest: Struttura della richiesta composite
• SalesforceCompositeSubRequest: Sotto-richiesta all'interno del batch
• SalesforceCompositeResponse: Risposta della chiamata composite
• SalesforceCompositeSubResponse: Risposta di ogni singola operazione

Nuovi Metodi

• BatchCreateEntitiesAsync(string entityName, List<Dictionary<string, object>> entityDataList):

  • Esegue creazioni multiple usando Composite API
  • Batching automatico: Suddivide automaticamente le operazioni in batch da max 25 (limite Salesforce)
  • Ritorna lista di risultati per ogni operazione

• BatchUpdateEntitiesAsync(string entityName, Dictionary<string, Dictionary<string, object>> updateData):

  • Esegue aggiornamenti multipli usando Composite API
  • Batching automatico: Gestisce automaticamente il limite di 25 operazioni per batch
  • Accetta dictionary con entityId come chiave e dati da aggiornare come valore

Metodi di Supporto per Batching

• ExecuteCreateBatchAsync(): Esegue un singolo batch di creazioni (max 25)
• ExecuteUpdateBatchAsync(): Esegue un singolo batch di aggiornamenti (max 25)

2. DataCoupler.razor.cs

Nuovo Metodo Principale

• StartDataTransferWithComposite(): Versione ottimizzata del trasferimento dati che:
  1. Recupera tutti i dati dalla sorgente
  2. Analizza le associazioni per determinare create vs update
  3. Suddivide i record in batch separati per create e update
  4. Esegue le chiamate composite in parallelo
  5. Processa i risultati e crea/aggiorna le associazioni

Metodi di Supporto

• CreateAssociationAsync(): Crea una nuova associazione per record creati
• UpdateAssociationVerificationAsync(): Aggiorna la data di verifica associazione
• HandleFailedUpdateAsync(): Gestisce associazioni non valide dopo update falliti
• ShowTransferResults(): Mostra i risultati del trasferimento

Modifiche al Metodo Originale

• StartDataTransfer(): Modificato per utilizzare automaticamente StartDataTransferWithComposite() quando il client è Salesforce

Vantaggi dell'Implementazione

1. Performance

• Riduzione chiamate API: Da N chiamate singole a 2 chiamate batch (una per create, una per update)
• Esecuzione parallela: Le operazioni di create e update vengono eseguite contemporaneamente
• Efficienza di rete: Riduce drasticamente il numero di round-trip HTTP

2. Affidabilità

• Gestione errori granulare: Ogni operazione nel batch può avere successo o fallire indipendentemente
• Rollback parziale: Le operazioni riuscite rimangono valide anche se altre falliscono
• Logging dettagliato: Tracciamento completo di ogni operazione

3. Scalabilità

• Supporto batch parallelo: Gestione automatica del limite di 25 operazioni con esecuzione parallela
• Gestione memoria efficiente: Elaborazione in stream dei risultati
• Compatibilità: Fallback automatico al metodo originale per client non-Salesforce

Flusso di Lavoro

1. Verifica Client Salesforce
   ↓
2. Recupera dati sorgente
   ↓
3. Trasforma record e analizza associazioni
   ↓
4. Suddivide in batch:
   - Record da creare (nuovi)
   - Record da aggiornare (con associazione esistente)
   ↓
5. Esecuzione parallela:
   - BatchCreateEntitiesAsync()
   - BatchUpdateEntitiesAsync()
   ↓
6. Processamento risultati:
   - Crea associazioni per nuovi record
   - Aggiorna timestamp associazioni esistenti
   - Gestisce errori e associazioni non valide
   ↓
7. Report finale con statistiche

Compatibilità

• Backward Compatible: Il sistema continua a funzionare con il metodo originale per client non-Salesforce
• Configurazione: Nessuna configurazione aggiuntiva richiesta
• Associazioni: Piena compatibilità con il sistema di associazioni esistente

Logging e Debug

Il sistema include logging dettagliato con prefisso "COMPOSITE:" per tracciare:

• Analisi delle associazioni
• Suddivisione dei batch
• Risultati delle operazioni composite
• Creazione/aggiornamento associazioni
• Gestione errori

Limitazioni e Gestione Automatica

Limite Salesforce: 25 Operazioni per Composite Request

Salesforce limita le Composite API a massimo 25 operazioni per singola richiesta. La nostra implementazione gestisce questo limite automaticamente:

• Batching Automatico: Le operazioni vengono suddivise automaticamente in chunk da max 25
• Esecuzione Parallela: I batch vengono eseguiti simultaneamente per massimizzare le performance
• Aggregazione Risultati: I risultati di tutti i batch vengono combinati in un unico risultato
• Fallback Trasparente: Se il numero di operazioni è <= 25, viene eseguita una singola richiesta

Altre Limitazioni

1. Solo Salesforce: Le ottimizzazioni composite funzionano solo con Salesforce
2. Dipendenze: Richiede le nuove classi composite nel SalesforceServiceClient
3. Gestione Errori: Errori a livello di batch vengono propagati immediatamente

Testing

Per testare l'implementazione:

1. Configurare una connessione Salesforce
2. Preparare dati sorgente con mix di record nuovi e esistenti (>25 per testare il batching)
3. Osservare i log per confermare l'uso delle chiamate composite con batching automatico
4. Verificare che le associazioni vengano create/aggiornate correttamente
5. Testare con grandi dataset per verificare la gestione automatica dei batch

Considerazioni Future

1. Throttling Automatico: Implementare rate limiting intelligente per evitare limiti API
2. Retry Logic con Exponential Backoff: Aggiungere retry automatico per singoli batch falliti
3. Metrics e Performance: Raccogliere metriche sulla performance delle operazioni parallele
4. Configurabilità: Permettere configurazione del livello di parallelismo
5. Altri Provider: Estendere il pattern ad altri provider REST che supportano batch operations