Documento tecnico di riferimento per l'integrazione tra la piattaforma Node AI DDT (cloud) e il sistema IBM i (AS/400). Sulla base del confronto tecnico del 15 aprile, il documento si concentra sull'approccio concordato: ODBC su tabella di staging + procedura RPG. Descrive architettura, tracciato record, requisiti tecnici e checklist di verifica.
Il sistema Node AI acquisisce DDT cartacei, estrae i dati strutturati tramite AI Vision e li presenta all'operatore per validazione umana. Solo i DDT in stato APPROVED sono eligible per essere inviati al gestionale IBM i. Questo documento copre esclusivamente il canale di trasporto tra i due sistemi.
[Scansione DDT] → Node AI / AI Vision → estrazione campi strutturati → Validazione umana (UI operatore, 2º livello controllo) → DDT in stato APPROVED → Invio a IBM i ←← oggetto del presente documento → Acknowledge / risposta / eventuale stato errore
Di seguito il modello dati di riferimento che Node AI inserirà nelle tabelle di staging. Nomenclatura e tipologie sono adattabili alle convenzioni del cliente. La struttura sotto è indicativa — lo schema definitivo delle tabelle Db2 va concordato con il team IBM i.
// Tracciato record di riferimento (struttura dati per staging table) { "external_id": "ddt_2026_04_16_a7f3b2", // UUID, chiave idempotency "source_document_id": "doc_92f1...", // riferimento audit Node AI "approved_at": "2026-04-16T10:23:11Z", "approved_by": "operator@cliente.it", "header": { "numero_ddt": "4521/2026", "data_ddt": "2026-04-12", "fornitore_codice": "FORN00128", "fornitore_ragione_sociale": "Edilizia Rossi S.r.l.", "fornitore_piva": "01234567890", "causale": "C01", "note": "" }, "righe": [ { "numero_riga": 1, "articolo_codice": "ART00451", "descrizione": "Cemento Portland 325", "quantita": 50, "unita_misura": "QL", "numero_ordine_acquisto": "OA-2026-0892", // per riga, per chiusura OdA lato IBM i "prezzo_unitario": null, "confidence": 0.98 } ], "attachments": [ { "type": "source_pdf", "url": "https://...", "sha256": "..." } ] }
Tutti i campi testuali sono UTF-8. Le date in ISO 8601. I codici fornitore/articolo sono placeholder: la strategia di mapping (lookup da anagrafica IBM i, import CSV periodico, o invio di codice grezzo con risoluzione lato IBM i) va definita in fase di dettaglio.
Il campo numero_ordine_acquisto è per riga, non per testata: ogni riga DDT può riferirsi a un ordine diverso. Questo consente la chiusura automatica degli OdA lato IBM i. Il campo è opzionale: non tutti i DDT cartacei riportano il numero d'ordine.
Node AI scrive i DDT validati su una o più tabelle di staging dedicate in Db2 for i via connessione ODBC. Una procedura RPG/CL runtime lato IBM i monitora la staging table in loop, consuma i record, valida, e li inserisce nelle tabelle definitive del gestionale con la propria logica di business. Pattern sicuro e comune negli ambienti IBM i.
Questo pattern è diverso dalla scrittura diretta nelle tabelle del gestionale (che non è raccomandata perché bypassa trigger, validazioni e logica RPG). Qui Node AI scrive solo sulla staging table; la procedura RPG del team IBM i fa il resto con pieno controllo.
INSERT over DRDA / DDM via ODBC · connessione TCP diretta a Db2 for iINSERT su tabelle NODEAI_DDT_H (testata) e NODEAI_DDT_R (righe) → colonna STATUS = 'NEW'
SELECT WHERE STATUS = 'NEW' → valida → scrive nelle tabelle definitive del gestionale → aggiorna STATUS = 'POSTED' o 'ERROR' con messaggio
IBM i Access Client Solutions (ACS) ODBC Driver · JTOpen / JT400 (JDBC, open source) · da Node.js: odbc npm package o bridge Java via JT400
NODEAI) con 2 tabelle:NODEAI_DDT_H — testata: external_id (PK), p_iva, ragione_sociale, data_ddt, numero_ddt, causale, note, status, error_msg, created_at, posted_atNODEAI_DDT_R — righe: external_id (FK), numero_riga, articolo_codice, descrizione, quantita, unita_misura, numero_ordine_acquisto, prezzo_unitario
446 (DRDA) · 8471 (IBM i Access) · variabili a seconda del driver e TLS on/offGRANT minimi: INSERT + SELECT + UPDATE solo su schema NODEAI. Nessun accesso alle tabelle del gestionale. Password complessa o Kerberos EIM.
*CHG / *ALL) con COMMIT/ROLLBACK: header + righe inserite come UOW atomica sulla staging table.
SBMJOB o subsystem dedicato) che: (1) legge record NEW, (2) valida contro anagrafiche, (3) incrocia OdA per chiusura automatica, (4) scrive nel gestionale, (5) aggiorna status. Gestione errori: STATUS = 'ERROR' + campo ERROR_MSG con dettaglio.
external_id come PRIMARY KEY sulla staging table. Un secondo INSERT con lo stesso id fallisce con constraint violation → Node AI tratta come successo già avvenuto.
SELECT status, error_msg FROM NODEAI_DDT_H WHERE external_id = ? per verificare l'esito del processing. Alternativa: callback HTTP dal consumer RPG verso Node AI.
La variante in cui Node AI scrive direttamente nelle tabelle finali del gestionale (senza staging table e senza consumer RPG) è sconsigliata. Bypassa la logica applicativa (trigger, validazioni, aggiornamento tabelle correlate) e può causare inconsistenza dati. Il pattern staging table + consumer RPG evita completamente questo rischio.
Elenco delle informazioni utili a restringere la scelta e preparare lo spec di integrazione di dettaglio. Idealmente raccolte prima o durante il meeting tecnico.
Requisiti trasversali dell'integrazione. Da concordare nella fase di spec di dettaglio.
Ogni DDT ha un external_id univoco generato da Node AI (UUID). IBM i deve usarlo come chiave di deduplicazione: un secondo invio con lo stesso id è un no-op (non crea duplicato, risponde con lo stato del precedente).
Node AI implementa retry con backoff esponenziale su errori transitori (5xx, timeout, errori di rete). Massimo 5 tentativi in 24 ore. Dopo il fallimento definitivo, il DDT torna in stato TRANSFER_ERROR lato Node AI per revisione manuale.
Testata DDT + righe sono un'unica unità transazionale. Nessun caso di testata salvata con righe mancanti. COMMIT/ROLLBACK sulla staging table garantiscono atomicità.
Node AI mantiene log completo di ogni tentativo di invio: payload, timestamp, risposta, esito, operatore che ha approvato. Ritenzione: 12 mesi (configurabile). Esportabile su richiesta cliente.
Metriche disponibili lato Node AI: throughput, latenza, tasso errori, conteggio retry, profondità coda. Alert proattivi su anomalie. Dashboard di stato accessibile al cliente.
Prima del go-live in produzione, tutta l'integrazione deve essere testata end-to-end su ambiente non-prod (LPAR o libreria dedicata lato IBM i, tenant dedicato lato Node AI). In assenza di ambiente non-prod IBM i, concordare finestra di test controllata in produzione con piano di rollback.