EdiStandardXml < Cargooffice

---+!! XML Edi formatting

%TOC%

---++ Standard XML format

There is a separation of order, shipment and goods fields in this format.<br /> <br /> The XML tends to be self explanatory:
<verbatim>
<orders> contains one or more orders
    <shipments> containing one or more shipments
       <goods> contains one or more goods lines</verbatim>

---+++ XML version 3.0 example:
   * <a href="http://twiki.cargooffice.com/pub/Cargooffice/EdiStandardXml/transportOrderXMLv30.xml" target="_blank" title="XML v3.0">Our example file for version 3.0</a>.
---+++ XML version 4.0 example:
   * <a href="http://twiki.cargooffice.com/pub/Cargooffice/EdiStandardXml/transportOrderXMLv40xml.txt" target="_blank" title="XML v4.0">Our example file for version 4.0</a>.
A complete list of field names can be found here: [[TransportorderFields][Transport order fields]].

---++ Special XML format

Special XML formats need a little bit of configuration to map the XML tags to the relevant cargooffice fields.

In your backoffice you find three types of parameters: !ShipmentTags, !GoodsTags and !ExtraTags.

These parameter names need to be prefixed by the name of the root tag, for example:

   * !ordersShipmentTags
   * !ordersGoodsTags
   * !ordersExtraTags
If the root tag is named &lt;orders&gt;.

---+++ parameter 'ordersShipmentTags' (example)
<verbatim>
   ORNERNODE=shipment
   pickupName=From_name
   pickupstreet=From_street
   pickuphousenumber=From_housenumber
   pickupCity=From_city
   pickupCountry=From_country
   pickupDate=From_date
   deliveryName=To_name
   deliverystreet=To_street
   deliveryhousenumber=To_housenumber
   deliveryCity=To_city
   deliveryCountry=To_country
   deliveryDate=To_date
   shipmenttype=shipment_type</verbatim>

---+++ parameter 'ordersGoodsTags' (example)
<verbatim>
   GOODSNODE=goodsPackages/goodsPackage
   goodsDescription=description
   quantity=number_of_items
   packing=emballageparamname: example_ordersExtraTags</verbatim>

---+++ parameter 'ordersExtraTags' (example)
<verbatim>
   shipmentID=FUNCTION(uniquenum)
   pickupAddress=FUNCTION(concatenate,pickupstreet," ",pickuphousenumber)
   pickupDate=FUNCTION(dateformat,pickupDate,DD-MM-YYYY,YYYYMMDD)
   deliveryDate=FUNCTION(dateformat,deliveryDate,DD-MM-YYYY,YYYYMMDD)
   deliveryAddress=FUNCTION(concatenate,deliverystreet," ",deliveryhousenumber)
   quantity=FUNCTION(totalizegoods,quantity)
   weight=FUNCTION(totalizegoods,weight)
   pallets=FUNCTION(totalizegoods,pallets)
   orderType=IF(shipmenttype="A","Binnen een dag")
   status=FUNCTION(check_statusdate,status,stdedibulk)</verbatim>

---+++ Explanation

The *ShipmentTags* and *GoodsTags* parameters contain the cargooffice field names (data_store_tags) and a corresponding xpath expression referencing 1 or more sections in the input XML. The format is:

=data_store_tag = xpath_expression_to_a_specific_node (relative to ORDERNODE)=

For a list of data_store_tags see: TransportorderFields

The *ExtraTags* parameter allows you to set values for fields which can not be found in the input XML and even the posibility to call a number of FUNCTIONs to manipulate data. See section *ExtraTags* fundtions below.

---+++ Operational Settings

ORDERNODE is a so called *Operational Setting*. Operational Settings are always in uppercase, in this case it defines the tag where a new order begins. If it is not present then the document is assumed to contain just 1 order.

| ORDERNODE | Defines an absolute xpath expression to order nodes in the xml document. If not present , the docroot is assumed to contain 1 order. |
| GOODSNODE | defines an xpath expression to goods nodes in the document. If not present , the docroot is assumed to contain 1 goods node. |
| ALL | Relative to ORDERNODE or GOODSNODE it defines and xpath expression to all order nodes, node name will be used as datastore tag name (optional). |
| ALLNAMES | Defines and attribute that will be used as datastore tag name, if the attribute is empty or absent, the nodename will be used instead (optional). |

---+++ Funtions

The *ExtraTags* parameter allows to set or modify values for cargooffice data_store_tags even if there is no correspondant node values from the input XML assigned.

The left value is always the name of a cargooffice field (a data_store_tag). The value on the right of the equal (=) sign can be:

   * a literal string <br />format: <br /> =data_store_tag=some text=
   * a function whos output will be written to the tag on the right <br />format: <br /> =data_store_tag=FUNCTION(functionname,argument1,argument2,...)=
   * a conditional statement <br />format: <br /> =data_store_tag=IF(data_store_tag=literal or data_store_tag;function or literal;else function or literal)=

| FUNCTIONS ||
| concatenate | concatenate(data_store_tag or literal,...)<br />concatenates the content of already existing data store tags and literals (delimited by "")<br />will be called as: data_store_tag=FUNCTION(concatenate,argument1,...) |
| dateformat | dateformat(data_store_tag,inputformat[, outputformat])<br />reformates an input date string (arg1), formatted as defined in inputformat (arg2), to the format defined in (optional) output format (arg3), default being 'DD-MM-YY'.<br />Will be called as:data_store_tag=FUNCTION(dateformat,inputformat[, outputformat)<br />whereby input and output formats contain a combination of the letters D(ay), M(onth), Y(ear) and literal division signs |
| sub_string | sub_string(data_store_tag ,start[,length])<br />outputs a substring as defined by the arguments<br />will be called as:data_store_tag=FUNCTION(sub_string,start[,length]) |
| check_statusdate | check_statusdate(data_store_tag containing the status, statusstring to insert if status is not found)<br />Checks if a status string is forwarded in the data_store_tag specified in arg1, and if the string contains a date/time stamp. If its empty, the status string fronm arg2 (a litteral) is used. If no date time stamp is present , it is added.<br />will be called as:data_store_tag=FUNCTION(check_statusdate,data_store_tag,defaultstatus) |
| totalizegoods | totalizegoods(data_store_tag in the goods section)<br />Totalizes the values found in the goodstag (arg1) for all goodslines. Naturally, arg1 will NOT contain the sequence number of the goods section.<br />Will be called as: data_store_tag=FUNCTION(totalizegoods,data_store_tag in goods section&gt;) |
| maketimestamp | maketimestamp()<br />Return a timestamp of the current time in format YYYY-MM-DD HH:MM.<br />Will be called as: data_store_tag=FUNCTION(maketimestamp) |
| uniquenum | uniquenum()<br />Return a fance unique number made up out of element from a microtime timestamp.<br />Will be called as: data_store_tag=FUNCTION(uniquenum) |

---+++ XML input file EXAMPLES:

---++++ a simple xml whereby fields are selectively translated

input XML:
<verbatim>
<example_orders>
   <shipment>
      <From_name>A. de Vries</From_name>
      <From_street>Hoofdstraat</From_street>
      <From_housenumber>1</From_housenumber>
      <From_city>Driekerken aan de Rijn</From_city>
      <From_country>Nederland</From_country>
      <From_date>21-06-2008</From_date>
      <To_name>B. de Boer</To_name>
      <To_street>Zijstraat</To_street>
      <To_housenumber>2</To_housenumber>
      <To_city>Eenhuizen</To_city>
      <To_country>Nederland</To_country>
      <To_date>21-06-2008</To_date>
      <shipment_type>A</shipment_type>
      <goodsPackages>
          <goodsPackage>
              <description>Tulpenbollen</description>
              <number_of_items>250</number_of_items>
              <emballage>doosjes</doosjes>
              <pallets>3</pallets>
              <weight>960</weight>
          </goodsPackage>
          <goodsPackage>
              <description>Boterkoek</description>
              <number_of_items>45</number_of_items>
              <emballage>kartons</emballage>
              <pallets>12</pallets>
              <weight>450</weight>
          </goodsPackage>
      <goodsPackages>
   </shipment>
</example_orders></verbatim>

---++++ parameters

paramname: *example_ordersShipmentTags*

param content:

<verbatim>
ORNERNODE=shipment
pickupName=From_name
pickupstreet=From_street
pickuphousenumber=From_housenumber
pickupCity=From_city
pickupCountry=From_country
pickupDate=From_date
deliveryName=To_name
deliverystreet=To_street
deliveryhousenumber=To_housenumber
deliveryCity=To_city
deliveryCountry=To_country
deliveryDate=To_date
shipmenttype=shipment_type</verbatim>

paramname: *example_ordersGoodsTags*

param content:

<verbatim>
GOODSNODE=goodsPackages/goodsPackage
goodsDescription=description
quantity=number_of_items
packing=emballageparamname: example_ordersExtraTags</verbatim>

paramname: *example_extraGoodsTags*

param content:

<verbatim>
shipmentID=FUNCTION(uniquenum)
customerID=3800
pickupAddress=FUNCTION(concatenate,pickupstreet," ",pickuphousenumber)
pickupDate=FUNCTION(dateformat,pickupDate,DD-MM-YYYY,YYYYMMDD)
deliveryAddress=FUNCTION(concatenate,deliverystreet," ",deliveryhousenumber)
deliveryDate=FUNCTION(dateformat,deliveryDate,DD-MM-YYYY,YYYYMMDD)
quantity=FUNCTION(totalizegoods,quantity)
weight=FUNCTION(totalizegoods,weight)
pallets=FUNCTION(totalizegoods,pallets)
orderType=IF(shipmenttype="A","Binnen een dag")
status=FUNCTION(check_statusdate,status,stdedibulk)</verbatim>

---++++ cargooffice Data Storage output:
<verbatim>
<!-- Start order
shipmentID: 235345334635
pickupName: A. de Vries
pickupstreet: Hoofdstraat
pichuphousenumber: 1
pickupAddress: Hoofdstraat 1
pickupCity: Driekerken aan de Rijn
pickupCountry: Nederland
pickupDate: 20080621
deliveryName: B. de Boer
deliverystreet: Zijstraat
deliveryhousenumber: 2
deliveryAddress: Zijstraat 2
deliveryCity: Eenhuizen
deliveryCountry: Nederland
deliveryDate: 20080621
oderType: Binnen een dag
goodsDescription1: Tulpenbollen
quantity1: 250
packing1: doosjes
pallets1: 5
weight1: 500
goodsDescription2: Augurken
quantity2: 320
packaging2: vatten
pallets2: 3
weight2: 960
goodsDescription3: Boterkoek
quantity3: 45
packaging3: kartons
pallets3: 12
weight3: 450
quantity: 615
pallets: 20
weight: 1910
status: +2008-06-20 stdedibulk
--></verbatim>

---++++ an xml where we will use the tagnames as data store field names

input XML:

<verbatim>
<xmlEdi>
   <header>
      <type>transportorderXML</type>
      <version>3.0</version>
      <userID>test@test.com</userID>
      <passwd>acceptAny</passwd>
   </header>
   <transportOrders>
      <transportOrder>
         <orderHead>
            <CN>7267</CN>
            <customerID>355400</customerID>
            <orderReference>ELC220906</orderReference>
         </orderHead>
         <shipments>
            <shipment>
               <shipmentID>01489830</shipmentID>
               <pickupName>PHILIPS ELECTRONICS</pickupName>
               <pickupAddress>MAINROAD 24</pickupAddress>
               <pickupPostcode>7418 EV</pickupPostcode>
               <pickupCity>DEVENTER</pickupCity>
               <pickupCountry>Nederland</pickupCountry>
               <pickupDate>23-09-03</pickupDate>
               <deliveryName>HEMA WINKELS</deliveryName>
               <deliveryAddress>SHOPPINGMALL 2</deliveryAddress>
               <deliveryPostcode>4271 CZ</deliveryPostcode>
               <deliveryCity>UTRECHT</deliveryCity>
               <deliveryCountry>Nederland</deliveryCountry>
               <deliveryDate>24-09-03</deliveryDate>
               <deliveryType>Normale levering</deliveryType>
               <goodsLines>
                  <goodsLine>
                     <quantity>10</quantity>
                     <packing>carton</packing>
                     <goodsID>electronic equipment</goodsID>
                     <weight>525</weight>
                     <pallets>1</pallets>
                  </goodsLine>
                  <goodsLine>
                     <quantity>12</quantity>
                     <packing>box</packing>
                     <goodsID>wiring</goodsID>
                     <weight>207</weight>
                     <pallets>1</pallets>
                     <palletID>euro</palletID>
                  </goodsLine>
               </goodsLines>
            </shipment>
         </shipments>
      </transportOrder>
   </transportOrders>
</xmlEdi></verbatim>

alternate version will also work

<verbatim>
<xmlEdi>
   <header>
      <headField name="type">transportorderXML</headField>
      <headField name="version">2.1</headField>
      <headField name="userID">test@test.com</headField>
      <headField name="passwd">acceptAny</headField>
   </header>
   <transportOrders>
      <transportOrder>
         <orderHead>
            <orderField name="CN">7267</orderField>
            <orderField name="customerID">355400</orderField>
            <orderField name="orderReference">ELC220906</orderField>
         </orderHead>
         <shipments>
            <shipment>
               <shipField name="shipmentID">01489830</shipField>
               <shipField name="pickupName">PHILIPS ELECTRONICS</shipField>
               <shipField name="pickupAddress">MAINROAD 24</shipField>
               <shipField name="pickupPostcode">7418 EV</shipField>
               <shipField name="pickupCity">DEVENTER</shipField>
               <shipField name="pickupCountry">Nederland</shipField>
               <shipField name="pickupDate">23-09-03</shipField>
               <shipField name="deliveryName">HEMA WINKELS</shipField>
               <shipField name="deliveryAddress">SHOPPINGMALL 2</shipField>
               <shipField name="deliveryPostcode">4271 CZ</shipField>
               <shipField name="deliveryCity">UTRECHT</shipField>
               <shipField name="deliveryCountry">Nederland</shipField>
               <shipField name="deliveryDate">24-09-03</shipField>
               <shipField name="deliveryType">Normale levering</shipField>               <goodsLines>
                  <goodsLine>
                     <goodsField name="quantity">10</goodsField>
                     <goodsField name="packing">carton</goodsField>
                     <goodsField name="goodsID">electronic equipment</goodsField>
                     <goodsField name="weight">525</goodsField>
                     <goodsField name="pallets">1</goodsField>
                     <goodsField name="palletID">euro</goodsField>
                  </goodsLine>
                  <goodsLine>
                     <goodsField name="quantity">12</goodsField>
                     <goodsField name="packing">box</goodsField>
                     <goodsField name="goodsID">wiring</goodsField>
                     <goodsField name="weight">207</goodsField>
                     <goodsField name="pallets">1</goodsField>
                     <goodsField name="palletID">euro</goodsField>
                  </goodsLine>
               </goodsLines>
            </shipment>
         </shipments>
      </transportOrder>
   </transportOrders>
</xmlEdi></verbatim>

---++++ parameters

param name: *xmlEdiShipmentTags*

param content:

<verbatim>
ORDERNODE=transportOrders/transportOrder
ALL=.//orderHead/*|.//shipment/*
ALLNAMES=name</verbatim>

param name: *xmlEdiGoodsTags*

param content:

<verbatim>
GOODSNODE=shipments/shipment/goodsLines/goodsLine
ALL=*
ALLNAMES=name</verbatim>

param name: *xmlEdiExtraTags*

param content:

<verbatim>
status=FUNCTION(check_statusdate,status,stdedibulk)
weight=FUNCTION(totalizegoods,weight)
quantity=FUNCTION(totalizegoods,quantity)
volume=FUNCTION(totalizegoods,volume)
pallets=FUNCTION(totalizegoods,pallets)
loadmeters=FUNCTION(totalizegoods,loadmeters)
quantityPick=FUNCTION(totalizegoods,quantityPick)</verbatim>

---++++ cargoofice Data Storage output:
<verbatim>
<!-- Start Order
CN: 7267
customerID: 355400
orderReference: ELC220906
shipmentID: 01489830
pickupName: PHILIPS ELECTRONICS
pickupAddress: MAINROAD 24
pickupPostcode: 7418 EV
pickupCity: DEVENTER
pickupCountry: Nederland
pickupDate: 23-09-03
deliveryName: HEMA WINKELS
deliveryAddress: SHOPPINGMALL 2
deliveryPostcode: 4271 CZ
deliveryCity: UTRECHT
deliveryCountry: Nederland
deliveryDate: 24-09-03
deliveryType: Normale levering
quantity1: 10
packing1: carton
goodsID1: electronic equipment
weight1: 525
pallets1: 1
palletID1: euro
quantity2: 12
packing2: box
goodsID2: wiring
weight2: 207
pallets2: 1
palletID2: euro
nofGoodslines: 3
status: +2008-07-03 17:06 stdedibulk
weight: 732
quantity: 22
pallets: 2
--></verbatim>
---++ Updates of order status.

Order statuses [[EdiStatusUpdates][can be changed]] via EDI.

<br /><br /> -- Main.KarlGorz - 7 Jul 2008 / 2015-02-16 <a href="http://twiki.cargooffice.com/bin/edit/Cargooffice/EdiStandardXml?t=1424088643;nowysiwyg=1" target="_top">-</a> Main.RutgerRutgers
Attachments
Topic attachments
I	Attachment	History	Action	Size	Date	Who	Comment
xml	transportOrderXMLv30.xml	r1	manage	2.0 K	2015-02-16 - 11:57	RutgerRutgers	example XML v3.0
txt	transportOrderXMLv40xml.txt	r1	manage	2.1 K	2015-02-16 - 12:02	RutgerRutgers	example XML v4.0
This topic: Cargooffice > AboutFreecargo > FreightExchangeHowto > WebHome > EdiDocumentation > EdiHowto > EdiStandardXml
Topic revision: r9 - 2015-02-16 - RutgerRutgers