Converter Scripts

With help of the integrated Template-Engine Smarty can flexibly adapt character-based output structures of data formats such as CSV, XML or JSON to the customer's needs. All that is required is to copy the existing target format into a text file and fill it with the appropriate variables. These can still be reformatted in the process.

Document data is located e.g. in the smarty variable $beleg and is addressed in the usual PHP object notation, e.g. $beleg->customer number or $beleg->belegnr. The naming is similar to the naming of database column names. Access to more complex structures is also possible depending on the document. So in the delivery bill the underlying order can be accessed: $voucher->order->delivery date.

Shortened example with fictitious format

<?xml version="1.0" encoding="utf-8"?>
<lieferschein>

         {* Beleg-Stammdaten -------------------------------- *} 
         <status>{$beleg->status}</status>
         <datum>{$beleg->datum|date_format:'%d.%m.%Y'}</datum>
         <belegnummer>{$beleg->belegnr}</belegnr>
         <kundennummer>{$beleg->kundennummer}</kundennummer>
         <kundenname>{$beleg->name}</kundenname>

         {* Zugriff auf Daten des zugrundeliegenden Auftrages *} 
         <lieferdatum>{$beleg->auftrag->lieferdatum}</lieferdatum>
         {* Weitere Felder entfernt *} 

         {* Positionen - Beginn ------------------------------ *} 
         <positionen>

                {* Schleife durchläuft alle verfügbaren Positionen *} 
                {foreach from=$beleg->positionen key=keypos item=position}
                <position>
                        <artikelnummer>{$position->nummer}</artikelnummer>
                        <artikelbezeichnung>{$position->bezeichnung}</artikelbezeichnung>
                        <artikelbeschreibung>{$position->beschreibung}</artikelbeschreibung>
                        <menge>{$position->menge}</menge>
                        <preis>{$position->preis}</preis>
                        <ean>{$position->articledata->ean}</ean>
                        {* Weitere Felder entfernt *} 
                 </position>
                {/foreach}

        </positionen>
        {* Positionen - Ende -------------------------------- *} 
</lieferschein>

Beyond the transmitted data, additional data, e.g. from the article master data, can also be accessed. These can be referenced via the object articledata, as represented by the EAN in the above example. All columns of the article table can be accessed via this notation, e.g. also the free fields of the article, which may be assigned with other values in the order itself.

The following is a summary of some examples that enable the output of various delivery note formats in EDI, CSV and XML formats. The column labels (CSV), tag names (XML) and EDI specifications are to be checked. Other output formats such as JSON are conceivable.

- wird ergänzt -

{foreach from=$beleg->positionen key=keyrow item=position}{* Positionen *}\
"{$position->tracking}";\
"{$beleg->status}";\
"{$beleg->datum|date_format:'%d.%m.%Y'}";\
"{$beleg->lieferdatum}";\
"{$beleg->tatsaechlicheslieferdatum}";\
"{$beleg->versandart}";\
"{$beleg->zahlungsweise}";\
"{$beleg->belegnr}";\
"{$beleg->hauptbelegnr}";\
"{$beleg->kundennummer}";\
"{$beleg->name}";\
"{$beleg->abteilung}";\
"{$beleg->unterabteilung}";\
"{$beleg->adresszusatz}";\
"{$beleg->ansprechpartner}";\
"{$beleg->telefon}";\
"{$beleg->email}";\
"{$beleg->land}";\
"{$beleg->strasse}";\
"{$beleg->plz}";\
"{$beleg->ort}";\
"{$beleg->projekt}";\
"{$beleg->aktion}";\
"{$beleg->internebemerkung}";\
"{$beleg->internebezeichnung}";\
"{$beleg->freitext}";\
"{$beleg->ihrebestellnummer}";\
"{$beleg->lieferbedingung}";\
"{$beleg->art}";\
"{$position->nummer}";\
"{$position->bezeichnung}";\
"{$position->beschreibung}";\
"{$position->menge|string_format:'%.2f'}";\
"{$position->preis}";\
"{$position->rabatt}";\
"{$position->waehrung}";\
"{$position->lieferdatum}";\
"{$position->sort}";\
"{$position->umsatzsteuer}";\
"{$position->einheit}";\
"{$position->zolltarifnummer}";\
"{$position->herkunftsland}";\
"{$position->artikelnummerkunde}";\
"{$beleg->auftrag->lieferdatum}";\
"{$position->freifeld1}";\
"{$position->freifeld2}";\
"{$position->freifeld3}";\
{* Ggf. weitere Freifelder *}";\
"{$position->freifeld40}";\

{/foreach}

<?xml version="1.0" encoding="utf-8"?>
<lieferschein>

        <status>{$beleg->status}</status>
        <datum>{$beleg->datum|date_format:'%d.%m.%Y'}</datum>
        <lieferdatum>{$beleg->lieferdatum}</lieferdatum>
        <tatsaechlicheslieferdatum>{$beleg->tatsaechlicheslieferdatum}</tatsaechlicheslieferdatum>
        <versandart>{$beleg->versandart}</versandart>
        <zahlungsweise>{$beleg->zahlungsweise}</zahlungsweise>
        <belegnr>{$beleg->belegnr}</belegnr>
        <hauptbelegnr>{$beleg->hauptbelegnr}</hauptbelegnr>
        <kundennummer>{$beleg->kundennummer}</kundennummer>
        <name>{$beleg->name}</name>
        <abteilung>{$beleg->abteilung}</abteilung>
        <unterabteilung>{$beleg->unterabteilung}</unterabteilung>
        <adresszusatz>{$beleg->adresszusatz}</adresszusatz>
        <ansprechpartner>{$beleg->ansprechpartner}</ansprechpartner>
        <telefon>{$beleg->telefon}</telefon>
        <email>{$beleg->email}</email>
        <land>{$beleg->land}</land>
        <strasse>{$beleg->strasse}</strasse>
        <plz>{$beleg->plz}</plz>
        <ort>{$beleg->ort}</ort>
        <projekt>{$beleg->projekt}</projekt>
        <aktion>{$beleg->aktion}</aktion>
        <internebemerkung>{$beleg->internebemerkung}</internebemerkung>
        <internebezeichnung>{$beleg->internebezeichnung}</internebezeichnung>
        <freitext>{$beleg->freitext}</freitext>
        <ihrebestellnummer>{$beleg->ihrebestellnummer}</ihrebestellnummer>
        <lieferbedingung>{$beleg->lieferbedingung}</lieferbedingung>
        <art>{$beleg->art}</art>
        <positionen>

        {foreach from=$beleg->positionen key=keypos item=position}
                <position>
                <nummer>{$position->nummer}</nummer>
                <bezeichnung>{$position->bezeichnung}</bezeichnung>
                <beschreibung>{$position->beschreibung}</beschreibung>
                <menge>{$position->menge}</menge>
                <preis>{$position->preis}</preis>
                <rabatt>{$position->rabatt}</rabatt>
                <waehrung>{$position->waehrung}</waehrung>
                <lieferdatum>{$position->lieferdatum}</lieferdatum>
                <sort>{$position->sort}</sort>
                <umsatzsteuer>{$position->umsatzsteuer}</umsatzsteuer>
                <einheit>{$position->einheit}</einheit>
                <zolltarifnummer>{$position->zolltarifnummer}</zolltarifnummer>
                <herkunftsland>{$position->herkunftsland}</herkunftsland>
                <artikelnummerkunde>{$position->artikelnummerkunde}</artikelnummerkunde>
                <freifeld1>{$position->freifeld1}</freifeld1>
                <freifeld2>{$position->freifeld2}</freifeld2>
                <freifeld3>{$position->freifeld3}</freifeld3>
                {* Ggf. weitere Freifelder *} 
                <freifeld40>{$position->freifeld40}</freifeld40>
        </position>
 {/foreach}

        </positionen>
        {if $beleg->versand}
{foreach from=$beleg->versand key=keyversand item=tracking} {* Versand *}
        <tracking>{$tracking->tracking}</tracking>
{/foreach}
{/if}
</lieferschein>

- wird ergänzt -

- wird ergänzt -

- wird ergänzt -

- wird ergänzt -

- wird ergänzt -

- wird ergänzt -

- wird ergänzt -

- wird ergänzt -

- wird ergänzt -

At xentral, great importance is attached to the connection as well as the automatic processing of orders in online stores. Therefore xentral offers interfaces to various stores. Although almost every store has an interface, sometimes problems with the compatibility of the interfaces to be connected occur. An importer, which serves as an adapter between xentral and the online stores interface, can be developed. This acts as middleware and translates the data of the orders from the store into a format from which xentral can in turn create orders. Conversely, the importer is also responsible for transferring the order status, item data and stock figures to the store.

The process within the importer always follows a fixed pattern. If, for example, orders are to be collected from the store, the system first checks whether there is a connection to the store interface. Then it is determined whether or how many orders are to be collected from the store. If there are orders to be picked up, they are imported and then marked as "In process" in the store. When items are imported from or exported to the store, a similar scheme applies. First, a check is made to see if there is a connection between xentral and the store, then the data is transferred.

It is necessary to follow the given structure when writing an importer. Some points must be specified in advance:

All requirements must be met: First, the ImportAuth() function must be used. In the external importer this function is necessary for authentication from xentral to the importer, in internal importers the function checks the connection call to the API. Since this function is called every time the importer is to be put into action, there is an underlying request or mechanism here to create a token. The important thing here is to return success to indicate that the importer is ready to accept instructions and pass them on to the Shop API.

public function ImportAuth()
{
        $params = ['limit' => 1];
        $responseJson  =$this->call('articles','GET',null, $params);
        $response = json_decode($responseJson,true);

        if($response['success']){
                return 'success';
        }

        return '';
}

The ImportSendListLager() function is added in addition. If the option for transferring stock numbers is activated in the import settings, this function leads to a synchronization of the stocks in the store with the stocks in xentral. In this example, this is done via the item number. It should be noted that for this function, the data parameter of the Importer object has the data for the item to be updated.

public function ImportSendListLager()
{
        $updatedArticles = 0;
        $tmp = $this->CatchRemoteCommand('data');
        foreach ($tmp as $article){
                $nummer = $article['nummer'];
                $lageranzahl = $article['anzahl_lager'];

                $updateInStock = [
                        'mainDetail' => [
                'inStock' => $lageranzahl
                        ]
                ];

                $params = [
                        'useNumberAsId'=>true
                ];

                $result = $this->call('articles/'.$nummer, 'PUT',$updateInStock, $params);
                if($result['success']){
                        $updatedArticles++;
                }
        }
        return $updatedArticles;
}

The ImportSendList() function is a version of ImportSendListLager(). This function transfers items to the store or updates their data. So item properties or images can be transferred to the store. It depends on the respective store interface how and which data can be transferred.

Care should be taken to separate the two functions, as ImportSendList is only called in two cases:

The ImportGetAuftraegeAnzahl function determines how many open orders are available in the store and need to be picked up. It is conceivable that the orders can be picked up via the status, from a certain order number or also via the order date. Depending on the store interface, not all options can be realized.

public function ImportGetAuftraegeAnzahl()
{
        $result = $this->getOrders($this->data);

        return count($result['data']);
}

The most important basic function of all importers is to fetch and translate the orders from the store to the shopping cart format of xentral. After the order is fetched from the store API, the first step is to transfer the customer's address data to the shopping cart:

$cart['anrede'] = 'herr';
$cart['strasse'] = $order['data']['billing']['street'];
$cart['plz'] = $order['data']['billing']['zipCode'];
$cart['ort'] = $order['data']['billing']['city'];
$cart['land'] = $order['data']['billing']['country']['iso'];
$cart['email'] = $order['data']['customer']['email'];
$cart['name'] = $order['data']['billing']['firstName'] . ' ' . $order['data']['billing']['lastName'];

If there is a deviating delivery address, this must also be transferred and the field deviating delivery address must be filled with true to ensure that the order arrives at the correct recipient. In addition, there are important data that are important for further processing.

$cart['auftrag'] = $orderFromCollection['id'];
$cart['gesamtsumme'] = $orderFromCollection['invoiceAmount'];
$cart['transaktionsnummer'] = $orderFromCollection['transactionId'];
$cart['onlinebestellnummer'] = $orderFromCollection['number'];
...
$cart['zahlungsweise'] = $order['data']['payment']['name'];
$cart['lieferung'] = $order['data']['dispatch']['name'];
$cart['bestelldatum'] = substr($order['data']['orderTime'],0,10);
$cart['versandkostennetto'] = $order['data']['invoiceShippingNet'];

Total amount:

The order total serves as a safeguard against an incorrectly assembled shopping cart. If item data is not passed correctly or there is a problem with taxation, the order total differs from the cart total and the auto-shipping option is disabled for the order. This ensures that no shipment leaves the warehouse that does not match the order.

Transaction number:

The transaction number is relevant for the automation of accounting and helps to allocate paid orders.

Order:

In this field the unique identification of the order for the store is transferred. Not every store interface allows to change the shipping status of an order via the order number. Occasionally an internal ID is required, which can be passed at this point. The value passed here will be referred to later when a change in the order status is transmitted from the store.

Online order number:

The order number is to be entered in this field. This facilitates the assignment and in case of queries, an order from the store can be directly assigned to an order in xentral.

Payment method:

Transferring the payment method allows you to enable or disable settings such as autoship, fast lane, or invoice creation specific to certain payment methods in xentral.

Delivery:

If the delivery method is transferred, a matching can be done in xentral, similar to the payment method.

Gross shipping costs:

When placing an order, the shipping costs can be transferred like an item in the shopping cart. By this special field the forwarding expenses are booked however on the, in the Importer adjusted, postage item and transferred into the order.

Order date: The order date shows the date the order was received.

foreach ($order['data']['details'] as $article)
{
        $articlearray[] = [
                'articleid' => $article['articleNumber'],
                'name' => $article['articleName'],
                'price' => $article['price'],
                'quantity' => $article['quantity']
        ];
}

...

$orderData =[
        'id' => $cart['auftrag'],
        'warenkorb' => base64_encode(serialize($cart)),
        'warenkorbjson' => base64_encode(json_encode($cart))
];

When the required basic data of the order has been transferred to the shopping cart, the individual items are to be added to the shopping cart. The item number is transferred in the articleid field. The other fields contain their respective equivalent from the order item.

After the shopping cart has been filled with all data from the order, the function returns the data.

The ImportDeleteAuftrag function is responsible for marking an open purchase order as "In process". The ImportUpdateAuftrag partner function marks the order as "Shipped".

public function ImportDeleteAuftrag()
{
  $orderId = $this->data['auftrag'];
  $update = [
    'orderStatusId' => 1
  ];

  $this->call('orders/'.$orderId, 'PUT',$update);

  return true;
}

The UNB line defines, among other things, the recipient and sender. A unique identifier for the communication partner must be entered here. There are various possibilities for this:

With EDI/EDIFACT almost everything is transmitted with code lists. For this, there are some sources that explain the format and show how to handle it:

The data transfer is done e.g. with SFTP exclusively via keyfile (ssh pub-key), alternatively AS2 is used. If required, xentral will provide an AS2 server, for this contact the sales department or the partner account manager at xentral.

The EDI file is a plain text file, ideally encoded in UTF8; however, this is not mandatory in the standard. If a file with only one line is sent, the EDI can replace punctuation ' (single quotation mark, is defined in the UNA segment) with an LF or CR/LF.

Certain segments may occur more than once in EDI and may then have different meanings, e.g. data in the header and at item level.

Some segments were combined into an ORDER to show how an ORDER would be parsed.

BGM+220+4HQ7EBLG+9'   --> Bestellung mit PO Nummer 4HQ7EBLG, 
                      --> die 9 am Schluss bedeutet es werden die EAN/GS1 Codelisten verwendet
DTM+137:20190107:102' --> Belegdatum im Format 102
DTM+63:20190111:102'  --> Lieferdatum spätestens im format 102
DTM+64:20190107:102'  --> Lieferdatum frühstens im Format 102
Benötigt wird das GLN Verzeichnis aus dem Vendor-Central, damit die Lieferadressen zugeordnet werden können.
NAD+BY+5450534000017::9'          --> Käufer, GLN Codiert
NAD+SU+4016428000009::9'          --> Lieferant, hier wird die eigene UNB-ID wieder angegeben
NAD+DP+5450534002325::9+++++++DE' --> Lieferadresse mit Land
NAD+IV+5450534005838::9++AMAZON EU SARL:NIEDERLASSUNG DEUTSCHLAND+MARCEL-BREUER-STR. 12+MUENCHEN++80807+DE' 
                                  --> Rechnungsadresse als GLN und Klartext muss in der INVOICE Message auch komplett 
                                  --> im Klartext übertragen werden.

In the following (from LIN) the positions begin. Between NAD and LIN further lines are possible, e.g. RFF (reference in each case to the current element) or CUX (here the currency is defined).

Each LIN defines the beginning of a new position (LIN+1, LIN+2, LIN+3 etc.):

LIN+1++4016428352115:EN'          --> Artikel Pos 1 mit Artikel EAN, EN=Datenherkunft EAN, könnte evtl. auch SA sein
QTY+21:52'                        --> Pos Menge in Stück
PRI+AAA:55.9'                     --> Preis pro Stück netto

This is followed by framework data, which is primarily used for validation: With UMS+S the sum block begins, which enables a validation with the help of different sums.

If several documents of a UNB transmission are contained, these now follow by a UNH or BGM, separated with the document header.