JSON to Table

Task type: json-to-table

Il Task "JSON to Table" consente di importare i dati da un file JSON con struttura tabellare e inserirli in una tabella di un database. La sua funzione è duplice: si connette a un database per scrivere fisicamente i dati e, allo stesso tempo, espone i dati importati come un Dataset per l'utilizzo da parte di Task successivi nel Workflow (come un Iterator). Questo Task lavora su un JSON in ingresso fornito da un Task precedente (es. "Importa Testo").

1. Connessione database

In questa scheda si configurano tutti i parametri per stabilire la connessione al database di destinazione.

Tabella target

È possibile definire l’origine delle credenziali per la connessione:

Manuale: consente l’inserimento manuale di tutti i dati della connessione e della tabella nei campi sottostanti.
Environment: consente di utilizzare un ambiente di connessione preconfigurato. Selezionandone uno, i campi di autenticazione vengono compilati automaticamente.

Tipologia Database

Definisce il tipo di database (DBMS) a cui connettersi. Le opzioni supportate includono:

PostgreSQL
SQL Server
MySQL
Oracle DB: consente di specificare la connessione tramite SID o SERVICE.

Connessione SSL

Indica se la connessione al database deve avvenire tramite un canale sicuro.

Autenticazione


Campo	Descrizione
Host	Indirizzo del server del database (es. localhost, 192.168.1.100).
Porta	Porta usata per la connessione (es. PostgreSQL: 5432, MySQL: 3306).
Nome DB	Nome del database a cui connettersi.
User	Nome utente per accedere al database.
Imposta Password	Apre una finestra per inserire la password in modo sicuro.

Gestione tabella

Definisce come il task deve interagire con la tabella fisica nel database.

Tabella target: determina l’azione da eseguire sulla tabella:

Crea tabella: crea sempre una nuova tabella. L’operazione fallisce se esiste già una tabella con lo stesso nome.
Crea tabella se non esiste: crea una nuova tabella solo se non esiste già una tabella con lo stesso nome.
Tabella esistente: inserisce i dati in una tabella già presente. Per impostazione predefinita, i nuovi dati vengono aggiunti a quelli già presenti (Append). Attivando la checkbox Truncate Insert, la tabella viene svuotata prima di inserire i nuovi dati.

Nome tabella target: nome della tabella da creare o in cui scrivere i dati (es. utenti, prodotti, log_eventi).

2. Struttura Tabellare

La scheda Struttura tabellare permette di definire i campi (colonne) della tabella e mappare ciascuna colonna con gli elementi del file JSON di origine.

Campi disponibili

Ogni riga rappresenta una colonna della tabella. Per ciascun campo è possibile configurare:

Campo	Descrizione
Tipo	Tipo di dato del campo. Valori disponibili: `NUMERICO`, `STRINGA`, `DATA`, `DATA E ORA`
Precisione	Per `NUMERICO`: numero massimo di cifre; per `STRINGA`: lunghezza massima
Alias	Nome effettivo della colonna nella tabella del database. Sarà questo il nome visibile nel DB.
Espressione JSONPath	Espressione JSONPath per estrarre il valore dal file JSON di origine (es. `$.persona.info.name`)

Gestione Table Structure

In basso a destra della Struttura tabellare sono presenti tre pulsanti:

Pulsante	Azione
Salva	Salva la struttura definita
Importa	Importa una struttura esistente
Esporta	Esporta la struttura definita

Questa funzionalità permette di salvare, esportare o riutilizzare le mappature, evitando la compilazione manuale dei campi e riducendo il rischio di errori.

Nota Tecnica

Visibilità: Le strutture salvate nel sistema sono visibili esclusivamente all'utente che le ha create.

Approfondimento: Per una descrizione dettagliata di tutte le opzioni e della logica di funzionamento, fare riferimento alla pagina Table Structure.

3. Esempio di configurazione

Per creare una tabella utenti con i seguenti campi:

Tipo	Alias	Espressione JSONPath
STRINGA	name	$.user.info.name
STRINGA	email	$.user.info.email
NUMERICO	age	$.user.info.age
STRINGA	city	$.address.city
DATA	registration_date	$.registration.date
DATA E ORA	registration_datetime	$.registration.datetime

Il risultato di questa configurazione sarà la creazione di una tabella nel database con le colonne name, email, age, city, registration_date e registration_datetime (Alias) popolate con i valori estratti dal JSON (Espressione JSONPath).

Alias con caratteri speciali o maiuscole

Se si vogliono usare lettere maiuscole, caratteri speciali o spazi nei nomi delle colonne, è necessario racchiudere l'Alias tra doppi apici (es. "Nome Utente").

Tipo	Alias	Espressione JSONPath
STRINGA	“Name”	$.name
STRINGA	“Surname”	$.surname

Risultato nel Database

4. Gestione di strutture JSON annidate

Il Task JSON to Table è in grado di gestire file JSON che contengono strutture annidate, come array o oggetti all’interno di altri oggetti. Tramite l’Espressione Path/Query, è possibile estrarre interi blocchi annidati o singoli valori, mappandoli su colonne della tabella. Il Task può serializzare un oggetto annidato in un’unica colonna di testo, preservando la struttura originale in formato JSON.

Esempio: Strutture complesse annidate

Il Task gestisce con la stessa facilità anche strutture molto più complesse. Consideriamo un JSON dove departments contiene un oggetto, che a sua volta contiene un array di altri oggetti.

[
 {
 "name": "Luca",
 "surname": "Rossi",
 "departments": {
 "department": [
 { "details": { "name": "Marketing", "location": "Milan" } },
 { "details": { "name": "Sales", "location": "Rome" } }
 ]
 }
 },
 {
 "name": "Maria",
 "surname": "Bianchi",
 "departments": {
 "department": [
 { "details": { "name": "HR", "location": "Florence" } }
 ]
 }
 }
]

Anche in questo caso, la configurazione nella "Struttura tabellare" rimane identica:


Tipo	Precisione	Alias	Espressione JSONPath
String	1000	name	$.name
String	1000	surname	$.surname
String	4000	departments	$.departments

Il Task prenderà l’intero oggetto associato alla chiave departments e lo serializzerà in una singola stringa JSON.

Risultato nel Database:


name	surname	departments
Luca	Rossi	`{"department":[{"details":{"name":"Marketing","location":"Milan"}},{"details":{"name":"Sales","location":"Rome"}}]}`
Maria	Bianchi	`{"department":[{"details":{"name":"HR","location":"Florence"}}]}`

Estrazione di sotto-elementi con JSONPath

Se invece si volesse estrarre singoli elementi annidati, come ad esempio i nomi dei dipartimenti, è possibile utilizzare un’Espressione JSONPath specifica. Ad esempio:

Tipo	Precisione	Alias	Espressione JSONPath
String	1000	name	$.name
String	1000	surname	$.surname
String	1000	department_names	$.departments.department[*].details.name

Con questa configurazione, il Task JSON to Table seleziona tutti i valori name presenti nell’array department e li inserisce nella colonna department_names del database, separandoli eventualmente con una virgola.

Risultato nel Database

name	surname	department_names
Luca	Rossi	Marketing, Sales
Maria	Bianchi	HR

Questo approccio consente di estrarre solo i dati necessari, senza serializzare l’intero blocco JSON, rendendo la tabella più facilmente interrogabile e utilizzabile in altri Task o report.

5. Parametri di Output

Una volta che il Task "JSON to Table" ha completato l'elaborazione, espone un ricco set di parametri di output. Questi parametri non solo forniscono informazioni sull'esito dell'operazione, ma mettono anche a disposizione i dati elaborati in vari formati per i Task successivi.

result: Fornisce lo stato complessivo dell'esecuzione del Task (es. "Success" o un messaggio di errore).
resultJson: Rappresenta il risultato dell’esecuzione del task in formato JSON, includendo informazioni generali, configurazioni e dettagli sull’esecuzione.
targetTable: Restituisce il nome della tabella del database in cui i dati sono stati inseriti.
rowCount: Indica il numero totale di righe che sono state inserite nella tabella di destinazione.
DataExportCsv: Restituisce l'intero set di dati elaborato, formattato come testo in formato CSV (Comma-Separated Values).
DataExportJson: Restituisce l'intero set di dati elaborato, formattato come una stringa JSON.
Dataset: Questo parametro rappresenta il nome della colonna della tabella (Per es: name). È il parametro più importante per collegare questo Task ad un Iterator. Per accedere ai valori di una specifica colonna durante un'iterazione, si utilizza la sintassi Dataset.NomeColonna.
DataColumn: Questo parametro permette di accedere all'intero contenuto di una colonna come un'unica entità (ad esempio, un array o una lista).
DataColumn.NomeColonna: Restituisce tutti i valori della colonna “NomeColonna”. Per es: “Luca, Maria, Giovanni, Elena”

6. Esempio parametro resultJson

{
 "id": 18676,
 "name": "JSON to Table",
 "description": "",
 "type": "json-to-table",
 "type_name": "JSON to Table",
 "type_description": "Trasforma un json in tabella",
 "config": {
 "db_host": "example",
 "db_name": "EXAMPLE;TrustServerCertificate=Yes",
 "db_port": "1433",
 "db_type": "sqlserver",
 "db_user": "user_test",
 "use_ssl": "Y",
 "tab_name": "test_json",
 "tab_target": "IF",
 "db_password": "Q1sp7Lvv4jjvuZqoVhzCYL7YvaTzrJaF8h1VeuGKDUI=",
 "output_links": [
 {
 "to": "[TASK 1401_18831_69]",
 "from": "[TASK 1401_18676_26]",
 "text": "Condizione 18",
 "color": "green",
 "points": [
 -430.7143439873165,
 -719.2420963708037,
 -420.7143439873165,
 -719.2420963708037,
 -323.54756337750354,
 -719.2420963708037,
 -323.54756337750354,
 -706.5559372725313,
 -226.38078276769056,
 -706.5559372725313,
 -216.38078276769056,
 -706.5559372725313
 ],
 "toPort": "left4",
 "fromPort": "port_1401_18676_1",
 "isTraversed": true
 }
 ],
 "tab_truncate": false,
 "tablestructure": [
 {
 "field_name": "task_name",
 "field_type": "string",
 "field_value": "$.task_name",
 "field_format": "",
 "field_nullable": "Y",
 "field_precision": "1000"
 },
 {
 "field_name": "generated_text",
 "field_type": "string",
 "field_value": "$.generated_text",
 "field_format": "",
 "field_nullable": "Y",
 "field_precision": "1000"
 }
 ],
 "connection_mode": "env",
 "env_connection_name": "SqlServer_SYBOT_TEST",
 "oracle_db_name_type": "0"
 },
 "run_info": {
 "run_id": 1457238,
 "start_datetime": "2026-03-19 17:12:37",
 "end_datetime": "2026-03-19 17:12:37",
 "start_epoch": 1773940357.714373,
 "end_epoch": 1773940357.955128,
 "duration": 0,
 "status": "Completed",
 "cmd_text": "",
 "run_result": "Success",
 "result_text": "3 righe inserite nella tabella test_json",
 "full_result_text": "3 righe inserite nella tabella test_json"
 },
 "output_parameters": {
 "rowCount": "3",
 "exitStatus": "0",
 "targetTable": "test_json",
 "DataExportCsv": "task_name;generated_text\n\"Generate Summary\";\n\"Translate Text\";\"[\"\"Testo tradotto di esempio...\"\",\"\"test\"\"]\"\n\"Check Grammar\";\"Correzioni suggerite...\"\n",
 "DataExportJson": "[{\"task_name\":\"Generate Summary\",\"generated_text\":\"\"},{\"task_name\":\"Translate Text\",\"generated_text\":\"[\\\"Testo tradotto di esempio...\\\",\\\"test\\\"]\"},{\"task_name\":\"Check Grammar\",\"generated_text\":\"Correzioni suggerite...\"}]",
 "Dataset.task_name": "task_name",
 "DataColumn.task_name": "Generate Summary,Translate Text,Check Grammar",
 "Dataset.generated_text": "generated_text",
 "DataColumn.generated_text": ",[\"Testo tradotto di esempio...\",\"test\"],Correzioni suggerite..."
 }
}

1. Connessione database

Tabella target​

Tipologia Database​

Connessione SSL​

Autenticazione​

Gestione tabella​

2. Struttura Tabellare

Campi disponibili​

Gestione Table Structure​

Nota Tecnica​

3. Esempio di configurazione

Alias con caratteri speciali o maiuscole​

Risultato nel Database​

4. Gestione di strutture JSON annidate

Esempio: Strutture complesse annidate​

Estrazione di sotto-elementi con JSONPath​

Risultato nel Database​

5. Parametri di Output

6. Esempio parametro resultJson

Tabella target

Tipologia Database

Connessione SSL

Autenticazione

Gestione tabella

Campi disponibili

Gestione Table Structure

Nota Tecnica

Alias con caratteri speciali o maiuscole

Risultato nel Database

Esempio: Strutture complesse annidate

Estrazione di sotto-elementi con JSONPath

Risultato nel Database