1. Introduzione

IB Entity è una libreria framework per Business Central che consente di definire entità di integrazione per la serializzazione e deserializzazione di dati in formato JSON o XML. L’app permette di mappare tabelle, campi e relazioni di Business Central verso strutture dati esterne, applicando regole e funzioni di trasformazione. Le pagine dell’app supportano la configurazione, il test e l’import/export delle strutture di entità.

1.1 Destinatari

Il manuale è rivolto a consulenti applicativi, key user e sviluppatori funzionali che conoscono la struttura dati di Business Central (tabelle, campi, chiavi e relazioni).

1.3 Convenzioni e termini

Nel documento vengono utilizzati i seguenti termini:

2. Concetti di base

2.1 Area

Un’Area raggruppa le entità per dominio funzionale. I campi principali sono Code e Description. Entity Count è un contatore calcolato delle entità associate all’Area.

2.2 Entity

Un’Entità rappresenta un modello di integrazione legato a una tabella di Business Central. I campi principali sono Code, Area, Table No., Table Name/Caption e Serialization Type (JSON o XML).

Opzioni di comportamento (deserializzazione e gestione record):

Metadati XML (solo se Serialization Type = XML):

2.3 Entity Property

Una Property definisce una proprietà dell’entità: può essere un singolo campo della tabella oppure un record correlato (serializzato come oggetto o array). Le proprietà sono elaborate secondo l’ordine di Priority (tipicamente multipli di 100).

Campi principali:

Campi avanzati e controlli (se presenti): skipValidate, forceModify, RegularExpression, IsPartOfPrimaryKey, Namespace/isAttribute (solo XML).

2.4 Entity Relation

Le Relazioni definiscono i filtri tra una proprietà di tipo record correlato e la tabella collegata. Ogni relazione specifica tabella e campo correlati e la modalità con cui calcolare il filtro.

2.5 Parameter

I Parametri gestiscono coppie Nome/Valore per funzioni e operazioni di serializzazione/deserializzazione. Il campo Type può essere Input, Output o Protected; Classification aiuta a organizzare i parametri.

2.6 Transformation

Le regole di Transformation (Model Code, Transformation Type, From, To) sono usate dalla funzione TRANSFORMATION per convertire valori da un dominio all’altro (ad esempio codici esterni/interni).

2.7 Tipi di Source Type

Field: Mappa un singolo campo della tabella.

RecordAsArray: Serializza un set di record collegati come array.

RecordAsObject: Serializza un singolo record collegato come oggetto.

InjectValues: Serializza un record collegato e incorpora le sue proprietà nell’oggetto padre, usando Serialized Name come prefisso.

3. Pagine e funzioni

Le pagine dell’app IB Entity consentono di configurare le entità, gestire proprietà e relazioni e testare i payload. I nomi delle pagine possono variare leggermente in base alla localizzazione; in questo manuale sono riportate le denominazioni presenti nella bozza.

3.1 Area List

Elenco delle aree (Area) con Code, Description ed Entity Count.

Campi principali:

• Code
• Description
• Entity Count (calcolato)

Azioni:

Entity: apre la lista delle entità filtrata per l’area selezionata.

3.2 Entities (Entity List)

Elenco delle entità configurate. Visualizza Area, Code, Table No., Table Name e Serialization Type.

Campi principali:

• Area
• Code
• Table No.
• Table Name
• Serialization Type (JSON/XML)

Azioni:

• Create entity from table: seleziona una tabella BC, crea l’entità e aggiunge automaticamente le proprietà per tutti i campi della tabella.
• Export: esporta la struttura in Entities.json (entità, proprietà, relazioni e parametri).
• Import: importa una struttura da file JSON nel formato generato dall’Export.

3.3 Entity Card

Scheda di dettaglio dell’entità. Consente di impostare tabella, tipo di serializzazione e opzioni di comportamento, oltre a gestire le proprietà in sottopagina.

Campi principali:

• General: Code, Area, Table No., Table Name/Caption, Record Count.
• Serialization Type: JSON o XML.
• Enabled Actions: Enable Delete, Disable Insert, Disable Modify.
• Deserializzazione: Skip OnInsert Trigger, Skip OnModify Trigger, Delay until Priority.
• XML Group (solo XML): Element Name/Namespace, EntitySet Name/Namespace.

Azioni:

• Validate: verifica un payload di input e mostra il risultato.
• Serialize: serializza un record selezionato della tabella in JSON/XML.
• Simple Serialize (solo JSON): serializza il record ignorando le proprietà configurate.
• Get: recupera un record usando i campi PK configurati nelle proprietà (IsPartOfPrimaryKey).
• Deserialize: crea/modifica un record partendo da un payload di input.
• Add Fields as properties: aggiunge proprietà a partire da campi selezionati.

3.4 Entity Properties (ListPart)

Sottopagina della Entity Card che mostra l’elenco delle proprietà e permette di configurare mapping, funzioni, relazioni e parametri.

Campi principali:

• Priority
• Source Type
• Source No.
• Source Entity Code
• Serialized Name
• Function
• IsPartOfPrimaryKey
• skipValidate / forceModify / RegularExpression

Azioni:

• Relation: configura i filtri di relazione (solo per RecordAsArray/Object/InjectValues).
• Function Parameters: gestisce i parametri della funzione selezionata.

3.5 Entity Relations

Pagina per gestire i filtri tra la tabella principale e la tabella collegata per una proprietà di tipo record correlato.

Campi principali:

• Related Table No.
• Related Field No.
• Relation Type (CONST/FIELD/FILTER)
• Relation Value

3.6 Transformation List

Gestisce le regole di trasformazione usate dalla funzione TRANSFORMATION.

Campi principali:

• Model Code
• Transformation Type
• From
• To

3.7 Additional Info

Pagina di supporto usata in tre modalità: LIST (parametri Nome/Valore), INPUT (incolla payload JSON/XML), WEB (visualizza risultati formattati).

Campi principali:

• LIST: Name, Value, Type, Classification
• INPUT: testo libero
• WEB: output formattato

4. Procedure operative

Flusso consigliato di configurazione:

Creare un’Area per raggruppare le entità.

Dalla pagina 9WAYS Entities, usare Create entity from table oppure creare una nuova entità manualmente.

Impostare Table No. e Serialization Type (JSON/XML).

Aggiungere proprietà dai campi della tabella o creare proprietà manuali con Priority e Source Type.

Per RecordAsArray/Object/InjectValues: impostare Source No., Source Entity Code e definire le relazioni.

Se necessario, applicare una Function alla proprietà e compilare i parametri in Function Parameters.

Configurare eventuali regole in Transformation List.

Eseguire Validate, Serialize o Deserialize per testare il mapping.

4.1 Creare un’Area

1) Aprire Area List. 2) Creare un nuovo record e compilare Code e Description. 3) Salvare.

4.2 Creare un’Entità da tabella

1) Aprire 9WAYS Entities. 2) Selezionare Create entity from table. 3) Scegliere la tabella da mappare. 4) Verificare che l’entità sia stata creata e che le proprietà (Field) siano state generate per i campi della tabella.

Suggerimento: dopo la generazione automatica, rimuovere le proprietà non necessarie e rinominare Serialized Name in modo coerente con il contratto esterno (es. camelCase).

4.3 Aggiungere proprietà e configurare le priorità

Le proprietà vengono elaborate in ordine crescente di Priority. Usare valori a step (es. 100, 200, 300) per lasciare spazio a inserimenti futuri.

Per mappare un campo:

1. Impostare Source Type = Field.
2. Selezionare Source No. (campo).
3. Verificare Serialized Name e, se necessario, modificarlo.
4. Se il campo contribuisce alla chiave primaria, attivare IsPartOfPrimaryKey.
5. Per mappare un record correlato:
6. Impostare Source Type = RecordAsArray (collezione) o RecordAsObject (singolo) oppure InjectValues (incorporazione).
7. Impostare Source No. con la tabella correlata.
8. Impostare Source Entity Code con l’entità di dettaglio.
9. Aprire Relation e definire i filtri di collegamento (CONST/FIELD/FILTER).

4.4 Definire relazioni

Le relazioni determinano quali record della tabella correlata vengono inclusi/ricercati rispetto al record padre. Usare FIELD quando il valore del filtro proviene dal record padre (es. collegamento per chiave), CONST per valori fissi e FILTER per espressioni più complesse.

Esempio (concettuale): collegare righe documento a testata usando FIELD sul numero documento del record padre.

4.5 Usare funzioni e parametri

Una Function consente di trasformare il valore in output oppure di interpretare l’input in deserializzazione. Selezionare la funzione nella proprietà e compilare i parametri in Function Parameters.

Esempi d’uso tipici:

• FORMAT: formattare date e numeri secondo uno standard concordato.
• FIXED: impostare un valore costante nel payload.
• TRANSFORMATION: convertire un valore secondo una tabella di mapping (Transformation List).
• REGEX: validare un valore rispetto a un’espressione regolare.

4.6 Testare (Validate / Serialize / Get / Deserialize)

Le azioni di test si trovano nella Entity Card e consentono di verificare rapidamente la correttezza del mapping.

Esempio di payload JSON (indicativo):

Nota: per l’azione Get è necessario che le proprietà che compongono la chiave primaria della tabella siano marcate con IsPartOfPrimaryKey.

4.7 Import / Export (Entities.json)

L’Export genera un file Entities.json che include entità, proprietà, relazioni e parametri. L’Import permette di ricreare la configurazione in un altro ambiente (es. da DEV a TEST/PROD).

Buone pratiche:

Versionare i file di export in un repository o in una libreria documentale.

Eseguire l’import in un ambiente di test e validare con Serialize/Deserialize prima di usarlo in produzione.

In caso di differenze di ID o numerazioni tabella tra versioni, verificare i riferimenti alle tabelle e ai campi dopo l’import.

5. Funzioni disponibili

Le funzioni disponibili dipendono dal tipo di serializzazione (JSON o XML). Di seguito l’elenco riportato nella bozza con i parametri principali.

5.1 Funzioni per proprietà (JSON)

5.2 Funzioni per proprietà (XML)

6. Note operative e risoluzione problemi

6.1 Controlli importanti

Source Entity Code è obbligatorio per proprietà di tipo RecordAsArray, RecordAsObject e InjectValues.

IsPartOfPrimaryKey viene letto dalla tabella ed è usato dall’azione Get per trovare il record.

Delay until Priority permette di posticipare l’inserimento del record fino alla priorità indicata.

Skip OnInsert/OnModify evita l’esecuzione dei trigger durante la deserializzazione.

RegularExpression abilita una validazione aggiuntiva sul valore del campo.

6.2 Problemi comuni

6.3 Checklist prima del go-live

Eseguire Export della configurazione e conservarla come baseline/versione.

Eseguire test di Serialize e Deserialize su casi reali (record con campi obbligatori, record con record correlati).

Verificare le opzioni Skip OnInsert/OnModify e Delay until Priority in base alle logiche di business.

Validare le regole TRANSFORMATION e i casi limite (valori non mappati).