Importazione di documenti

Importazione di documenti

In aggiunta alle funzioni JASCII di importazione (ed esportazione), Jolly consente l'importazione specializzata di documenti da sorgenti dati esterne.
Le sorgenti dati utilizzabili sono le seguenti:

NB: per importare documenti è necessario che siano contemporaneamente attivate le seguenti impostazioni:

XML
La lettura dei dati XML può avvenire o attraverso una procedura personalizzata (tipicamente: interrogazione via DLL di una sorgente dati esterna), o attraverso un file o attraverso la clipboard.
I dati XML devono contenere almeno due tipi di oggetti: DOCUMENTI e ARTICOLI, e il secondo deve essere gerarchicamente dipendente dal primo. Tutti gli altri oggetti saranno trascurati.
Il formato di importazione XML viene letto da un file di configurazione (estensione predefinita: *.JXLM) contenente la mappatura dei campi XML sui campi da importare. La sintassi del file di configurazione è la seguente (i campi in grassetto sono obbligatorî):

DOCUMENTI ARTICOLI
  • BOLLE=nome dell'oggetto XML che contiene i dati dei documenti (anche se sono fatture, ordini, o documenti di altro genere)
  • DOC_EXTERNAL_KEY=campo
  • DATA_DOCUMENTO=campo
  • NUMERO_DOCUMENTO=campo
  • DATA_PROTOCOLLO=campo
  • NUMERO_PROTOCOLLO=campo
  • DATA_CONSEGNA=campo
  • CONTO=campo
  • SQLFIELD_CONTO=campo
  • DENOMINAZIONE=campo
  • EMAIL=campo
  • PAGAMENTO_CODICE=campo
  • PAGAMENTO_DESCRIZIONE=campo
  • LISTINO=campo
  • NETTO=campo
  • TOTALE=campo
  • NOTE=campo
  • BOLLE_ARTICOLI=nome dell'oggetto XML che contiene i dati degli articoli
  • ART_EXTERNAL_KEY=campo
  • CODICE=campo
  • SQLFIELD_CODICE=campo
  • DESCRIZIONE=campo
  • UM=campo
  • QTA=campo
  • DATA_CONSEGNA=campo
  • PREZZO_LISTINO=campo
  • SCONTO=campo
  • SCONTO_02=campo
  • SCONTO_03=campo
  • VOCE_IVA=campo

La doppia barra commenta il resto della riga su cui si trova (in qualunque posizione).
I campi numerici devono contenere numeri, e i numeri devono essere privi del separatore delle migliaia. Come separatore decimale è possibile utilizzare indifferentemente la virgola o il punto.
Le date devono essere formattate come dd/mm/yy oppure dd/mm/yyyy.

Gli oggetti DOC_EXTERNAL_KEY e ART_EXTERNAL_KEY contengono le chiavi univoche di identificazione, riferite alla sorgente dati esterna, rispettivamente del documento e dell'articolo.

I campi SQLFIELD_CONTO e SQLFIELD_CODICE consentono - ove necessario - di ricavare indirettamente il codice del conto e dell'articolo attraverso un codice alternativo usato nella sorgente dati esterna.
Il loro valore rappresenta il nome del campo delle tabelle pconti e archivio_articoli che contiene il valore rispettivamente indicato da CONTO e CODICE. Il valore reale di CONTO e di CODICE vengono perciò determinati come:

select PCO_str_codice FROM pconti WHERE [SQLFIELD_CONTO] = [CONTO]
select AA_str_codice FROM archivio_articoli WHERE [SQLFIELD_CODICE] = [CODICE]

Se i campi SQLFIELD_CONTO e SQLFIELD_CODICE non sono referenziati, il programma utilizza le primary keys delle tabelle pconti e archivio_articoli (PCO_str_codice e AA_str_codice).

I campi CONTO, PAGAMENTO_CODICE, LISTINO, CODICE, CODICE_IVA e in generale tutti i codici, se specificati, deve contenere un valore valido ed esistente.
Se in Jolly il codice non esiste viene eseguita una ricerca sul codice alternativo di importazione/exportazione (per i campi CONTO e CODICI i codici alternativi sono SQLFIELD_CONTO e SQLFIELD_CODICE). Se non esiste neanche il codice alternativo, l'importazione fallisce.
Fa eccezione il codice del tipo di pagamento: se il documento che si sta importando non richiede necessariamente la presenza di un codice di pagamento (ad esempio: gli ordini tipicamente non richiedono un codice, ma si accontentano di una indicazione descrittiva), il tipo pagamento - anche se non esistente in Jolly - sarà comunque accettato e considerato alla stregua di una mera descrizione.

Il campo causale è un tipo di documento di jolly (table tipi_BDOC), e se presente deve avere un valore valido. Se non presente, viene desunto dal contesto in cui avviene l'importazione. Se non è possibile desumerlo, l'importazione fallisce.

BARCELLA ELETTROFORNITURE

E' possibile importare in Jolly documenti trasmessi dal fornitore Barcella Elettroforniture nel suo formato proprietario.

FILES DI TESTO (colonne fisse e CSV)

E' possibile importare in JOLLY documenti a partire da files di testo, sia a colonne fisse che in formato CSV (separato da virgole o tabulatori), creando un file di formato come descritto più sotto. Un esempio dei files di sintassi nei due casi (CSV/colonne fisse) è fornito nella seguente tabella. 

CSV (Comma Separated Values)

Seguendo il modello ideale di un file Excel, i dati da importare devono essere organizzati come segue:

FILE DATI

  • la prima riga del file dati deve contenere i nomi delle COLONNE (come assegnate sotto)
  • i dati devono seguire, un record per riga
  • non sono ammesse righe vuote (al massimo l'ultima riga dopo tutti i dati)
  • le colonne devono essere separate da TABULATORI o da VIRGOLE
  • non sono ammesse righe prive di colonne (tutte le righe devono avere lo stesso numero di 'colonne', eventualmente vuote)
  • i campi numerici possono contenere il separatore decimale (vedi sotto) ma non possono contenere separatori delle migliaia
  • per caricare documenti con più articoli:
    • la prima riga deve contenere i dati del primo documento e del primo articolo
    • ogni ulteriore articolo dello stesso documento è contenuto in una riga successiva, nella quale sono compilati esclusivamente i campi articolo (i campi documento devono essere completamente vuoti)
    • ogni documento termina quando si indicano i dati per il documento successivo (o quando il file termina)

FILE DI FORMATO

  • Il file di formato serve per associare i campi JOLLY ai nomi di colonna del file importato
  • il file dati può contenere le colonne referenziate nel file di formato, ma non è obbligatorio che le contenga tutte
  • è possibile rendere obbligatoria la presenza di una colonna nel file dati premettendo un "!" al nome del campo; esempio: !ARTICOLO=artic
  • è possibile rendere obbligatoria la presenza DEI DATI in una colonna premettendo un @ al nome del campo; esempio: @ARTICOLO=artic
  • a prescindere dall'obbligatorietà della presenza di campi e dati, il programma esegue un controllo sull'esistenza di tutti i campi necessari ed impedisce la creazione di documenti privi di dati essenziali
  • CAMPI STATICI: è possibile assegnare valori STATICI ai campi; i valori statici devono essere compresi tra virgolette; esempio:
    CONTO="RHIAG"

OPZIONI

  • DELIMITATORE-CSV=TAB / VIRGOLA
  • SEPARATORE-DECIMALE=VIRGOLA / PUNTO
  • SOLO-COLONNE-REFERENZIATE
    se l'opzione è specificata, il file dati deve contenere solamente le colonne referenziate;
    per default il file dati può contenere anche altre colonne, che durante l'importazione vengono ignorate se non referenziate in questo file di formato
  • SENZA-INTESTAZIONE-COLONNE
    se l'opzione è specificata, il file dati NON contiene la riga di intestazione delle colonne;
    l'ordine delle colonne è esattamente quello descritto in questo file di formato
  • TIPO-DATA=DD/MM/YY
    valori ammessi: YYYYMMDD, YYYY-MM-DD, DD/YY/YY, DD/MM/YYYY
 COLONNE FISSE

I campi vengono identificati in base a colonne fisse.

Vi sono i seguenti tipi di campo:

  • campi stringa: C(start, len)
  • campi numerici: C(start, len, dec) dove DEC è il numero di cifre decimali; esempio "00012345", la notazione "c(xxx, 8, 2)" darebbe il valore 123,45

E' in generale possibile importare campi formati dall'unione di più intervalli di dati e/o dati statici. Ad esempio:
NOMECOLONNA=c(10,3)+c(20,3)+c(30,3)
NOMECOLONNA=c(10,3)+"+"+c(20,3)+"+"+c(30,3)
NOMECOLONNA=c(10,8)+"."+c(18,2)

OPZIONI

  • FIXED_LEN=123
    dimensione fissa di ogni riga del file dati
  • NUOVO-DOCUMENTO=c(xx,yy)="ABC"   le righe per le quali sia vera la condizione specificata indicano l'inizio di un nuovo documento
  • CONTIENE-ARTICOLO=c(xx,yy)="ABC"   le righe per le quali la condizione è verificata contengono i dati di un articolo
  • FILTER=c(24,1)="-"
    vengono considerate le sole righe del file dati che rispondono a questa condizione di 'filtro'
OPZIONI COMUNI AD ENTRAMBI I MODELLI DI IMPORTAZIONE
  • CODICE_SQL_FIELD=AA_extra_str_ecommerce
    campo SQL utilizzato per trattare la colonna  "ARTICOLO";
    il valore di ARTICOLO non viene ricercato sulla Primary key della table archivio_articoli (AA_STR_CODICE) ma sul campo specificato (CODICE_SQL_FIELD)
  • DISTANZA_MAX_DT_MOVIMENTAZIONE=45
    la data di movimentazione (DATAMOV) dovrebbe cadere nel periodo tra DISTANZA_MAX_DT_MOVIMENTAZIONE giorni fa ed OGGI;
    se il campo non viene specificato non viene eseguito alcun controllo
  • le seguenti colonne (opzionali) vengono trattate in modo speciale
    • FATTORE=c(x,y,z)|FATTORE="numero"     gli importi vengono MOLTIPLICATI per il numero specificato
    • DIVISORE=c(x,y,z)|DIVISORE="numero"   gli importi vengono DIVISI per il numero specificato
// vedere esempio in BDOC-text-import.txt

TIPO-IMPORTAZIONE=CSV                 // deve essere la prima istruzione valida

// DOCUMENTI ----------------------------
//TIPODOC=tipodoc          // tipo di documento
//COMMESSA=
!@DATADOC=data
//NUMERODOC=
//DATARIF=
//NUMERORIF=
!@CONTO=clifor
//VALUTA="EURO"
//LISTINO="RHIAG"
//!@MAGAZZINO_1=magazzino          // primo principale
//MAGAZZINO_2="XXXX"                   // secondo magazzino
//!@MAGAZZINO_DB1=magazzino      // primo magazzino componenti
//MAGAZZINO_DB2=                         // secondo magazzino componenti
//IVA="0021" // voce IVA (no codice)

// ARTICOLI -----------------------------
!@ARTICOLO=codice                        // codice articolo
!@QTA=qtà
!@DATAORDINE=dtord                      // data di ordine (consegna prevista per)
//DATAMOV=                                    // data della movimentazione di magazzino
//CODICE_CLIFOR=                          // codice articolo per il cliente/fornitore
//UM=
DESCRIZIONE=descrizione                // descrizione dell'articolo
PREZZO_UNITARIO=prz unit
//SCONTORIGA=c()
//IMPORTO_RIGA=importo
//RIFERIMENTO_CLIFOR=                 // riferimento del cliente/fornitore alla transazione

// OPZIONI ------------------------------------
DELIMITATORE-CSV=TAB       // valori ammessi: TAB, VIRGOLA
SEPARATORE-DECIMALE=VIRGOLA      // facoltativo: indica il carattere utilizzato come separatore decimale; valori ammessi: VIRGOLA, PUNTO; valore default: VIRGOLA
//SOLO-COLONNE-REFERENZIATE      // il file dati deve contenere solamente le colonne referenziate; per default il file dati può contenere anche altre colonne, che vengono ignorate se non referenziate in questo file di formato
//SENZA-INTESTAZIONE-COLONNE      // il file dati NON contiene la riga di intestazione delle colonne; l'ordine delle colonne è esattamente quello descritto in questo file di formato 
TIPO-DATA=DD/MM/YY // valori ammessi: YYYYMMDD, YYYY-MM-DD, DD/YY/YY, DD/MM/YYYY

  

TIPO-IMPORTAZIONE=COLONNE-FISSE

// DOCUMENTI ----------------------------
//NUOVO-DOCUMENTO=c(1,1)="T" // se la condizione è vera, viene creato un nuovo documento
//TIPODOC=c(10,6)
//COMMESSA=
!@DATADOC=c(18,8)           // formato YYYYMMDD
//NUMERODOC=
//DATARIF=
//NUMERORIF=
!@CONTO=c(30,12)
//VALUTA="EURO"
//LISTINO="RHIAG"
//!@MAGAZZINO_1=c(60,10)
//MAGAZZINO_2="XXXX"
//!@MAGAZZINO_DB1=
//MAGAZZINO_DB2=
//IVA="0021"                // voce IVA (no codice)

// ARTICOLI -----------------------------
//CONTIENE-ARTICOLO=c(1,1)="Q" // se la condizione è vera, la riga contiene un articolo
!@ARTICOLO=c(80,10)
!@QTA=c(90,10,2)          // campo numerico
!@DATAORDINE=c(110,8)
//CODICE_CLIFOR=
//UM=
DESCRIZIONE=c(150,30)
//DATAMOV=c(2,8)
PREZZO_UNITARIO=c(130,10,2)
//SCONTORIGA=c()
//NETTO_RIGA_UNITARIO=c()
//NETTO_RIGA_TOTALE=c()
//DESCRIZIONE=c(,)
//RIFERIMENTO_CLIFOR=c(10,3)

// OPZIONI GENERICHE ----------------------
//CODICE_SQL_FIELD=AA_extra_str_ecommerce // campo SQL utilizzato per trattare il campo "ARTICOLO"; il valore di ARTICOLO non viene ricercato sulla Primary key della table archivio_articoli AA_STR_CODICE ma sul campo specificato (CODICE_SQL_FIELD)
//DISTANZA_MAX_DT_MOVIMENTAZIONE=45 // la movimentazione dovrebbe cadere nel periodo tra DISTANZA_MAX_DT_MOVIMENTAZIONE giorni fa ed OGGI; se il campo non viene specificato non viene eseguito alcun controllo

// OPZIONI COLONNE FISSE ----------------
//FIXED_LEN=250 // dimensione fissa di ogni riga del file dati 
//FILTER=c(24,1)="-" // vengono considerate le sole righe del file dati che rispondono a questa condizione di 'filtro'

La condizione (facoltativa) NUOVO-DOCUMENTO=condizione fa iniziare un nuovo documento su ogni riga per la quale la condizione è soddisfatta. Il comportamento default è che viene generato un unico documento per ogni file.

La condizione (facoltativa) CONTIENE-ARTICOLO=condizione indica che la riga contiene (anche) un articolo. Il comportamento default è che ogni riga contiene un articolo.

Le righe che non iniziano un documento e non contengono un articolo vengono ignorate.

COLONNE PREZZI E SCONTO
I campi NETTO_RIGA_UNITARIO e NETTO_RIGA_TOTALE sono mutuamente esclusivi.
Se viene referenziato un solo campo tra PREZZO_UNITARIO e NETTO_RIGA, lo sconto viene considerato non esistente, e il campo non referenziato viene calcolato.
Se vengono referenziati due tra i seguenti campi: PREZZO_UNITARIO, SCONTO, NETTO_RIGA, il terzo viene calcolato in funzione dei primi due (e del campo QTA). Se vengono referenziati tutti e tre, in caso di non perfetta congruenza numerica il campo SCONTO viene calcolato per differenza tra il NETTO e il LISTINO.

FILES DI TESTO (MRS/RHIAG)
E' prevista l'importazione di documenti i cui dati sono registrati su files di testo formattati a colonne fisse.
Il file di testo deve contenere i dati degli articoli, mentre tutti i dati relativi al documento sono indicati nel file di formato dell'importazione oppure devono essere desunti dal contesto.
Ogni riga del file di testo rappresenta un articolo da inserire nel documento.
Il file di formato deve contenere una sezione per il DOCUMENTO ed una sezione per gli ARTICOLI.

SEZIONE DOCUMENTO SEZIONE ARTICOLI
[DOCUMENTO]
TIPODOC="ORD-CLI"   // tipo documento; se assente viene desunto dal contesto
CONTO="FIAT-SPA"
VALUTA="EURO"
LISTINO="FORNITORE"
MAGAZZINO_1="SEDE"          // magazzino principale
MAGAZZINO_2="LAVORO"      // magazzino secondario
//MAGAZZINO_DB1=             // primo magazzino d/base
//MAGAZZINO_DB2=             // secondo magazzino d/base
IVA="0021"                         // voce IVA		 [ARTICOLI]
=c(1,10)
QTA=c(11,7,2)
UM=c(23,2)
CODICE_CLIFOR=c(101,10)    // codice articolo secondo il cliente/fornitore
DESCRIZIONE=c(100,20)
PREZZO_UNITARIO=c(18,13,2)
IMPORTO_RIGA=c(100,10,2)
SCONTORIGA=c(31,5)   // nel formato sconto accettato da JOLLY 
DATAMOV=c(50,8)        // formato AAAAMMGG
RIFERIMENTO_CLIFOR=c(100,10)    // riferimento al documento originale

Ogni campo può essere assegnato STATICAMENTE oppure letto dal file di testo.
I campi della sezione documento sono tutti STATICI (non possono essere letti dal file di testo), mentre i campi della sezione articoli possono essere assegnati staticamente oppure essere assegnati in funzione di un range di colonne del file di testo.
I campi obbligatori sono indicati in grassetto. Certi campi (ad esempio il campo MAGAZZINO_1) possono essere resi obbligatori in funzione del tipo di documento da importare.
Su ogni riga, tutto ciò che segue la sequenza "//" è considerata commento ed ignorata.

Tutti i campi possono essere assegnati in base ad un range di colonne oppure possono essere assegnati staticamente ad un valore specificato.
Ove possibile i valori sono integrati con i valori caricati dagli archivi di Jolly (ad esempio dall'archivio articoli).

ASSEGNAZIONE DA FILE (range di colonne) ASSEGNAZIONE STATICA
  • CAMPO=c(start, len [,dec])

dove

START = colonna iniziale
LEN=lunghezza complessiva del campo
DEC=valore facoltativo per i soli campi numerici; indica il numero di decimali (le ultime DEC colonne del campo sono considerate come decimali)
  • CAMPO="valore"

CLAUSOLE SPECIALI
E' possibile utilizzare le seguenti clausole speciali.

CODICE_SQL_FIELD=SQL_field             Viene usato per indicare che il codice articolo non fa riferimento alla primary key della tabella archivio_articoli, ma ad un altro campo (tipicamente il codice usato dal cliente / fornitore). Il valore del campo CODICE viene quindi ricercato sul campo SQL_field anzichè sul campo AA_str_codice
FILTER=c(start,len)="valore"           *** vengono considerate le sole righe che rispettano la condizione specificata
FIXED_LEN=nnn       // lunghezza obbligatoria della stringa di dati
MIN_LEN=nnn       // lunghezza minima della stringa di dati
MAX_LEN=nnn       // lunghezza massima della stringa di dati
DISTANZA_MAX_DT_MOVIMENTAZIONE=nnn    // la data di movimentazione del documento importato non può risalire ad oltre DISTANZA_MAX_DT_MOVIMENTAZIONE giorni

Pagina base del manuale di JOLLY