Schnittstellen- Beschreibung - GDSN-XML -

Transkript

1 Schnittstellen- Beschreibung - GDSN-XML - GDSN XML Subset FMCG - Fast Moving Consumer Goods GDSN Zielmarktprofile: Deutschland, Dänemark, Finnland und Österreich Version /2014 (Dokumentversion 1 in Release 1.01 ab 27. Januar 2014) 1WS_XML_FMCG-GDSN_V1.01-1_d.docx Herausgeber: 1WorldSync GmbH Maarweg 165, Köln

2

3 ÜBERBLICK ÜBERBLICK Inhaltsverzeichnis ÜBERBLICK 1 Inhaltsverzeichnis 1 ANGEPASSTES GDSN XML FÜR DIE GDSN ZIELPROFILE DEUTSCHLAND, DÄNEMARK, FINNLAND UND ÖSTERREICH 2 Einleitung 2 Voraussetzungen 2 Referenzierte Dokumente 3 ERLÄUTERUNG DER SCHEMADATEIEN DES SUBSETS 4 Enthaltene Schemadateien 4 Aufbau der Schemadateien 4 Erläuterung zur Dokumentation 5 Nutzung des GDSN-Attributs genau für eine Zielmarktangabe 5 Nutzung des GDSN-Attributs für mehrere Zielmarktattribute über zusätzliche qualifizierende Angaben 6 Weitergehende Informationen 8 Wiederholbarkeiten 8 Implizit vorausgesetzte Angaben 8 Verweise auf spezielle Typen und Codelisten 8 Verwendung von XML Choice Elementen 9 ÄNDERUNGSHISTORIE DIESER DOKUMENTATION 10 1WorldSync GmbH, Köln 2014 Seite 1

4 Angepasstes GDSN XML für die GDSN Zielprofile Deutschland, Dänemark, Finnland und Österreich Einleitung Dieses Dokument erläutert die Grundlagen zum Verständnis der für die GDSN Zielprofile Deutschland, Dänemark, Finnland und Österreich bereitgestellten modifizierten XML-Schemadateien zur Übermittlung der Artikelstammdaten über GS1 GDSN XML. Soweit erforderlich werden hier zusätzliche Erläuterungen gegeben, die über die Kommentierungen in den XML Schema-Dateien hinausgehen. Die Schemadateien werden von uns als Hilfestellung bei der Implementierung der o. g. Zielprofile bereitgestellt. Hierzu wurden die original GS1 GDSN XML Schemadateien (Version BMS 2.8) der Catalogue Item Notification (CIN) sowie der verwendeten GDSN-Extensions unter folgenden Gesichtspunkten angepasst: Reduzierung der Komplexität der Originalschemadateien auf den im Rahmen der Zielprofile genutzten Umfang. D.h. nicht genutzte Inhalte wurden aus den Schemadefinitionen entfernt. Einfügen von Dokumentationsblöcken in das so erzeugte Subset der GS1 GDSN XML Schemata: Einfügen der Datenelementnamen gemäß der fachlichen Spezifikation der Zielprofile. Einfügen zusätzlicher Mappinganweisungen (Regeln zur Befüllung nachrichtentechnisch notwendiger Zusatzinformationen (z. B. Agencies), strukturelle Vorgaben zur Sicherstellung der Eindeutigkeit der übermittelten Informationen). Verweis auf spezielle, von den Zielmarkt-Communities festgelegte Codelisten. Einfügen zusätzlicher Aufzählungen im Schema, wenn diese nachrichtentechnisch als Zusatzinformation erforderlich sind. Die Anzahl der notwendigen Schemadateien wurde so klein wie möglich gehalten, um die Navigation innerhalb der Schemadefinition so einfach wie möglich zu halten. Das so entstandene Subset sollte ausschließlich während der Implementierung der eigenen Nachrichtenschnittstelle genutzt werden. Die Schemadateien des Subsets dürfen nicht zur Validierung von CIN s im Datenaustausch via GDSN genutzt werden. Dies gilt insbesondere für Datenempfänger, da CIN s von anderen Datenpools grundsätzlich über die Zielmarktprofile hinausgehende Informationen enthalten können. Diese Informationen wären ggf. zu ignorieren, dürfen aber nicht mit einer Fehlermeldung beantwortet werden! Voraussetzungen Grundlegende Kenntnisse zum Verständnis von XML Schema werden vorausgesetzt. Für die Prozesse und Regeln des Datenaustauschs via GDSN sei auf die entsprechende Dokumentation der GS1 verwiesen. Zur Arbeit mit den Schemadateien sollte ein leistungsfähiger XML Editor verwendet werden. 1WorldSync GmbH, Köln 2014 Seite 2

5 Referenzierte Dokumente Kompendium GDSN Zielmarktprofile Deutschland, Dänemark, Finnland und Österreich, Sektorspezifische Informationen und Datenelemente FOOD / NON-FOOD Beschreibung der Attribute im Detail (Community, Status, Hierarchiestufe, Format, Ausprägungen/Wertebereiche, GDSN Definition, Ergänzende Community Beschreibung/Erläuterung, Verknüpfungen/Bedingungen etc.) Profiles Overview mit Codelisten Kompendium Übersicht der Community Profile und ihrer Attribute inkl. GDSN-Mapping, als Excel mit der Möglichkeit zu Filtern und Sortieren sowie Übersicht der Codelisten und alle Community Codelisten. GS1 XML Schemadateien* BMS Doku / Operational manual * *) Alle GDSN Dokumente / Informationen sind im GS1 Standards Knowledge Centre zu finden: Unter dem ersten Link GDSN XML Business Message Standards erreicht man alle GDSN XML Business Message Standards. Dort wiederum enthält das Catalogue Item Sync Paket (v 2.8 Current) eine Sammlung aller Informationen, um die notwendigen Grundlagen zu verstehen und diesen GS1 Business Message Standard (BMS) zu implementieren: BMS-Dokument: Definiert die Business-Lösung von BMS (erfordert Adobe Acrobat Reader) Technische Lösung Implementierer Paket: Enthält die XSD-Dateien, die für die Umsetzung erforderlich sind. Darüber hinaus bieten die lokalen GS1 Organisationen zahlreiche Übersetzungen und Hilfestellungen an. Hier sei insbesondere auf die Umstellung der nationalen Standardwarenklassifikation auf die GPC (Global Product Classification) in Deutschland hingewiesen, für welche die GS1 Germany vom Leitfaden GPC-Basiswissen über den GPC-Browser bis hin zu Mappinghilfen und der Anwendungsempfehlung für Deutschland umfangreiche Hilfestellung im GS1 Complete Portal anbietet: 1WorldSync GmbH, Köln 2014 Seite 3

6 Erläuterung der Schemadateien des Subsets Das nachfolgende Kapitel enthält detaillierte Erläuterungen zu den enthaltenen Dateien des Subsets sowie zur Interpretation der in diesen Dateien bereitgestellten Dokumentation. Enthaltene Schemadateien Die zu dem Subset gehörenden Schemadateien werden in einen Zip -Archiv ausgeliefert. Dieses Zip-Archiv kann an einer beliebigen Stelle im Dateisystem entpackt werden. Das im Archiv enthaltene Unterverzeichnis commongs1types muss zwingend mit allen zugehörigen Dateien vorhanden sein. Nach dem Entpacken befinden sich im Zielverzeichnis und dem Unterverzeichnis commongs1types folgende Dateien: Zielverzeichnis CatalogueItemNotificationEU-FMCGsubset.xsd AttributeValuePairExtensionEU-FMCGsubset CaseLevelNonGTINLogisticsUnitExtensionEU- FMCGsubset ChemicalIngredientExtensionEU-FMCGsubset Zielverzeichnis\commonGS1Types commongs1typedefinitions commongs1codelisttypes commongdsncodelisttypes commonfood_beverage_tobacco_codelisttypes ExtensionSpecificsTechnicalCharacteristicsExtension EU-FMCGsubset FoodAndBeverageTradeItemExtensionEU- FMCGsubset Für einen ersten Überblick empfiehlt es sich, die CatalogueItemNotificationEU-FMCGsubset.xsd zu öffnen. Einen leistungsfähigen XML-Editor vorausgesetzt, kann von dort aus auch in die genutzten Extensions hineinnavigiert bzw. übergreifend nach einzelnen Attributen gesucht werden. Aufbau der Schemadateien Die Schemadateien wurden grundsätzlich auf den Umfang reduziert, der durch die Zielmarktprofile für Deutschland, Dänemark, Finnland und Österreich definiert ist. D. h. alle darüber hinausgehenden Informationen wurden aus den Schemata entfernt. Die XML-Definitionen der einzelnen Elemente wurden in der Regel entsprechend der GS1 GDSN XML Definition vorgenommen. D. h. sowohl die Kardinalität der Attribute als auch Datentyp und Feldgrößenangaben folgen in der Regel der GS1 GDXN XML Spezifikation. Abweichende fachliche Regeln (Mussangabe statt optional im GDSN, Einschränkungen der Wertebereiche) ergeben sich somit nicht aus dem Schema, sondern sind der zugrunde liegenden fachlichen Dokumentation der Zielmärkte zu entnehmen. Die in der GS1 GDSN XML Definition verwendeten allgemeinen Typen wurden jedoch überwiegend durch explizite Definitionen ersetzt. Damit wird den geltenden Vorgaben im Rahmen des Subsets Rechnung getragen und die Einführung von spezifischen Kommentaren ermöglicht. 1WorldSync GmbH, Köln 2014 Seite 4

7 Erläuterung zur Dokumentation Die Dokumentation der Attributreferenz im Rahmen der Zielmarktprofile sowie speziell zu beachtende Mappinganweisungen sind in den Schemata in Form von XML <annotation> Elementen enthalten. Die Dokumentationsangaben finden sich grundsätzlich bei den entsprechenden GDSN-Attributen, über die der eigentliche Nutzwert angegeben wird. Grundsätzlich werden die GDSN-Attribute in zwei verschiedenen Arten für den Austausch der Informationen für die Zielmärkte genutzt. In den nachfolgenden Beispielen sind Erläuterungen in Form von XML-Kommentaren eingefügt. Zur besseren Identifikation sind diese Kommentare darüber hinaus in Grün. Nutzung des GDSN-Attributs genau für eine Zielmarktangabe Beispiel: Markenname <xs:element name="brandname"> <!--Beginn der annotation mit eindeutiger id--> <xs:annotation id="brandname"> <!--Verweis auf das fachliche Attribut im Zielmarkt, Angabe der Bezeichnung gem. Profiles Overview - hier in Deutsch. Diese Angabe findet sich immer in einem Element <communityattributename> --> <xs:documentation xml:lang="de"> <communityattributename>artikeltexte und -beschreibungen: Markenname</communityAttributeName> <xs:documentation xml:lang="en"> <communityattributename>trade item description information: Brand name</communityattributename> <!--In der appinfo werden bei Bedarf zusätzliche Mappinganweisungen und Hinweise dokumentiert--> <xs:appinfo>attribute restrictions and mapping instructions <xs:documentation xml:lang="de">none <xs:documentation xml:lang="en">none </xs:appinfo> </xs:annotation> </xs:element> 1WorldSync GmbH, Köln 2014 Seite 5

8 Nutzung des GDSN-Attributs für mehrere Zielmarktattribute über zusätzliche qualifizierende Angaben Soweit sich der fachliche Kontext nur über zusätzliche qualifizierende Angaben ergibt, sind diese innerhalb des Dokumentationsblocks der fachlichen Angabe in der appinfo beschrieben. Der Hinweis erfolgt dabei allgemeinsprachlich und in einer an xpath angelehnten Beschreibung. Nachfolgend wird dies anhand der Nutzung der tradeitemregulatoryinformation näher erläutert. Abbildung 1: Grafische Ansicht der tradeitemregulatoryinformation soweit in den Zielmärkten genutzt Die tradeitemregulatoryinformation wird in den Zielmärkten u. a. zur Übermittlung der Angaben verwendet: Ökologisches Produkt: Bio-Kontrollstelle Ökologisches Produkt: Ökologische Herkunft Ökologisches Produkt: Bio-Qualitätskennzeichen Die eigentliche Information ist jeweils in einer Wiederholung der regulatorypermitidentification anzugeben. Die Zuordnung des dort eingetragenen Wertes zum fachlichen Attribut erfolgt über entsprechende Kombinationen von Angaben in den beiden Elementen regulatoryact und regulatoryagency. <xs:element name="regulatorypermitidentification"> <xs:annotation id="regulatorypermitidentification"> <!--Zusätzliches 'documentation' Element klammert die zusammengehörenden Informationen zu einer fachlichen Angabe--> <xs:documentation> <xs:documentation xml:lang="de"> <communityattributename>ökologisches Produkt: Bio-Kontrollstelle</communityAttributeName> <xs:documentation xml:lang="en"> <communityattributename>organic product: Certification body</communityattributename> <xs:appinfo>attribute restrictions and mapping instructions <!--'appinfo' beschreibt allgemeinsprachlich und formalisiert die Werte, die in die qualifizierenden Felder einzutragen sind--> <xs:documentation xml:lang="de">als regulatoryact' den Wert '834_2007_Certification' und für 'regulatoryagency' der Wert 'EU' übermitteln <xs:documentation xml:lang="en">assign the value '834_2007_Certification' for 'regulatoryact' and the value 'EU' for 'regulatoryagency' <xs:field xpath="../../regulatoryact[834_2007_certification]"/> <xs:field xpath="../../regulatoryagency[eu]"/> </xs:appinfo> 1WorldSync GmbH, Köln 2014 Seite 6

9 <!--Nachfolgendes 'documentation' Element für die zusammengehörenden Informationen der nächsten fachlichen Angabe--> <xs:documentation> <xs:documentation xml:lang="de"> <communityattributename>ökologisches Produkt: Ökologische Herkunft</communityAttributeName> <xs:documentation xml:lang="en"> <communityattributename>organic product: Origin</communityAttributeName> <xs:appinfo>attribute restrictions and mapping instructions<xs:documentation xml:lang="de">als 'regulatoryact' den Wert '834_2007_Class' und für 'regulatoryagency' der Wert 'EU' übermitteln <xs:documentation xml:lang="en">assign the value '834_2007_Class' for 'regulatoryact' and the value 'EU' for 'regulatoryagency' <xs:field xpath="../../regulatoryact[834_2007_class]"/> <xs:field xpath="../../regulatoryagency[eu]"/> </xs:appinfo>. </xs:annotation>.. </xs:element> Interpretation der in appinfo unter xpath eingetragenen Ausdrücke: Beispiel anhand des Attributs Ökologisches Produkt: Ökologische Herkunft <xs:field xpath="../../regulatoryact[834_2007_class]"/> <xs:field xpath="../../regulatoryagency[eu]"/> D. h. ausgehend vom Element regulatorypermitidentification, in das der Wert eingetragen wird, muss im Elementbaum nach oben navigiert werden. Im vorliegenden Beispiel (../../) wird also im Elementbaum zwei Ebenen nach oben zu tradeitemregulatoryinformation navigiert. In die hierunter befindlichen Elemente regulatoryact und regulatoryagency sind dann die in eckigen Klammern angegebenen Werte einzutragen. In anderen Fällen wird ohne Angabe eines einzutragenden Wertes auf weitere Elemente im XML referenziert. D. h. hier ist dann ein gültiger Wert für das betreffende Element einzutragen. Für das oben angegebene Beispiel ergibt sich damit für das resultierende XML folgende Struktur. Für die Nutzdaten wurden die Datenelementnamen aus dem Zielprofil eingetragen:... <tradeitemregulatoryinformation> <regulatoryact>834_2007_class</regulatoryact> <regulatoryagency>eu</regulatoryagency> <permitidentification> <regulatorypermitidentification> Ökologisches Produkt: Ökologische Herkunft</regulatoryPermitIdentification> </permitidentification> </tradeitemregulatoryinformation> <tradeitemregulatoryinformation> <regulatoryact>834_2007_certification</regulatoryact> <regulatoryagency>eu</regulatoryagency> <permitidentification> <regulatorypermitidentification> Ökologisches Produkt: Bio-Kontrollstelle </regulatorypermitidentification> </permitidentification> </tradeitemregulatoryinformation> 1WorldSync GmbH, Köln 2014 Seite 7

10 Weitergehende Informationen Wiederholbarkeiten In den Schemadefinitionen des Subsets wurden grundsätzlich die Wiederholbarkeiten aus der GS1 GDSN XML Schemadefinition übernommen. In verschiedenen Fällen erlaubt die Zielmarktspezifikation nur die Übermittlung eines einzelnen Wertes. Diese Regeln sind der fachlichen Dokumentation zu entnehmen. Implizit vorausgesetzte Angaben Standardmäßig vorkommende Abhängigkeiten wie insbesondere bei sprachabhängigen Attributen und physikalischen Messwerten werden nicht explizit dokumentiert. Die jeweilige Abhängigkeit ergibt sich in diesen Fällen bereits aus der Schemadefinition. Desgleichen werden die zu verwendenden Codelisten nicht im Einzelfall erwähnt. Die gültigen Ausprägungen ggf. in Abhängigkeit vom konkreten Datenelement sind der Profiles Overview / Codelisten Kompendium zu entnehmen. Verweise auf spezielle Typen und Codelisten Wenn für die Zielmarktprofile spezielle Codelisten verwendet werden, so werden diese im appinfo Element der Dokumentation in einem Elementpaar kenntlich gemacht: <communityformat>codelist</communityformat> <communitycodelistname>featurebenefit</communitycodelistname> Der im Element communitycodelistname angegebene Verweis entspricht dem Codelistennamen in der Profiles Overview / Codelisten Kompendium. Das Element communityformat wird darüber hinaus durchgängig in der Dokumentation zur AVP-Extension genutzt. Werte, die via AVP-Extension übermittelt werden, werden dort im Element value übertragen, welches im GS1 GDSN XML den Datentyp string hat. Im Rahmen der Zielmarktprofile werden via AV-Pair aber auch numerische Werte übertragen bzw. im Rahmen künftiger Erweiterungen könnten auch Datums- oder Datum/Zeit-Werte übertragen werden. In diesen Fällen müssen die eingetragenen Werte mit den hierfür im XML Standard vorgesehenen Zeichen getrennt und korrekt formatiert werden. Ansonsten ist eine Verarbeitung der Daten nicht gewährleistet bzw. wird eine Fehlermeldung verursachen. communityformat Werte / Trennzeichen Beispiel String Alle UTF-8 Zeichen Integer Ganzzahlen ohne Trennzeichen Decimal Dezimalzahlen / Dezimalpunkt Date Datum (YYYY-MM-DD) / Bindestrich Datetime Datum-Zeit (YYYY-MM-DDThh:mm:ss) T09:30:47 Codelist Codelistenwerte gem. Profiles Overview / Codelisten Kompendium 1WorldSync GmbH, Köln 2014 Seite 8

11 Verwendung von XML Choice Elementen Abweichend von der GS1 GDSN XML Definition wurden in verschiedenen Fällen anstelle der normalen sequence zusätzliche choice Elemente eingefügt. Hiermit soll herausgestellt werden, dass die betroffenen Datenelemente in diesen Fällen in einer eigenen Wiederholung in der dargestellten Form übermittelt werden sollen. Die gemeinsame Übermittlung in einer Wiederholung obwohl gemäß GS1 GDSN XML zulässig - kann ggf. zu Verarbeitungsproblemen führen und sollte daher vermieden werden. Beispiel: DangerousSubstanceInformation Abbildung 2: DangerousSubstanceInformation - Verwendung von choice D. h. sollen Gefahrstoffangaben und gleichzeitig Angaben zu Brennbaren Stoffen übermittelt werden, so sollten die Gefahrstoffangaben in einer Wiederholung zusammengefasst werden. Für jeden einzelnen durch dangeroussubstancename identifizierten brennbaren Stoff sind dann weitere Wiederholungen bestehend aus dangeroussubstancename und der flammablesubstanceinformation zu liefern. 1WorldSync GmbH, Köln 2014 Seite 9

12 Änderungshistorie dieser Dokumentation Datum Kapitel (Datenelement), Seite Änderung / Erweiterung / Neuerung Version 0.91 Erstveröffentlichung Version 1.0 veröffentlicht am Version Anpassungen der Schemavorgaben GDSN Core Alter der Zielgruppe: Sprache Default-Wert Vorgabe (en) für die Sprache entfernt Attribute-Value Pair Extension Neue Attribute in der Attribute Value Pair Extension: numberofservingsrangedescription partyreceivingprivatedata1 sequenceofingredientemphasised Attributnamen entfernt breadunit Anpassung von AV-Pair Namen an den GDSN Standard recommendedareaofconsumerpickupcode ersetzt recommendedareaofconsumerpickup packagingmarkedlabelaccreditationcode ersetzt packagingmarkslabelaccreditation 1WorldSync GmbH, Köln 2014 Seite 10