Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/riege/one-record-converter

Cargo-XML XFWB/XFZB to ONE Record Converter
https://github.com/riege/one-record-converter

java library onerecord

Last synced: 2 months ago
JSON representation

Cargo-XML XFWB/XFZB to ONE Record Converter

Awesome Lists containing this project

README 

        
# Cargo-XML XFWB / XFZB to ONE Record Converter

Note: A live demo of this converter is available at https://onerecord.riege.com/



## Release versioning and IATA Ontology versions



The IATA Ontology version is reflected by the version of the Riege [one-record-ontologymodel library](https://github.com/riege/one-record-ontologymodel).



It is highly recommended to use converter library 2.1 / Ontology version 2.1 or younger for 

converting XFWB or XFZB to ONE Record. Note IATA Ontology version 2.0 added major improvements for 

eAWB data fields.



Versions of the converter library:

* 2.1.x / `branch_2.1`: based upon IATA Ontology 2.1, the ONE Record datamodel as per December 2022, see https://github.com/IATA-Cargo/ONE-Record/tree/master/December-2022-standard

  
Uses one-record-ontologydatamodel version **0.2.x**

* 1.0.x / `branch_1.0`: based upon IATA Ontology 2.0, the ONE Record datamodel as per May 2022, see https://github.com/IATA-Cargo/ONE-Record/tree/master/May-2022-standard-COTB-endorsed.

  
Uses one-record-ontologymodel version **2.0.x**

* 0.9.x / `branch_0.9`: based upon IATA Ontology 1.1, the ONE Record datamodel as per June 2021, see https://github.com/IATA-Cargo/ONE-Record/tree/master/June-2021-standard-COTB-endorsed.

  
Uses one-record-ontologymodel version **1.1.x**

* current development / `main`: based on IATA ONE Record datamodel working draft, see https://github.com/IATA-Cargo/ONE-Record/tree/master/working_draft/ontology



## General Backgound Information

This converter intentionally does neither set IDs nor makes use of persisted data for linked-data purposes.



The converter is based on two main data structures to convert from Cargo-XML to ONE Record:



* For parsing Cargo-XML the converter uses Java classes which had been generated from the 

  Cargo-XML schema. These generated classes are included via library

  https://github.com/riege/cargoxml-jaxb.

  Please note that the cargoxml-jaxb package does not contain any schema information from the IATA Cargo-XML

  Toolkit.

  Please also note that the schema information from 

  the _IATA Cargo-XML Toolkit_ is published on 

  the _IATA Cargo-XML validation portal_ available at

  https://cargo-xml-autocheck.iata.org/Docs/IATA/XML%20Waybill%20Message%20XFWB%203.00/011.htm

* For generating ONE Record Logistics Object structures, IATA provides Java classes 

  in project https://github.com/IATA-Cargo/one-record-server-java 

  (see https://github.com/IATA-Cargo/one-record-server-java/tree/master/src/main/generated-sources/org/iata/cargo).

  These classes have been updated with recently IATA endorsed Ontology via the project 

  https://github.com/riege/one-record-ontologymodel which is used by this converter.



Codes and units are copied 1:1 from the provided Cargo-XML message where applicable.



Line breaks are respected for some fields if provided in XML, e.g. for multi-line goods description or address name/street. Line breaks are intentionally used in GoodsDescription to preserve and indicate descriptions from more than one field if applicaple from original XML



Version 0.9 is limited to map the Cargo-XML XFWB3 message to ONE Record JSON.

Version 1.0 adds a basic mapping for the Cargo-XML XFZB3 message.

Please note that the 1R converter is not mapping all possible data yet and has focus on the use-case 'message from a forwarder to an airline'.



## Usage



### Programming 



#### XFWB

The main Cargo-XML class for XFWB3 is `com.riege.cargoxml.schema.xfwb3.WaybillType`.



The `com.riege.onerecord.converter.XFWB3toOneRecordConverter` converts a provided 

Cargo-XML XFWB `WaybillType`

into validation results plus hints and especially into ONE Record logistics data model

`org.iata.cargo.model.Waybill`:



    InputStream is = ...

    WaybillType xfwb = new ConverterUtil().unmarshalXFWB3(is);

    XFWB3toOneRecordConverter converter = new XFWB3toOneRecordConverter(xfwb);

    for (ValidationMessage msg : converter.getValidationHints()) {

        System.out.println("HINT: " + msg.getMessage());

    }

    for (ValidationMessage msg : converter.getValidationWarnings()) {

        System.out.println("WARNING: " + msg.getMessage());

    }

    for (ValidationMessage msg : converter.getValidationErrors()) {

        System.out.println("ERROR: " + msg.getMessage());

    }

    Waybill oneRecordWaybill = converter.getOneRecordResult();



The `Waybill` can be serialized easily into JSON, e.g. with https://github.com/FasterXML/jackson



#### XFZB

For XFZB3, the main Cargo-XML class is `com.riege.cargoxml.schema.xfzb3.HouseWaybillType`.



The `com.riege.onerecord.converter.XFZB3toOneRecordConverter` converts in a similar way

from `HouseWaybillType` into `org.iata.cargo.model.Waybill`.



### Library usage

The converter library is not published on mavenCentral (yet).



Nevertheless releases are available for download at https://github.com/riege/one-record-converter/releases 

and it can be also integrated into a Java project as a depencency via https://jitpack.io/#riege/one-record-converter:



[gradle](https://gradle.org/):



    repositories {

      ...

      maven { url 'https://jitpack.io' }

    }



    dependencies {

      implementation 'com.github.riege:one-record-converter:1.0.+'

    }



[maven](https://maven.apache.org):



    

      com.github.riege

      one-record-converter

      1.0.2

    



See https://jitpack.io/#riege/one-record-converter for more details.



### Java version

**Update for version 0.9 and above**: The one-record-converter published jar includes 

the required Ontologymodel classes, Cargo-XML JAXB classes as well as 

`jakarta.xml.bind-api` and `jaxb-impl` classes. 



**Only for version 0.8 and older**:

The converter uses Jakarta XML Binding (JAXB), which was part of 

the Java Enterprise Edition with Java version 8,

deprecated in the following Java versions and finally removed in Java 11.



When this library is used with Java 11 or younger, a dependency needs to be added,

e.g. for Java EE 8, in use with maven:



    

      jakarta.xml.bind

      jakarta.xml.bind-api

      2.3.3

    

    

      com.sun.xml.bind

      jaxb-impl

      2.3.5

      runtime