Database e gestionali: SQL Server, PostgreSQL, MySQL e tunnel VPN
L’agente interroga il database del gestionale in sola lettura, con una login dedicata, e impara la struttura grazie alla mappatura. Qui trovi gli script da consegnare all’IT.
Ultimo aggiornamento:
Sola lettura, sempre
Kaiross esegue solo query SELECT: controlla ogni query prima di eseguirla, usa i permessi della login (solo lettura) e applica timeout e limite di righe. I dati per grafici ed export vengono riletti dal database, senza passare dal modello.
SQL Server: login dedicata
Chiedi al DBA di creare una login usata solo da Kaiross. Script da eseguire come amministratore del server (sostituisci i segnaposti tra < >):
USE [master];
CREATE LOGIN [<login_kaiross>] WITH PASSWORD = N'<password>', CHECK_POLICY = ON, DEFAULT_DATABASE = [<database>];
GO
USE [<database>];
CREATE USER [<login_kaiross>] FOR LOGIN [<login_kaiross>];
GRANT SELECT ON SCHEMA::[dbo] TO [<login_kaiross>];
GRANT VIEW DEFINITION TO [<login_kaiross>];
GRANT VIEW DATABASE STATE TO [<login_kaiross>];
GO - Non aggiungere la login a
db_owner,db_datawritero a ruoli di server. VIEW DATABASE STATEè facoltativo: rende più precisi e veloci i conteggi delle righe.- Per escludere tabelle sensibili (es. dati del personale) usa
DENY:
DENY SELECT ON OBJECT::[dbo].[<table>] TO [<login_kaiross>]; La password si inserisce solo nel connettore di Kaiross, che la salva nel Vault: non scriverla in email o ticket.
PostgreSQL: ruolo dedicato
CREATE ROLE kaiross LOGIN PASSWORD '<password>';
GRANT pg_read_all_data TO kaiross; Oppure concedi la lettura solo alle tabelle utili:
GRANT USAGE ON SCHEMA public TO kaiross;
GRANT SELECT ON public.<table> TO kaiross; Kaiross apre la sessione in modalità READ ONLY con statement_timeout e limite di righe.
MySQL e MariaDB: utente dedicato
Chiedi al DBA un utente usato solo da Kaiross, con il solo privilegio SELECT:
CREATE USER 'kaiross'@'%' IDENTIFIED BY '<password>';
GRANT SELECT ON <database>.* TO 'kaiross'@'%'; Oppure concedi la lettura solo alle tabelle utili:
GRANT SELECT ON <database>.<table> TO 'kaiross'@'%'; Kaiross apre sessione e query in sola lettura (READ ONLY), con un tempo massimo imposto dal server e un limite di righe. Funziona con MySQL 5.7+ e MariaDB 10.3+.
In SSL lascia Richiesto o scegli Richiesto + verifica certificato: Disattivato (solo in VPN) solo dentro un tunnel.
Creare la connessione
- Apri Integrazioni → SQL Server (o PostgreSQL, MySQL / MariaDB) e premi Nuova connessione.
- Inserisci host, porta, database, utente e password. Se il server è nella rete aziendale, in Raggiungibile tramite scegli il tunnel VPN.
- Con il certificato generato da SQL Server (autofirmato) attiva Accetta certificato self-signed.
- Premi Prova connessione e salva. Poi collega la connessione all’agente dalla scheda MCP e database.
Dettagli dei campi e degli strumenti: SQL Server, PostgreSQL, MySQL / MariaDB.
Tunnel VPN WireGuard
Per raggiungere un server nella rete dell’azienda serve un server WireGuard lato azienda (router o firewall con WireGuard, oppure una piccola VM) raggiungibile su una porta UDP.
- In Kaiross apri Impostazioni → Rete / VPN e premi Nuovo tunnel.
- In Modalità scegli Incolla configurazione (il file
.confpreparato dall’IT) oppure Genera chiavi: indichi Indirizzo assegnato a Kaiross, Endpoint del server, Chiave pubblica del server, Reti raggiungibili e, se serve, il DNS interno. - Premi Salva e verifica. Con Genera chiavi consegna all’IT la Chiave pubblica Kaiross da aggiungere al server WireGuard.
- Con Verifica raggiungibilità indica la porta del server (es. 1433) e premi Test: deve comparire Handshake riuscito.
[Interface]
PrivateKey = <Kaiross private key>
Address = 10.0.0.2/32
MTU = 1280
[Peer]
PublicKey = <server public key>
Endpoint = <vpn.example.ch>:51820
AllowedIPs = 10.0.0.5/32 AllowedIPslimitato all’indirizzo del server SQL: il tunnel serve solo al connettore.MTU = 1280nella sezione[Interface]: con valori più alti le query lunghe possono bloccarsi.- SQL Server su una porta TCP fissa: il servizio SQL Browser non passa dal tunnel, quindi indica la porta nel connettore.
«Mappa il database»
I gestionali hanno migliaia di tabelle. La mappatura (solo SQL Server) le legge una volta e scrive nella knowledge di un agente la struttura: tabelle, colonne, chiavi, relazioni, viste e query di esempio. Nella knowledge finisce solo la struttura: nessun valore delle tabelle viene salvato.
- Apri Integrazioni → SQL Server, scheda delle connessioni, riquadro Mappa del database e premi Mappa il database.
- Scegli l’Agente di destinazione (meglio un agente dedicato, es. «Analista gestionale»). Alla prima mappatura Campiona le tabelle (TOP 100 righe) è attivo, Tabelle da campionare al massimo è 300 (le più grandi; la struttura si legge per tutte) e Tempo massimo (minuti) è 20, fino a 25. Le volte dopo il modulo riprende le opzioni dell’ultima mappatura. Premi Avvia la mappatura.
- Segui l’avanzamento: puoi chiudere la pagina, la mappatura continua sul server. Poi attendi che tutti i file nella knowledge siano Pronti.
- Apri
00_panoramica.sqle controlla la riga Gestionale riconosciuto.
| File | Contenuto |
|---|---|
00_panoramica.sql | Riepilogo, gestionale riconosciuto, tabelle e colonne non standard, avvisi. |
10_tabelle_<area>.sql | Tabelle per area con colonne, tipi e chiavi. |
20_relazioni.sql | Relazioni dichiarate e dedotte, con la percentuale di affidabilità. |
30_viste.sql, 40_procedure_funzioni.sql | Viste, procedure e funzioni. |
50_cross_database.sql | Riferimenti ad altri database. |
60_query_esempio.sql, 65_query_standard.sql | Query di esempio; quelle standard solo con un gestionale riconosciuto. |
90_personalizzazioni.sql | Le regole della tua azienda: creato una volta, mai sovrascritto, prevale sul resto. |
Se la mappatura segnala Permessi mancanti (ad esempio su altri database), premi Copia lo script: contiene le GRANT esatte di sola lettura da far eseguire al DBA. Poi premi Riprova.
Profilo Mago4
Per Mago4 (Microarea, gruppo Zucchetti) Kaiross riconosce il gestionale, conosce le relazioni standard e aggiunge 65_query_standard.sql con le query più comuni. La corrispondenza attesa in 00_panoramica.sql è oltre il 90%.
Le voci «da verificare» di 65_query_standard.sql (tipo di documento della nota di credito, criterio di costo per il margine) vanno confermate con chi conosce il gestionale.
90_personalizzazioni.sql: le regole della tua azienda
Questo file insegna all’agente come la tua azienda usa il gestionale. Si compila in una sessione di circa 30 minuti con chi conosce i dati: Agenti → agente → Knowledge → 90_personalizzazioni.sql → Modifica. Sostituisci i TODO con le risposte e cancella le righe di esempio.
- Codici e significati: quali tipi di documento sono fattura, nota di credito, DDT; a cosa servono tabelle e colonne aggiuntive.
- Regole di business: cosa include il fatturato, quale costo usare per il margine, quali depositi contano nelle giacenze, quando un ordine è aperto o in ritardo.
- Relazioni delle tabelle personalizzate e le 3 estrazioni che fate più spesso.
Ripeti la mappatura dopo ogni aggiornamento del gestionale o almeno ogni 6 mesi: il file delle personalizzazioni resta com’è. Una sola mappatura alla volta per connessione.