Data-Coupler/README.md

Data-Coupler

Panoramica

Data-Coupler è una soluzione integrata per la gestione di connessioni dati e credenziali, composta da tre progetti principali:

• CredentialManager: Libreria per la gestione sicura delle credenziali
• DataConnection: Libreria per connessioni a database e API REST
• Data_Coupler: Applicazione Blazor Server per l'interfaccia utente

🆕 Novità Recenti (Febbraio 2026)

• ✅ Salesforce Batch Describe via Composite API: I metadati degli SObject vengono ora recuperati in batch (25 per chiamata) invece di N chiamate singole, riducendo drasticamente il consumo di API durante la discovery
• ✅ Discovery REST Parallela: DiscoverEntitySummariesAsync e DiscoverEntitiesAsync vengono eseguite in parallelo; la lista entità diventa interattiva quasi subito, i dettagli arrivano in background
• ✅ Fix Scheduler External ID Relationships: Corretti due bug nello schedulatore — ExternalIdRelationshipsJson e DefaultValuesJson venivano azzerati al re-salvataggio del profilo; i campi sorgente usati nelle relazioni External ID non venivano esclusi dal mapping normale

🆕 Novità Recenti (Gennaio 2026)

• ✅ Schedulazione File CSV/Excel: Supporto completo per schedulare trasferimenti da file
• ✅ Validazione Percorsi: Validazione file prima del salvataggio profili
• ✅ Deletion Sync Configurabile: Controllo granulare sincronizzazione eliminazioni
• ✅ Doppia Modalità File: Caricamento browser (preview) + percorso manuale (schedulazione)

Architettura

CredentialManager

Libreria responsabile per:

• Gestione sicura delle credenziali (Database, REST API)
• Crittografia dei dati sensibili
• Persistenza su database SQLite
• Validazione delle credenziali

DataConnection

Libreria per connessioni dati che include:

• Supporto per database: SQL Server, MySQL, PostgreSQL, Oracle, SQLite, DB2, SAP HANA
• Gestione connessioni REST API
• Integrazione con CredentialManager per l'autenticazione
• Factory pattern per la gestione di diversi provider

Data_Coupler

Applicazione Blazor Server che fornisce:

• Interfaccia web per la gestione delle credenziali
• CRUD completo per credenziali database e REST API
• Test delle connessioni
• Validazione form integrata

Configurazione

1. Database delle Credenziali

L'applicazione utilizza SQLite per memorizzare le credenziali. Il database viene automaticamente creato in:

Data_Coupler/wwwroot/data/credentials.db

2. Registrazione Servizi

Nel Program.cs di Data_Coupler:

// Add CredentialManager services
builder.Services.AddDataConnectionCredentialManagement("Data Source=wwwroot/data/credentials.db");

Utilizzo

Gestione Credenziali via Web Interface

1. Avviare l'applicazione Data_Coupler
2. Navigare su /credentials
3. Utilizzare l'interfaccia per:
   • Aggiungere nuove credenziali (Database/REST API)
   • Modificare credenziali esistenti
   • Testare le connessioni
   • Eliminare credenziali

Utilizzo Programmatico

// Iniettare il servizio
@inject IDataConnectionCredentialService CredentialService

// Ottenere opzioni per connessione database
var dbOptions = await CredentialService.GetDbManagerOptionsAsync("MyDatabase");

// Ottenere opzioni per API REST
var apiOptions = await CredentialService.GetRestServiceOptionsAsync("MyApi");

// Gestire credenziali
var credential = new DatabaseCredential
{
    Name = "Test",
    DatabaseType = DatabaseType.SqlServer,
    Host = "localhost",
    Port = 1433,
    DatabaseName = "TestDB",
    Username = "user",
    Password = "password"
};

await CredentialService.SaveDatabaseCredentialAsync(credential);

Struttura dei Progetti

Data-Coupler/
├── CredentialManager/              # Gestione credenziali
│   ├── Data/                       # DbContext e configurazioni
│   ├── Models/                     # Modelli per credenziali
│   └── Services/                   # Servizi core
├── DataConnection/                 # Connessioni dati
│   ├── CredentialManagement/       # Integrazione con CredentialManager
│   │   ├── Interfaces/             # Interfacce servizi
│   │   ├── Models/                 # Extension methods e conversioni
│   │   └── Services/               # Implementazione servizi
│   ├── DB/                         # Gestione database
│   └── REST/                       # Gestione API REST
└── Data_Coupler/                   # Applicazione Blazor
    ├── Pages/                      # Pagine Blazor
    │   └── CredentialManagement.razor
    ├── Shared/                     # Componenti condivisi
    └── wwwroot/data/               # Database SQLite

Build e Deployment

Prerequisiti

• .NET 9.0 SDK
• Visual Studio 2022 o VS Code
• Docker (opzionale, per deployment containerizzato)

Build Locale

dotnet build Data_Coupler.sln

Esecuzione Locale

dotnet run --project Data_Coupler/Data_Coupler.csproj

L'applicazione sarà disponibile su:

• HTTP: http://localhost:7550

Formati File Supportati

CSV

• Separatori: , (virgola), ; (punto e virgola), \t (tab), | (pipe)
• Rilevamento automatico: Sì
• Gestione quote: Supporto completo per campi tra virgolette
• Escape caratteri: Supporto per "" (double quote escape)
• Dimensione massima: 50 MB (configurabile)
• Schedulazione: ✅ Supportato con percorso file manuale

Excel

• Formati: .xlsx (Office Open XML), .xls (Binary Format)
• Fogli multipli: Legge il primo foglio per default
• Header: Prima riga utilizzata come intestazione
• Dimensione massima: 50 MB (configurabile)
• Schedulazione: ✅ Supportato con percorso file manuale

Modalità Caricamento File

1. Caricamento Browser (Preview)

• Carica file tramite browser per configurare mapping
• Processato in memoria, non salvato sul server
• Ideale per setup iniziale profilo

2. Percorso Manuale (Schedulazione) ⭐

• Specifica percorso completo file sul server
• Obbligatorio per profili schedulati
• Sistema valida esistenza e leggibilità
• Esempi: C:\Data\products.csv, /data/customers.xlsx

🐳 Deployment Docker

Quick Start con Docker:

# Pull e run (immagine pubblica)
docker run -d -p 7550:7550 -v data-coupler-data:/var/lib/Data_Coupler ghcr.io/alessiodalsi/data-coupler:latest

# Con Docker Compose
docker-compose up -d

Build Locale:

# Linux
docker build -t data-coupler:local -f Dockerfile .

# Windows
docker build -t data-coupler:local-windows -f Dockerfile.windows .

# Script automatico (PowerShell)
.\build-docker.ps1 -Target all -Test

# Script automatico (Bash)
./build-docker.sh all

Immagini Disponibili:

• Linux/Multi-platform: ghcr.io/alessiodalsi/data-coupler:latest
• Windows: ghcr.io/alessiodalsi/data-coupler:latest-windows
• Development: ghcr.io/alessiodalsi/data-coupler:development-latest
• Dev: ghcr.io/alessiodalsi/data-coupler:dev-latest
• Staging: ghcr.io/alessiodalsi/data-coupler:staging-latest

Note: Il tag latest viene automaticamente aggiornato sia dal branch main che dal branch development per garantire che le ultime funzionalità siano sempre disponibili. Il tag development-latest è specifico per il branch development.

📚 Documentazione Docker Completa: Vedi DOCKER_DEPLOYMENT.md e GITHUB_ACTIONS_SETUP.md

🔄 CI/CD Pipeline

Il progetto supporta pipeline CI/CD automatiche su:

GitHub Actions (.github/workflows/docker-build.yml):

• Build automatica su push ai branch main, development, staging
• Pubblicazione su GitHub Container Registry (ghcr.io)
• Multi-platform manifest (Linux + Windows)

Gitea Actions (.gitea/workflows/docker-build.yml):

• Stessa configurazione di GitHub Actions
• Pubblicazione su Gitea Container Registry (gitea.home-nas-ds.org)
• Istanza Gitea self-hosted con registry abilitato
• Configurazione: .gitea/workflows/README.md

Immagini su Gitea (self-hosted):

# Pull da Gitea Container Registry
docker pull gitea.home-nas-ds.org/alessio/data-coupler:latest

# Versioni disponibili
docker pull gitea.home-nas-ds.org/alessio/data-coupler:development-latest
docker pull gitea.home-nas-ds.org/alessio/data-coupler:staging-latest

📚 Setup Gitea: Vedi .gitea/workflows/README.md

Caratteristiche di Sicurezza

• Crittografia: Le password vengono crittografate prima del salvataggio
• Validazione: Validazione completa dei dati in input
• Isolamento: Ogni progetto ha responsabilità specifiche
• Type Safety: Uso di tipi forti per evitare errori
• Validazione File: Verifica esistenza e leggibilità file prima del salvataggio
• Deletion Sync Sicuro:
  • Disabilitato di default per prevenire eliminazioni accidentali
  • Disponibile solo nelle schedulazioni con configurazione esplicita
  • Warning chiaro nell'interfaccia utente per operazioni critiche
• Percorsi File Validati: Controllo permessi e accessibilità per schedulazioni

Testing

L'applicazione include funzionalità di test per:

• Connessioni database
• Chiamate API REST
• Validazione credenziali

Il testing può essere eseguito direttamente dall'interfaccia web.

Log e Monitoring

I servizi utilizzano ILogger per tracciare:

• Operazioni CRUD sulle credenziali
• Test di connessione
• Errori e eccezioni

Contributi

Per contribuire al progetto:

1. Fork del repository
2. Creare un branch per la feature
3. Implementare i cambiamenti
4. Testare thoroughly
5. Creare una Pull Request

Licenza

[Specificare la licenza del progetto]