Lo schema dati (LabelDataMapping)

1 Tre tipi di valore

2 Aprire l'editor

3 Generale

4 Input Context

5 Variabili

6 Campi

7 Transforms e Fallback

8 Esecuzione e campi obbligatori

9 Validazione

10 Salvare, importare, riaprire

11 I campi nel pannello Dati

1 Tre tipi di valore

Lo schema ha tre sezioni. Il punto fondamentale è chi produce il valore, quando viene
risolto e se si può usare sul layout:

Ogni nome si usa come token {nome} nelle query, nelle espressioni e nei testi.
Conseguenze pratiche:

• una variabile può usare solo input e altre variabili, mai i campi (si risolve prima);
• una variabile serve per i valori intermedi: un prefisso, il risultato di una query
  riusato da più campi. Non compare nel pannello Dati e non arriva al layout;
• tutto quello che deve finire stampato deve essere un input o un campo.

2 Aprire l'editor

Ci sono tre strade:

• menu Dati › Crea / modifica schema dati (LabelDataMapping);
• tab Dati › pulsante Modifica schema (compare quando uno schema è già caricato);
• Ctrl+K › Crea / modifica schema dati.

Il dialog si chiama Crea schema dati se non c'è ancora uno schema, Schema dati
altrimenti. A sinistra ci sono le sezioni, al centro l'editor, a destra l'Anteprima XML
che si aggiorna mentre scrivi, con lo stato di validazione in cima.

Se apri l'editor senza uno schema caricato, il tool prepara una bozza ricavata dal
layout corrente: i 6 parametri standard più un campo per ogni bind già presente. La bozza
diventa lo schema vero alla prima modifica. Il pulsante Nuovo in basso rigenera
questa bozza, quindi non crea uno schema vuoto.

3 Generale

Gli attributi della radice <LabelDataMapping>: customerName (es. ACME), layoutId
(diventa anche il nome del file scaricato) e version.

4 Input Context

Un parametro per riga. Le colonne, da sinistra:

• Aggiungi parametro aggiunge una riga, il cestino la elimina.
• I sei parametri standard (ResourceId, ItemCode, PhaseCode, OrderCode, UserId
  obbligatorio, CustomerName) sono sempre presenti e vengono reintegrati se importi uno
  schema che non li ha. Puoi comunque modificarli.
• Nell'esempio abbiamo aggiunto Lotto e dato un default a ItemCode, OrderCode e
  CustomerName, così l'anteprima mostra valori realistici.

5 Variabili

+ Variabile crea NuovaVariabile con Source statica. L'editor è lo stesso dei campi
(vedi sotto). Nell'esempio Stabilimento legge il codice impianto della risorsa:

SELECT PlantCode FROM Resources WHERE Id = {ResourceId}

con fallback BG01. Due campi la usano (matricola e reparto), ma non viene mai
stampata direttamente.

6 Campi

+ Campo crea NuovoCampo. Selezionando un campo nella lista a sinistra si apre il
dettaglio: name, type e la Source, scelta tra cinque tipi.

Sotto la query e l'espressione ci sono i chip dei token: un clic inserisce il token nel
punto del cursore. Sono disponibili gli input, le variabili, gli altri campi (solo per i
campi) e i token di sistema {now}, {utcnow}, {today}, {date}, {time},
{machinename}, {processid}, {guid}.

I token vengono inseriti nel testo della query. Per i valori stringa metti gli apici:
WHERE Code = '{ItemCode}'.

Il mode delle query SQL decide la forma del risultato:

7 Transforms e Fallback

Ogni campo o variabile può applicare trasformazioni in sequenza (+ Transform,
frecce per riordinare) e un fallback.

Fallback: con Attivo il motore emette un valore quando il risultato è nullo o vuoto,
cioè il Valore indicato (es. N/D) oppure, con Vuoto, una stringa vuota esplicita.
Nell'esempio descrizione passa per ToUpper e Truncate 40 e ha fallback N/D.

8 Esecuzione e campi obbligatori

• Parallelism e maxDegree: quanti campi il motore risolve in parallelo.
• GlobalTimeoutSeconds: tempo massimo dell'intera pipeline.
• ContinueOnFieldError: se un campo non obbligatorio va in errore, si continua.
• FieldCache e ttlSeconds: cache dei valori.
• MaxPages: limite di pagine per i parametri paginati (0 = nessun limite).
• RequiredFields: spunta i campi che devono risultare valorizzati, altrimenti la
  pipeline fallisce. Nell'esempio è obbligatoria descrizione.

9 Validazione

Il riquadro sopra l'anteprima XML è verde (Schema valido) o rosso con l'elenco dei
problemi. I controlli principali:

• nome duplicato tra Input, Variabili e Campi (nell'immagine: un campo chiamato Lotto);
• nome mancante;
• template vuoto, query SQL vuota, URL mancante, lookup senza Entry;
• una variabile che usa un campo (le variabili si risolvono prima);
• dipendenze cicliche tra variabili o tra campi;
• un RequiredField che non corrisponde a nessun campo.

L'editor non chiede conferma quando elimini un parametro, una variabile o un campo, e
non permette di riordinarli. Le modifiche allo schema non passano dall'Annulla del
layout: prima di interventi importanti scarica una copia con Scarica .xml, da
reimportare in caso di errore.

10 Salvare, importare, riaprire

Lo schema viene salvato con l'autosave del tool e resta caricato fra una sessione e
l'altra: per modificarlo basta Modifica schema, senza reimportare il file.

11 I campi nel pannello Dati

Ogni modifica allo schema aggiorna subito il tab Dati:

• gli input con un default mostrano quel valore (ItemCode → ART-00184), gli altri
  il segnaposto ({UserId});
• i campi mostrano sempre il segnaposto {descrizione}: il valore lo calcolerà il
  motore in stampa;
• con pag compare anche lo scalare pageItem;
• i campi tabella (mode="rows") compaiono come array vuoti, pronti per una Tabella;
• le variabili non compaiono.

Se nel frattempo importi un XML di record (radice diversa da <LabelDataMapping>),
quello diventa la sorgente: lo schema resta modificabile ma non cambia più i campi del
pannello finché non lo reimporti.