PROGRAMMA BBARIANNADISTR (BLACK BOX PER I DISTRIBUTORI)

Transcript

1 ARIANNA PROGRAMMA BBARIANNADISTR (BLACK BOX PER I DISTRIBUTORI) VERSIONE 1.03 GUIDA DI RIFERIMENTO Primo rilascio documento: aprile 2005 Ultima revisione documento: maggio 2006

2 ELENCO DELLE PRINCIPALI MODIFICHE Versione 1.01 Sono state apportate le seguenti modifiche: I file di testo possono contenere più documenti, ma solo dello stesso tipo, quindi in un file possono essere contenuti solo messaggi di tipo DESADV o di tipo ORDRSP. Nel caso in cui un documento contenga messaggi di tipo differente, il programma si interrompe restituendo il relativo codice d errore 216. Versione 1.03 Sono state introdotte le seguenti modifiche: Alla versione per Windows è stata affiancata anche una versione per Linux. Per la versione Linux il nome dell eseguibile è bbariannadistr, il funzionamento è lo stesso. Arianna 2 Versione 2.02

3 INDICE 1 Introduzione Sottoinsieme dei messaggi Arianna Funzionalità della BBAriannaDistr Formato dei messaggi contenuti nei file di testo Messaggio DESADV (Avviso di spedizione) Formato Note Esempio Messaggio ORDRSP (Risposta all'ordine) Formato Note Esempio Utilizzo della BBAriannaDistr Configurazione Esempio di configurazione Opzioni del programma Esecuzione Esempi di utilizzo Descrizione degli errori Archivio prodotti e partecipanti Arianna 3 Versione 2.02

4 1 INTRODUZIONE Arianna è un servizio dedicato al sistema editoriale, grazie al quale gli utenti (editori, distributori, promotori, grossisti e librai) sono in grado di dialogare tra loro attraverso un unico standard di comunicazione e scambiare informazioni di tipo commerciale. Arianna si basa sugli standard EDI (Electronic Data Interchange) nel settore librario. Con il termine EDI ci si riferisce in generale allo scambio di informazioni per via telematica tra partner commerciali all interno di un applicazione strutturata. Nel servizio Arianna, lo scambio di informazioni avviene tra librerie, distributori/editori e Informazioni Editoriali che svolge la funzione di clearing house, cioè di intermediatore tra le varie parti in gioco con il fine di risolvere problemi di compatibilità tra le stesse, gestire servizi addizionali e mantenere alcuni archivi centrali. Lo scambio di informazioni tra le parti avviene seguendo alcune regole fissate a priori: lo standard di riferimento per lo scambio di messaggi in ambito amministrativo e commerciale è l EDIFACT (EDI for Administration, Commerce and Transport): tale standard definisce le regole sintattiche per la composizione dei documenti EDI. I documenti elettronici EDI che vengono scambiati tra le parti prendono il nome di interchange che contengono un insieme di messaggi, a loro volta strutturati in segmenti: i segmenti contengono le unità elementari di informazione, o data element. La sintassi EDIFACT, formalizzata nel set di standard ISO 9375 Edifact application level syntax rules, definisce gli standard per strutturare gerarchicamente un interchange. Lo standard EANCOM è stato definito dall EAN come sottoinsieme dello standard EDIFACT, la cui generalità porterebbe a un eccessiva complessità per il campo di interesse più ristretto delle aziende associate all EAN; l EANCOM è completamente compatibile con la sintassi e i messaggi EDIFACT. Un ulteriore restringimento, in conformità con le esigenze del mondo del libro, è stato attuato dal PAN European Book Sector EDI Group e ha generato lo standard EDItEUR, come sottoinsieme dello standard EDI/EANCOM. Lo scambio di dati nel contesto del servizio Arianna prevede l utilizzo di un ristretto insieme dei messaggi, segmenti e data element previsti dallo standard EDItEUR. 1.1 SOTTOINSIEME DEI MESSAGGI ARIANNA Allo stato attuale Arianna utilizza un ristretto sottoinsieme dei messaggi definiti dallo standard EDItEUR. Ogni messaggio Arianna, inoltre, prevede l utilizzo solamente di una parte dei segmenti e segment group previsti per quel tipo di messaggio a livello di standard EDItEUR. I messaggi utilizzati in Arianna sono i seguenti: ORDERS: ordini dalle librerie verso l editore/distributore. SLSRPT: dati di vendita dalle librerie verso l editore/distributore. ORDRSP: conferma dell ordine dall editore/distributore verso le librerie. DESADV: avviso di spedizione della merce dall editore/distributore verso le librerie. PRICAT: aggiornamenti di catalogo dall editore/distributore verso le librerie. Arianna 4 Versione 2.02

5 1.2 FUNZIONALITÀ DELLA BBARIANNADISTR Al fine di consentire l accesso ai servizi Arianna senza l onere della complessa gestione dello standard EDIFACT, è stato realizzato da Informazioni Editoriali S.p.a. il software BBAriannaDistr di conversione dei dati dal formato testo, più semplice da gestire, al formato EDIFACT. I dati diretti al sistema Arianna, così come quelli ricevuti dal sistema Arianna, devono essere elaborati e trasformati dal software di conversione BBAriannaDistr: il software consente il dialogo tra il sistema Arianna e l eventuale utente, che deve essere in grado di produrre e interpretare un semplice formato testo per i dati Arianna. Utente Arianna Formato Semplificato Software di conversione Formato EDIFACT Servizio Arianna La complessità dell EDIFACT diventa quindi del tutto invisibile all utente Arianna, senza tuttavia porre limitazione ai servizi accessibili. Il software di conversione deve essere eseguito sui sistemi dell utente. L utente dovrà produrre i propri file in un particolare formato testo, tradurli con la BBAriannaDistr e inviare al sistema i file tradotti. Per i file provenienti dal sistema, l utente dovrà tradurli con la BBArianna e otterrà i file in formato testo semplice. Il software BBAriannaDistr converte dal formato testo al formato EDIFACT i messaggi di tipo: DESADV: avviso di spedizione prodotti. ORDRSP: risposta all ordine. inviati dall utente al sistema Arianna. Ogni file è una sequenza di linee di testo ASCII; ogni linea di testo è terminata dalla coppia di caratteri CR/LF, che sono i terminatori di linea per i file di testo MS-DOS. Ciascuna linea è composta da una sequenza di campi separati da un carattere ",": Esempio: < Campo 1>,<Campo 2>,...,<Campo N>CRLF... <Campo 1>,<Campo 2>,...,<Campo N>CRLF Eventuali caratteri di spaziatura superflui, all inizio o alla fine di una linea di testo o di un singolo campo, verranno rimossi dal software di conversione. Si tenga inoltre presente che: I campi numerici sono sempre degli interi senza segno. I campi che indicano delle date sono nel formato AAAAMMGG: per esempio la data del 26 Aprile 2004 viene indicata come " ". Gli identificatori sono dei campi alfanumerici che hannno lunghezza massima di 17 caratteri. I codici EAN sono dei numeri a 13 cifre (12 cifre più il check digit). Gli EAN Location Code sono dei particolari codici EAN, attribuiti dall agenzia Arianna, che hanno la funzione di identificare univocamente gli utenti Arianna (distributori, editori, grossisti, librerie ecc.). Il tracciato dei messaggi in formato testo è descritto nella sezione successiva. Arianna 5 Versione 2.02

6 2 FORMATO DEI MESSAGGI CONTENUTI NEI FILE DI TESTO In questa sezione verranno descritti i tracciati dei messaggi contenuti nei file di testo (txt). 2.1 MESSAGGIO DESADV (AVVISO DI SPEDIZIONE) Formato I file di testo possono contenere più messaggi di avviso di spedizione; per ogni avviso di spedizione sono previste una riga di testata, più righe di dettaglio e una riga finale contenente il numero delle linee di dettaglio. Il file termina con una riga contenente il numero di documenti di avviso di spedizione presenti nel file. La riga di testata del messaggio di avviso di spedizione ha il seguente formato: dove: DESADV,<EAN destinatario>,<identificatore dell'avviso di spedizione>,<data di spedizione>[,<numero di colli>] <EAN destinatario> è l EAN Location Code che identifica il destinatario (Libreria) dell avviso di spedizione. <identificatore dell'avviso di spedizione> è il codice univoco che identifica il documento di avviso di spedizione. <data di spedizione> è la data di spedizione delle merci. <numero di colli> opzionale è il numero di confezioni/pacchi con cui è stata inviata la merce. Le righe di dettaglio del messaggio di avviso di spedizione hanno il formato: dove: <tipo codice articolo>,<codice articolo>,<quantità>,<qualificatore quantità> <tipo codice articolo> può essere "EAN" o "ISBN". <codice articolo> è il codice EAN o ISBN dell articolo ordinato. <quantità> è la quantità evasa, ordinata, in backorder, cancellata o gratuita. <qualificatore quantità> identifica il tipo di quantità come riportato nella tabella: CODICE DESCRIZIONE 0 Quantità evasa 1 Quantità ordinata 2 Quantità in backorder 3 Quantità cancellata 4 Quantità gratuita La riga finale del messaggio di avviso di spedizione ha il formato: dove: END,<numero linee di avviso di spedizione> Arianna 6 Versione 2.02

7 dove: <numero linee di avviso di spedizione> è il numero di linee di avviso di spedizione contenute nel singolo documento. La riga finale del file ha il formato: COUNT,<numero messaggi di avviso di spedizione> <numero messaggi di avviso di spedizione> è il numero dei documenti di avviso di spedizione contenuti nel file Note Il campo <qualificatore qualità> è sempre obbligatorio, anche se si tratta di quantità evasa. La coppia di campi <quantità>,<qualificatore quantità> può essere ripetuta nella medesima riga di dettaglio se i qualificatori quantità sono tutti di tipo differente Esempio DESADV, XXXX,DES0541, , ,3 E AN, ,8,0,6,1 EAN, ,5,0,5,1,1,4 EAN, ,2,0,3,1 ISBN, ,1,0 EAN, ,1,0 EAN, ,2,0 END,6 DESADV, XXXX,A00194, , EAN, ,2,0 EAN, ,1,0 END, 2 COUNT,2 Arianna 7 Versione 2.02

8 2.2 MESSAGGIO ORDRSP (RISPOSTA ALL'ORDINE) Formato I file di testo possono contenere più messaggi di risposta all ordine; per ogni documento di risposta all o rdine è prevista una riga di testata. Al momento non sono previste righe di dettaglio, anche se è presente la riga con il contatore delle linee di dettaglio. Il file termina con una riga contenente il numero di documenti di risposta all ordine presenti nel file. La riga di testata del messaggio di risposta all ordine ha il seguente formato: dove: ORDRSP,<EAN destinatario><identificatore risposta all ordine>,<numero dell'ordine originale>,<stato dell ordine> <EAN destinatario> è l EAN Location Code che identifica il destinatario (Libreria) della risposta all ordine. <identificatore risposta all ordine> è il codice univoco che identifica il documento di risposta all ordine. <numero dell'ordine originale> è il numero dell ordine assegnato dall acquirente. <stato dell ordine> è lo stato dell ordine (non processato, accettato, non accettato ecc.) come riportato nella tabella: CODICE DESCRIZIONE 0 Ordine non processato 1 Ordine non accettato 2 Ordine accettao con variazione 3 Ordine accettato senza variazioni La riga finale del messaggio di END,0 risposta all ordine ha il formato: non essendo previste, al momento, righe di dettaglio. Il file termina con la riga finale che ha il formato: dove: COUNT,<numero messaggi di risposta all ordine> <numero messaggi di risposta all ordine> è il numero dei documenti di risposta all ordine contenuti nel file Note Il campo <stato dell ordine> è sempre obbligatorio, anche se si tratta di ordine non processato Esempio ORDRSP, XXXX,ORD001,ORD-001,0 END,0 Arianna 8 Versione 2.02

9 ORDRSP, XXXX,ORD012,ORD012,0 END,0 COUNT,2 Arianna 9 Versione 2.02

10 3 UTILIZZO DELLA BBARIANNADISTR La BBAriannaDistr è un programma per la conversione di documenti verso il sistema Arianna: traduce i documenti in formato testo (descritti nel capitolo precedente) da inviare ad Arianna avviso di spedizione e risposta all ordine in formato EDIFACT. I file in formato EDIFACT hanno estensione ".edi" e per semplicità verranno chiamati file EDI, i file in formato testo hanno estensione ".txt" e verranno chiamati file FLAT. La BBAriannaDistr è un applicazione scritta per essere usata da linea di comando, o all interno di un file batch; non prevede l intervento interattivo da parte dell utente e può essere usato come chiamata di sistema all interno di qualsiasi applicativo. Può risiedere in qualunque cartella sul computer locale, dove deve essere collocato anche il file di configurazione, "bbariannadistr.ini", contenente i parametri necessari al funzionamento e il file "cygwin1.dll". Nella stessa cartella verrà anche generato automaticamente il file "bbariannadistr.cnt", utilizzato dal programma per mantenere l ultimo numero del progressivo dei documenti convertiti da FLAT a EDI. 3.1 CONFIGURAZIONE Il file di configurazione è un file di testo di nome "bbariannadistr.ini" contenente righe nel formato: parametro = valore Nel file è prevista la possibilità di aggiungere commenti inserendo un carattere "#" all inizio della riga. I parametri riconosciuti sono: Obbligatori: EAN = EAN Location Code dell utente (identificativo dell editore/distributore rilasciato dall agenzia Arianna). PWD = password (password EDI dell utente rilasciata dall agenzia Arianna). Facoltativi: OUTDIR = percorso (cartella di destinazione del file convertito, se non specificato verrà usata la stessa cartella contente il file da tradurre) Esempio di configurazione #Inserire EAN (Obbligatorio) EAN= XXXX #Inserire PASSWORD (Obbligatorio) PWD=ABCD123 #Inserire il percorso della directory di destinazione (facoltativo) OUTDIR=C:\Arianna\file\output\ 3.2 OPZIONI DEL PROGRAMMA Il programma può essere usato per convertire un singolo file La sintassi per l esecuzione del programma è la seguente: Arianna 10 Versione 2.02

11 bbariannadistr < -f -v > <argomento> dove le opzioni -f, -v determinano la modalità operativa e il significato dell argomento. Se il programma viene lanciato senza argomento viene stampato a video un breve prospetto riassuntivo della sintassi e viene segnalato come errore. Le possibili opzioni sono: -f <nome file>: converte il singolo file indicato da <nome file>; se è privo di percorso il file deve essere nella stessa cartella contenete il programma bbariannadistr.exe. -v: restituisce la versione del programma BBAriannaDistr (tale opzione è priva di argomento). Il file di configurazione bbariannadistr.ini deve essere presente nella stessa directory ove è presente il file eseguibile. Inoltre occorre lanciare il programma dalla directory contenente i file di configurazione ed eseguibile. Si consiglia di indicare sempre il percorso di tutti i file. 3.3 ESECUZIONE L applicazione bbariannadistr.exe converte file FLAT in EDI. Il file ottenuto dopo la conversione (file in uscita) si trova nella stessa cartella del file da convertire (file in ingresso) se nel file di configurazione "bbariannadistr.ini" il parametro OUTDIR è commentato o non valorizzato; se invece tale parametro è valorizzato, i file in uscita si troveranno nella cartella indicata dal parametro OUTDIR. Il programma crea un file in uscita con lo stesso nome del file in ingresso, cambiando semplicemente l estensione da "txt" a "edi". Per esempio il file desadv1.txt verrà convertito nel file desadv1.edi. In caso di errore durante la conversione, il programma interrompe l elaborazione, segnala in modo dettagliato l errore (descrizione dell errore, parametro e valore, riga e file in ingresso che hanno generato l errore) su standard output. Il programma restituisce d errore. 0 se la conversione è andata a buon fine, altrimenti restituisce il relativo codice Il file in uscita EDI, se esistente, viene sovrascritto. In caso di errore non viene generato alcun file in uscita, e a video verrebbero segnalate le informazioni di dettaglio relative all errore: L'elaborazione del documento TXT C:\Arianna\file\input\icg.txt e' fallita. Codice errore: 222 Codice Ean/Isbn con lunghezza errata Codice Ean/Isbn = Elaborazione interrotta Linea 6 contenente errori: EAN,97888,1,0 Programma terminato con errore Esempi di utilizzo Assumendo sia stato usato il file "bbariannadistr.ini" descritto nel paragrafo Esempio di configurazione, avremo: bbariannadistr.exe f C:\Arianna\file\input\ desadv1.txt Arianna 11 Versione 2.02

12 Verrà generato nella cartella C:\Arianna\file\output\ il file desadv1.edi Il file desadv1.txt da tradurre può contenere più messaggi ma dello stesso tipo, come in questo esempio composto solo da DESADV: DESADV, XXXX,DES0541, ,1 EAN, ,8,0,6,1 EAN, ,5,0,5,1,1,4 EAN, ,2,0,3,1 ISBN, ,1,0 EAN, ,1,0 EAN, ,2,0 END,6 DESADV, XXXX,A00194, EAN, ,2,0 EAN, ,1,0 END,2 DESADV, ZZZZ,D00101, EAN, ,1,0 EAN, ,1,0 END,2 COUNT,3 Il file da tradurre può contenere più messaggi tutti di tipo ORDRSP: ORDRSP, XXXX,RSP01,RSP02,0 END,0 ORDRSP, ZZZZ,ORDRS01,ORDRS01,0 END,0 COUNT,2 bbarianna.exe -v Verrà restituita la versione del programma: BBAriannaDistr versione: DESCRIZIONE DEGLI ERRORI Nella seguente tabella sono riportati i codici e le descrizioni degli errori restituiti dal programma CODICE DESCRIZIONE 101 Errore apertura file in lettura 102 Errore apertura file in scrittura 201 Opzione non specificata o non valida per il programma 202 Nome file da convertite non specificato 203 Estensione file da convertite non riconosciuta 204 Errore nei contenuti del file ini 205 File di configurazione con EAN mancante (obbligatorio) 206 File di configurazione con PASSWORD mancante (obbligatorio) 211 Sequenza segmenti Linea Messaggio Linea Dettaglio Linea contatore NON rispettata 212 Segmento non valido o non riconosciuto 213 Sequenza segmento di messaggio desadv non valida 214 Sequenza segmento di linea desadv non valida 215 Sequenza segmento di messaggio ordrsp non valida 216 Sequenza messaggi di tipo differente 221 Data spedizione merce non valida Arianna 12 Versione 2.02

13 222 Codice Ean/Isbn con lunghezza errata Codice Ean con carattere non consentito Codice Ean con checkdigit errato Codice Isbn con carattere non consentito Codice Isbn con checkdigit errato 223 Tipo quantità sconosciuto 224 Quantità non numerica 225 Stato ordine sconosciuto 226 Contatore linee errato 227 Contatore messaggi errato In caso di errore vengono segnalate ulteriori informazioni di dettaglio relative all errore come: In caso di errore vengono segnalate ulteriori informazioni di dettaglio relative all errore come: Nome file: <nome file> Nome file ini: bbariannadistr.ini Linea: <linea in errore> Data: <data non valida> Quantità: <quantità in errore> Codice Ean/Isbn: <codice in errore> Tipo quantità: <tipo quantità non valida> Stato ordine: <stato ordine non valido> Arianna 13 Versione 2.02

14 4 ARCHIVIO PRODOTTI E PARTECIPANTI Per la descrizione del flusso delle informazioni e del formato dei dati dell anagrafica prodotti e partecipanti si rinvia al documento Record prodotti e partecipanti (Record_prodotti_e_partecipanti.doc). Arianna 14 Versione 2.02