TransdatiX.Convert

Der Einsatz von TransdatiX.Convert

Version 2.0.1 vom 06.02.2005

Dieses Dokument beschreibt, wie man Eingangsdateien für TransdatiX erstellt, damit die Konvertierung ready2use erfolgreich ist. Als Beispiel werden TransdatiX.Convert hogast Rechnungen genutzt.

Inhalt

Einführung
Datenstruktur
Aufbau der Eingangsdaten
Identität der Datensätze
Absolute Namen
Datenfragmente
Nomenklatur der CSV-Dateien oder XML-Elemente
Verflachung einer 1:1-Beziehung
Verflachung einer 1:n-Beziehung
Übersetzungstabellen
Aufbereitung der Eingangsdaten als CSV-Dateien
Aufbereitung der Eingangsdaten als XML-Dateien

Einführung

Die TransdatiX.Convert-Module sind Komponenten, die Dienste zur Konvertierung von Dokumenten zwischen Formaten anbieten. Durch Verwendung von TransdatiX.Convert können Sie die Kosten für die Konvertierung Ihrer Daten radikal senken:

Sie müssen sich nicht mit komplizierten Formaten wie EDIFACT, ebXML oder DATANORM auseinandersetzen, allein die Einarbeitung kann mehrere Tage in Anspruch nehmen.
TransdatiX.Convert bietet eine große Flexibilität bei den Eingangsformaten, da
unterschiedliche Datenformate eingangsseitig (CSV, XML) unterstützt werden. Details
es an die Komplexität und Hierarchiestruktur Ihrer Daten angepasst ist. Details
automatische Datenübersetzungen mittels Übersetzungstabellen (Migrationstabellen) zur Laufzeit möglich sind. Details
Die Eingangsdateien, mit denen Sie den Konverter anstoßen, sind z.B. einfache CSV-Dateien, die aus den meisten EDV-Systeme einfach exportiert werden können.
Alle TransdatiX.Convert-Module unterliegen den gleichen allgemeinen Regeln für die Aufbereitung der Daten, unabhängig davon, um welchem Belegtyp es sich handelt. Wenn Sie z.B. bereits Rechnungsdaten für Metro exportiert haben, ist es leicht, mit der gleichen Technik die Lieferscheindaten für Spar vorzubereiten.
Datenfelder mit dem gleichen Inhalt sind gleich benannt, d.h. der Export für Metro-Rechnungen ist mit minimalen Änderungen für Spar- oder Billa-Rechnungen nutzbar.
TransdatiX.Convert ist sofort einsatzbereit. Die Details der Formate wurden bereits mit dem Empfänger geklärt (dieser Vorgang kann bei Eigenentwicklung mehrere Monate dauern).
Sie können TransdatiX.Convert mittels TransdatiX.Configurator mit anderen Komponenten wie .Adapt, .Comm oder .Tool zu komplexen Prozessen kombinieren, um eine Reihe von Aktionen per Mausklick auszuführen.

Als Beispiel wird die Dokumentation der Rechnungsdaten in diesem Dokumentation behandelt. Diese Vorgehensweise ist für alle anderen Belegtypen (Lieferscheine, Transportaufträge, etc.) genau gleich. Siehe die jeweilige Konverterdokumentation für weitere Details.

Datenstruktur

Eine normale Rechnung enthält mindestens folgende Daten:

Einmalige Rechnungskopfdaten wie Rechnungsnummer oder Gesamtbetrag
Daten, die für jede Rechnungsposition wiederholt werden, wie Artikelnummer oder MwSt.-Satz der Zeile

Wir können Rechnungsköpfe und Rechnungspositionen Datengruppen nennen, da sie als Behälter für unterschiedliche einfache Daten dienen.

Hier haben wir das erste Beispiel einer Datenhierarchie (oder einfach Hierarchie benannt). Eine Rechnung besitzt genau einen Kopf, dem keine oder mehrere Positionen zugeordnet sind, das bedeutet auch, dass zwischen den Datengruppen Rechnungskopf und Rechnungspositionen eine Beziehung vorhanden ist. Schematisch können wir diese Hierarchie folgendermaßen darstellen:

Rechnungskopf (muss vorhanden sein)
1. Rechnungsposition (optional)
2. Rechnungsposition (optional)
...
9999. Rechnungsposition (optional)

Oder in komprimierter Form:

Rechnungskopf
Rechnungsposition (0–9999)

In der Rechnungsposition z.B. hat man in der Regel Daten, die einmal vorkommen (wie die Artikelnummer) oder die wiederum öfters vorkommen können (wie die Positionsrabatte). Mit diesen Daten, die mehr als einmal erscheinen können, bietet sich an, sie hierarchisch auszugliedern und eine neue Beziehung zu definieren. Betroffen sind z.B. Kopf- und Positionsrabatte sowie Kopf- und Positionssteuerinformationen.

Ein typisches EDIFACT-Rechnungsdokument definiert folgende Hierarchie:

Name     Wiederholungen
Rechnungskopf
Rechnungsposition (0–9999)
Positionsrabatt (0–15)
Positionssteuer (1–99)
Kopfrabatt (0–15)
Kopfsteuer (0–10)

Wenn wir uns nun einen (elektronischen) Brief vorstellen, in welchem mehrere Rechnungen für den gleichen Empfänger enthalten sind, dann haben wir genau die komplette Hierarchie eines Rechnungsdokuments, die ein TransdatiX.Convert behandeln kann. Diese neue Datengruppe, die Daten wie Absender und Empfänger enthält, können wir Übertragungsdaten nennen:

Datengruppe     Beschreibung     Wiederholungen
Message Nachricht
Envelope Übertragungsdaten
Invoice Rechnungskopf (1–9999)
InvoicePos Rechnungsposition (0–9999)
InvoicePosCharge Positionsrabatt (0–15)
InvoicePosTax Positionssteuer (1–99)
InvoiceCharge Kopfrabatt (0–15)
InvoiceTax Kopfsteuer (1–10)

In dieser Form wird die Struktur der Daten aller TransdatiX.Convert dokumentiert, siehe z.B. TransdatiX.Convert hogast Rechnungen.

Weitere Hinweise zu den Wiederholungen:

Wenn eine Datengruppe genau nur 1-mal wiederholt werden kann, dann wird dies (1:1) in der Regel unterlassen.
Wiederholungen von 0 oder mehr deuten auf eine optionale Angabe.
Wiederholungen von 1 oder mehr deuten auf eine Mussangabe.

Aufbau der Eingangsdaten

Sie übergeben dem TransdatiX.Convert alle Daten des Beleges in Dateien. Die zwei Formate für die Eingangsdateien, die derzeit vom Konverter unterstützt werden, sind CSV (Comma-Separated Values) und XML (Extensible Markup Language).

CSV-Dateien sind normalerweise kostengünstiger zu generieren und können z.B. aus MS Excel erstellt werden, erlauben aber nur eine flache Darstellung der Daten:

InvoicePos.csv

InvoiceID;InvoicePosID;ItemNumber;ItemName;QuantityInvoiced;UnitInvoiced;NettPrice; NettAmount1; 10;83K321;Handtuch PREMIUM NOVA 8300-1310;25;PCE;5,933;148,335

InvoicePosCharge.csv

InvoiceID;InvoicePosID;Status;CalculationLevel;Percentage 1;10;A;1;20

In XML dagegen können wir Daten in einer Hierarchie nachbilden. XML ist das interne Format, in welchem TransdatiX seine Daten beschreibt:

InvoicePos.xml

<InvoicePos InvoiceID="1" InvoicePosID="10"> <ItemNumber>83K321</ItemNumber> <ItemName>Handtuch PREMIUM NOVA 8300-1310</ItemName> <QuantityInvoiced>25</QuantityInvoiced> <UnitInvoiced>PCE</UnitInvoiced> <NettPrice>5,933</NettPrice> <NettAmount>148,335</NettAmount> <InvoicePosCharge InvoiceID="1" InvoicePosID="10"> <Status>A</Status> <CalculationLevel>1</CalculationLevel> <Percentage>20</Percentage> </InvoicePosCharge> <InvoicePosTax InvoiceID="1" InvoicePosID="10"> <Qualifier>VAT</Qualifier> <Percentage>20</Percentage> <Amount>29,667</Amount> </InvoicePosTax> </InvoicePos>

Identität der Datensätze

Die drei CSV-Dateien und die XML-Datei im Beispiel enthalten die gleichen Daten. Wir sehen trotzdem, dass es eine genaue Logik gibt, wie man von flachen CSV-Dateien auf hierarchische Daten kommt: Wichtig ist, dass ein Datensatz eine Identität besitzt – somit kann sein genauer Platz in der Hierarchie ermittelt werden.

Die Identität eines Datensatzes wird durch ein oder mehrere Felder namens Schlüsselfelder festgelegt, die eindeutig sein müssen. Die Schlüsselfelder einer Datengruppe sind die Schlüsselfelder der übergeordneten Datengruppe zuzüglich die eigene relative Identität, deren Name aus dem Namen der Datengruppe plus dem Zusatz ID erstellt wird:

Elementname     Schlüsselfelder
Invoice InvoiceID
InvoicePos InvoiceID +
InvoicePosID
InvoicePosCharge InvoiceID +
InvoicePosID +
InvoicePosChargeID
InvoicePosTax InvoiceID +
InvoicePosID +
InvoicePosTaxID
InvoiceCharge InvoiceID +
InvoiceChargeID
InvoiceTax InvoiceID +
InvoiceTaxID

Im folgenden Beispiel, welches eine Steuerinformationszeile einer Rechnungsposition darstellt, wird eindeutig identifiziert, dass der Satz zu der Rechnungsposition 10 in der Rechnung 1 gehört.

InvoicePosTax.csv

InvoiceID;InvoicePosID;Qualifier;Percentage;Amount 1;10;VAT;20;29,667

Absolute Namen

Im obigen Beispiel können wir feststellen, dass es sich um Steuerinformationsdaten handelt, weil der Dateiname (InvoicePosTax.csv) jenem der Datengruppe entspricht. In den Fällen, in welchem der Dateiname nicht zur Verfügung steht, können wir den sogenannten absoluten Namen des Feldes verwenden. Der absolute Name identifiziert eindeutig ein Feld in einem gesamten Schema und besteht aus dem Namen der Datengruppe zuzüglich dem Namen des Feldes. Das Feld Qualifier könnte z.B. zu folgenden Datengruppen gehören: InvoiceCharge, InvoiceTax, InvoicePosTax. Die entsprechenden absoluten Namen lauten: InvoiceChargeQualifier, InvoiceTaxQualifier, InvoicePosTaxQualifier.

Letzteres Beispiel unter Angebe von absoluten Namen:

InvoiceID;InvoicePosID;InvoicePosTaxQualifier;InvoicePosTaxPercentage;
InvoicePosTaxAmount
1;10;VAT;20;29,667

Datenfragmente

Der TransdatiX.Convert ermöglicht die Verarbeitung von bis zu 10 Dateien, die im CSV- oder XML-Format vorliegen sollen. Neuartig ist, dass Sie nicht unbedingt eine Datei pro Datengruppe exportieren sollen, sondern Sie übergeben Datenfragmente aus der gesamten Information und der .Convert kümmert sich um die Zusammenführung der Teile, als ob es ein Puzzle wäre. Dies erlaubt eine enorme Flexibilität bei der Aufbereitung der Dateien.

Sie könnten z.B. die Felder für bestimmte Datensätze in zwei Dateien teilen:

InvoicePos-1.csv

InvoiceID;InvoicePosID;ItemNumber;ItemName 1;10;83K321;Handtuch PREMIUM NOVA 8300-1310

InvoicePos-2.csv

InvoiceID;InvoicePosID;QuantityInvoiced;UnitInvoiced;NettPrice;NettAmount 1;10;25;PCE;5,933;148,335

Dies gilt auch für XML-Dateien:

InvoicePos.xml

<InvoicePos-1 InvoiceID="1" InvoicePosID="10"> <ItemNumber>83K321</ItemNumber> <ItemName>Handtuch PREMIUM NOVA 8300-1310</ItemName> </InvoicePos-1> <InvoicePos-2 InvoiceID="1" InvoicePosID="10"> <QuantityInvoiced>25</QuantityInvoiced> <UnitInvoiced>PCE</UnitInvoiced> <NettPrice>5,933</NettPrice> <NettAmount>148,335</NettAmount> </InvoicePos-2>

Nomenklatur der CSV-Dateien oder XML-Elemente

Der TransdatiX.Convert erkennt anhand des Names der Dateien (oder Elemente) und der Namen der Felder, dass es sich um die Rechnungsposition-Datengruppe handelt. Zusätzlich, da die Identität des Datensatzes gleich ist, werden die zwei Fragmente zusammengeführt. Im Beispiel enthält die Datei InvoicePos-1.csv die Beschreibungstexte der Position und die Datei InvoicePos-2.csv enthält die kaufmännischen Werte.

Wenn die Dateien im CSV-Format übergeben werden, wird eine bestimmte Nomenklatur von den Dateinamen verlangt:

<Datengruppe>[<Sonderzeichen><Zusatz>].{<Dateierweiterung>}

Der Dateiname muss mit dem absoluten Namen der Datengruppe beginnen, gefolgt von einem optionalen, nicht alphabetischen Zeichen und einem Zusatz (z.B. einer Durchnummerierung), um die Dateien voneinander zu unterscheiden.

Folgende Dateinamen wären für unser Beispiel korrekt:

InvoicePos-Metro.csv
InvoicePos_2005-02-07.txt
InvoicePos.csv
InvoicePos.1.csv

Dagegen sind folgende Dateinamen ungültig:

InvoicePos1.csv     (Trennzeichen zwischen Datengruppe und Zusatz fehlt)
InvoicePosition.csv (InvoicePosition ist keine Datengruppe)
Rechnungen.csv (Rechnungen ist keine Datengruppe)

Verflachung einer 1:1-Beziehung

Diese Technik erlaubt das Exportieren einer hierarchischen Beziehung in eine einzige Datei. Nehmen wir folgendes Datenfragment (eine Rechnungsposition und ihren Steuersatz) an:

InvoicePos.csv

InvoiceID;InvoicePosID;ItemNumber;ItemName;QuantityInvoiced;UnitInvoiced;NettPrice; NettAmount 1;10;83K321;Handtuch PREMIUM NOVA 8300-1310;25;PCE;5,933;148,335

InvoicePosTax.csv

InvoiceID;InvoicePosID;Qualifier;Percentage;Amount 1;10;VAT;20;29,667
oder in XML:

InvoicePos.xml

<InvoicePos InvoiceID="1" InvoicePosID="10"> <ItemNumber>83K321</ItemNumber> <ItemName>Handtuch PREMIUM NOVA 8300-1310</ItemName> <QuantityInvoiced>25</QuantityInvoiced> <UnitInvoiced>PCE</UnitInvoiced> <NettPrice>5,933</NettPrice> <NettAmount>148,335</NettAmount> <InvoicePosTax InvoiceID="1" InvoicePosID="10"> <Qualifier>VAT</Qualifier> <Percentage>20</Percentage> <Amount>29,667</Amount> </InvoicePosTax> </InvoicePos>

Wenn die Anzahl der Vorkommnissen der untergeordneten Datengruppe (Steuer) 1 ist, dann können wir den übergeordneten Satz (Rechnungsposition) um die absoluten Namen der Felder der untergeordnete Datengruppe dazugeben:

InvoicePos.csv

InvoiceID;InvoicePosID;ItemNumber;ItemName;QuantityInvoiced;UnitInvoiced;NettPrice; NettAmount;TaxQualifier;TaxPercentage;TaxAmount 1;10;83K321;Handtuch PREMIUM NOVA 8300-1310;25;PCE;5,933;148,335;VAT;20;29,667

Wichtig ist nur, dass die Namen der Felder identifiziert werden. In XML würde es folgendermaßen ausschauen:

InvoicePos.xml

<InvoicePos InvoiceID="1" InvoicePosID="10"> <ItemNumber>83K321</ItemNumber> <ItemName>Handtuch PREMIUM NOVA 8300-1310</ItemName> <QuantityInvoiced>25</QuantityInvoiced> <UnitInvoiced>PCE</UnitInvoiced> <NettPrice>5,933</NettPrice> <NettAmount>148,335</NettAmount> <TaxQualifier>VAT</TaxQualifier> <TaxPercentage>20</TaxPercentage> <TaxAmount>29,667</TaxAmount> </InvoicePos>

Wenn Sie z.B. keine anderen Steuern für Ihre Artikel haben als die Mehrwertsteuer, können Sie sich die explizite Erstellung einer Datei für die InvoicePosTax sparen.

Verflachung einer 1:n-Beziehung

Wenn die untergeordnete Datengruppe öfter vorkommt, können Sie auch die vorherige Technik verwenden, Sie sollten aber am Ende der jeweiligen Felder eine Zahl hinzufügen, mit welcher die Felder des gleichen Datensatzes identifiziert werden. Folgendes Beispiel zeigt eine Rechnungsposition mit 3 möglichen Positionsrabatten mit 5 %, 2 % und 7 %:

InvoicePos.csv

InvoiceID;InvoicePosID;ItemNumber;ItemName;QuantityInvoiced;UnitInvoiced;NettPrice; NettAmount 1;10;83K321;Handtuch PREMIUM NOVA 8300-1310;25;PCE;5,933;148,335

InvoicePosCharge.csv

InvoiceID;InvoicePosID;Status;CalculationLevel;Percentage 1;10;A;1;5 1;10;A;2;2 1;10;A;3;7
In XML:

InvoicePos.xml

<InvoicePos InvoiceID="1" InvoicePosID="10"> <ItemNumber>83K321</ItemNumber> <ItemName>Handtuch PREMIUM NOVA 8300-1310</ItemName> <QuantityInvoiced>25</QuantityInvoiced> <UnitInvoiced>PCE</UnitInvoiced> <NettPrice>5,933</NettPrice> <NettAmount>148,335</NettAmount> <InvoicePosCharge InvoiceID="1" InvoicePosID="10"> <Status>A</Status> <CalculationLevel>1</CalculationLevel> <Percentage>5</Percentage> </InvoicePosTax> <InvoicePosCharge InvoiceID="1" InvoicePosID="10"> <Status>A</Status> <CalculationLevel>2</CalculationLevel> <Percentage>2</Percentage> </InvoicePosTax> <InvoicePosCharge InvoiceID="1" InvoicePosID="10"> <Status>A</Status> <CalculationLevel>3</CalculationLevel> <Percentage>7</Percentage> </InvoicePosTax> </InvoicePos>

Wenn man die Technik der Verflachung einer 1:n-Beziehung verwendet, dann würden die Eingangsdaten folgendermaßen ausschauen:

InvoicePos.csv

InvoiceID;InvoicePosID;ItemNumber;ItemName;QuantityInvoiced;UnitInvoiced;NettPrice; NettAmount;ChargeStatus1;ChargeCalculationLevel1;ChargePercentage1;ChargeStatus2; ChargeCalculationLevel2;ChargePercentage2;ChargeStatus3;ChargeCalculationLevel3; ChargePercentage3 1;10;83K321;Handtuch PREMIUM NOVA 8300-1310;25;PCE;5,933;148,335;A;1;5;A;2;2;A;3;7
oder in XML:

InvoicePos.xml

<InvoicePos InvoiceID="1" InvoicePosID="10"> <ItemNumber>83K321</ItemNumber> <ItemName>Handtuch PREMIUM NOVA 8300-1310</ItemName> <QuantityInvoiced>25</QuantityInvoiced> <UnitInvoiced>PCE</UnitInvoiced> <NettPrice>5,933</NettPrice> <NettAmount>148,335</NettAmount> <ChargeStatus1>A</ChargeStatus1> <ChargeCalculationLevel1>1</ChargeCalculationLevel1> <ChargePercentage1>5</ChargePercentage1> <ChargeStatus2>A</ChargeStatus2> <ChargeCalculationLevel2>2</ChargeCalculationLevel2> <ChargePercentage2>2</ChargePercentage2> <ChargeStatus3>A</ChargeStatus3> <ChargeCalculationLevel3>3</ChargeCalculationLevel3> <ChargePercentage3>7</ChargePercentage3> </InvoicePos>

Übersetzungstabellen

Die Übersetzungstabellen oder Migrationstabellen erlauben eine Korrektur der Werte in gegebenen Spalten. Stellen Sie sich vor, dass Sie die Mehrwertsteuersätze als A=10 und B=20 kodiert haben. Sie können zuerst den Export der Steuerdaten mit diesen Codes vornehmen:

InvoicePosTax.csv

InvoiceID;InvoicePosID;Qualifier;PercentageCode;Amount 1;10;VAT;B;29,667 1;20;VAT;A;10,80 1;30;VAT;B;120,10

Benennen Sie die Spalte mit einem Namen, der nicht in der Definition vorkommt, und reichen Sie dann die Übersetzungstabelle als Datei nach:

InvoicePosTaxPercentage-Migration.csv

InvoicePosTaxPercentageCode;InvoicePosTaxPercentage A;10 B;20

Der TransdatiX.Convert erledigt die Übersetzung der Werte zur Laufzeit.

Aufbereitung der Eingangsdaten als CSV-Dateien

Wenn Sie dem TransdatiX.Convert Ihre Daten im CSV-Format übergeben, sind folgende Regeln zu berücksichtigen:

Die erste Zeile muss die Feldnamen enthalten. Damit kann der TransdatiX.Convert die Werte zu den Feldern zuordnen.
Das Spaltentrennzeichen kann jedes beliebige, nicht alphanumerische Zeichen sein (empfohlen werden Semikolon [;], Komma [,] oder Tabulator) und muss für die ganze Datei gelten.
Das Zeilentrennzeichen kann CR+LF (CHR(13)+CHR(10), Windows) oder lediglich LF (CHR(10), UNIX) sein.
Die Dateinamen können beliebig in Groß- oder Kleinbuchstaben ausgegeben werden. Empfohlen wird eine einheitliche Schreibweise.
Daten können nach Bedarf unter Anführungszeichen angegeben werden, z.B.:

InvoicePos.csv

EANCustomer;ShortName;LongName 9090923378;"Sherry";Sherry Tio Pepe, .7 l

Hinweis: Das ist zwingend notwendig, wenn im Wert selber das Spalten- oder Zeilentrennzeichen vorkommt.

Wenn das Anführungszeichen Bestandteil des Wertes ist, dann müssen die enthaltenen Anführungszeichen doppelt ausgegeben werden:

InvoicePos.csv

EANCustomer;ShortName;LongName 9090923378;"Sherry";"Sherry ""Tio Pepe"", .7 l"
Dezimalformate
Als Dezimaltrennzeichen in numerischen Werten kann Komma [,] oder Punkt [.] verwendet werden. Das Tausender-Trennzeichen darf nicht verwendet werden.

Hinweis: Sollte das Dezimaltrennzeichen gleich wie das Spaltentrennzeichen sein, dann muss der Dezimalwert unter Anführungszeichen ausgegeben werden.

InvoicePos.csv

QuantityInvoiced,UnitInvoiced,NettPrice,NettAmount 20,PCE,"10,50",210.00
Datumsformate
Datumsfelder können in folgenden Formaten ausgegeben werden:
YYYY-MM-DD     (z.B. 2005-07-02)
DD-MM-YYYY (z.B. 02-07-2005)
DD-MM-YY (z.B. 02-07-05)
Anstatt des Bindestrichs [-] als Trennzeichen können auch folgende Trennzeichen verwendet werden: Punkt [.], Komma [,], Schrägstrich [/], Backslash [\].
Uhrzeitformate
Folgende Datumsformate für Uhrzeit werden akzeptiert:
HH:MM     (z.B. 18:30)
HH:MM:SS (z.B. 18:30:25)
In allen Fällen wird die Zeit im 24-Stunden-Format erwartet.
Formate für Datum und Uhrzeit
Jede Kombination von Datums- und Uhrzeitformaten in der Reihenfolge <Datumsformat><Leerzeichen><Uhrzeitformat> wird akzeptiert,
z.B.: DD-MM-YY HH:MM:SS (02-07-05 18:30:25).

Aufbereitung der Eingangsdaten als XML-Dateien

Die einzige wichtige Regel ist, dass es sich um eine gültige XML-Datei handelt. Datengruppennamen können absolut sein oder nicht. Dezimalfelder werden mit Punkt als Dezimaltrennzeichen ausgegeben und Datumsfelder werden im Format YYYY-MM-DD HH:MM:SS ausgegeben.


© 2005 MicroTown Software - www.transdatix.com