Zum Hauptinhalt gehen
Anmelden

Smarty im Übertragen-Modul

  • Aktualisiert

Inhaltsverzeichnis

Das Übertragen-Modul ermöglicht es dir, eine Vielzahl von Belegen oder Daten aus xentral zu exportieren. Dabei werden dir neben verschiedenen Ausgabeformaten und Ausgabekanälen auch verschiedene Trigger zum Export angeboten (z.B. der Belegstatus, Label, ID oder Datum eines Beleges, etc.). Dazu verwendest du das Smarty Transfer-Modul.

Mit Hilfe von Smarty kannst du nun das Zielformat der ausgegebenen Daten selbst definieren und mit Hilfe von 

  • Funktionen (wie z.B. truncate) bearbeiten,
  • mit SQL-Abfragen anreichern
  • und durch die Anwendung von Schleifen, Bedingungen o.ä. mit Logik verändern.

Im Übertragen-Modul steht dir Smarty bei eingehenden und ausgehenden Nachrichten zur Verfügung. Dabei bestimmt das Template 

  • bei ausgehenden Nachrichten das von der Gegenstelle erwartete Zielformat 
  • bei eingehenden Nachrichten das xentral interne Format zur Verarbeitung (in den meisten Fällen xentral XML).

Belegarten und Daten

Hier erfährst du, welche Belegarten und Daten du exportieren bzw. importieren kannst.

Ausgehende Übertragungen und Daten

Im Übertragen-Modul kannst du per Smarty die folgenden Belegtypen exportieren:

  • Auftrag
  • Lieferschein
  • Rechnung
  • Gutschrift
  • Angebot 
  • Bestellung
  • Retoure

Darüber hinaus kannst du die folgenden Daten mit Hilfe von Smarty Templates exportieren:

  • Artikel
  • Lagerzahlen
    • Lagerbestände
    • Lagerplätze

Eingehende Übertragungen und Daten

Im Übertragen-Modul kannst du per Smarty die folgenden Belegtypen importieren:

  • Auftrag: techn. Bezeichnung 'auftrag' (XML, CSV)
  • Bestellung: techn. Bezeichnung 'bestellung' (XML, CSV)
  • Produktion: techn. Bezeichnung 'produktion' (XML, CSV)
  • Retoure: techn. Bezeichnung 'retoure' (XML, CSV)

Darüberhinaus kannst du die folgenden Daten importieren (einlesen): 

  • Lagerzahlen
  • Artikeldaten
  • Tracking-Informationen

Um alle Belegtypen zu importieren, musst du das Übertragungsformat smarty auswählen und speichern. Dann erscheint unter Beleg empfangen eine neue Checkbox, die alle Belegtypen importieren heißt.

Fehler beim Auslesen kannst du teilweise aus dem Monitor bzw. der Logfile lesen.

Smarty Ausgehend (outbound oder Export)

Daten aus xentral zu versenden (auch “outbound” genannt) ermöglicht es dir die Daten von xentral 

  1. in ein Zielformat zu konvertieren und anschließend 
  2. in ein Fremdsystem zu exportieren

Eine Template-Datei könnte dabei z.B. folgendermaßen aussehen:

<?xml version="1.0" encoding="utf-8"?>
<auftrag>
  <status>{$beleg->status}</status>
  <datum>{$beleg->datum|date_format:'%d.%m.%Y'}</datum>
  <lieferdatum>{$beleg->lieferdatum}</lieferdatum>
  <versandart>{$beleg->versandart}</versandart>
  <zahlungsweise>{$beleg->zahlungsweise}</zahlungsweise>
  <belegnr>{$beleg->belegnr}</belegnr>
  <kundennummer>{$beleg->kundennummer}</kundennummer>
  <name>{$beleg->name}</name>
  <strasse>{$beleg->strasse}</strasse>
  <plz>{$beleg->plz}</plz>
  <ort>{$beleg->ort}</ort>
  <positionen>
  {foreach from=$beleg->positionen key=keyrow item=position}{* Positionen *}
  <position>
<nummer>{$position->nummer}</nummer>
   <bezeichnung>{$position->bezeichnung}</bezeichnung>
   <beschreibung>{$position->beschreibung}</beschreibung>
   <menge>{$position->menge}</menge>
   <preis>{$position->preis}</preis>
   <einheit>{$position->einheit}</einheit>
</position>
  {/foreach}
  </positionen>
   {if $beleg->versand}
   <tracking>
   {foreach from=$beleg->versand key=keyversand item=tracking}{* Versand *}
<tracking>{$tracking->tracking}</tracking>
   {/foreach}
   </tracking>
{/if}
</auftrag>

Smarty Eingehend (inbound oder Import)

Daten in xentral einzulesen (auch “inbound” genannt) ermöglicht es dir die Daten 

  1. aus einem anderen System zu importieren, 
  2. zu interpretieren, dann 
  3. in ein xentral Zielformat zu konvertieren und anschließend 
  4. in xentral zu importieren.

Hinweis: Alle Inhalte, die im Eingangskonverter eingegeben werden, orientieren sich an den Standard-Templates aus dem Übertragen-Modul. Diese stellen gleichzeitig auch das Maximum an zu verarbeitenden Informationen dar. Informationen, welche darüber hinaus geliefert werden, bleiben unbeachtet.

Standardmäßig werden die meisten Inhalte korrekt über das $object-Array geparst. Wenn die Darstellung nicht passen sollte, kannst du mit alternativen Arrays arbeiten. 

Alternative smarty-objects

  • $csv: ein Array aus Objekten mit dem Headerspalten als Keys
  • $csvwithoutheader: ein Array aus Objekten ohne Headerspalten; Aufruf der Spalten in der Notation col0, col1, usw. 
  • $xml: ein Object das aus einem Xml gaparst wurde 
  • $object: ist ein $xml falls Ursprungsdaten ein gültiges xml waren
  • $original: ist der Original-String des Eingangs

Operationen

  • {"Der Auftrag enthält keine Positionen"|error}
    gibt einen Fehler an Smarty aus, der in den Übertragungsmonitor geloggt wird

  • {"SELECT nummer FROM artikel"|assignsql assign="artikelnummern"}
    speichert das Ergebnis der SQL-Abfrage in die Variable $artikelnummern

  • {$original|replace:"1.0":"2.0"|getxml assign="neuesxml"}
    ersetzt alle Strings 1.0 zu 2.0 und speichert wandelt es in ein neues Objekt $neuesxml um

  • {$position->nummer|pregreplace:'/[^0-9]/':''}
    führt eine reguläre Ersetzung auf das eine Objekt aus

Beispiele

Nachfolgend zeigen wir dir Beispiele zur eingehenden Datenkonvertierung.

Beispiel 1: Umwandlung CSV-Datei in xml zur Auftragserstellung

<?xml version="1.0" encoding="UTF-8"?>
<response>
<xml>
{assign var="letztebestellnummer" value=0}{assign var="ersterbeleg" value=1}

<auftrag_list>{foreach from=$object key=keyrow item=position}{if $letztebestellnummer <>  $position->beleg_belegnr and $ersterbeleg == 0}
</auftrag_position_list>
</auftrag>
{/if}

{if $letztebestellnummer <>  $position->beleg_belegnr or $ersterbeleg == 1}
<auftrag>
{$ersterbeleg = 0}{$letztebestellnummer= $position->beleg_belegnr}
<datum>{$position->beleg_datum|date_format:"%d.%m.%Y"}</datum>
<versandart>{$position->beleg_versandart}</versandart>
<status>{$position->beleg_status}</status>
<projekt>{$position->beleg_projekt}</projekt>
<name>{$position->beleg_name_firma|escape:"html"}</name>
<adresszusatz>{$position->beleg_name_nachname|escape:"html"} {$position->beleg_name_vorname|escape:"html"}</adresszusatz>
<strasse>{$position->beleg_adresse_strasse} {$position->beleg_adresse_hausnummer|escape:"html"}</strasse>
<plz>{$position->beleg_plz}</plz>
<ort>{$position->beleg_ort}</ort>
<ihrebestellnummer>{$position->beleg_belegnr}</ihrebestellnummer>
<internebezeichnung>{$position->POSNR|string_format:"%.0f"}</internebezeichnung>
<email>{$position->beleg_email}</email>
<telefon>{$position->beleg_telefon}</telefon>
<lieferunterabteilung>
</lieferunterabteilung>
<internebemerkung>
</internebemerkung>
<auftrag_position_list>{/if}
<auftrag_position>
<name_de>{$position->artikel_bezeichnung|escape:"html"}</name_de>
<menge>{$position->artikel_menge}</menge>
<nummer>{$position->artikel_nummer}</nummer>
</auftrag_position>
{/foreach}
</auftrag_position_list>
</auftrag>
</auftrag_list>
</xml>
</response>

 

Beispiel 2: Falllprüfung für Lagerzahlen inklusive SQL-Verwendung

Hintergrund: Lagerzahlen wurden von Fulfiller teilweise ohne MHD/Chargen-Infos übertragen. Via SQL wird geprüft, ob der Artikel MHD/Chargenpflichtig ist. Wenn ja, dann wird das template um statische Informationen erweitert.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<xml>
<artikel_list>
{assign var="counter" value = 0}
{foreach from=$object->xml->artikel_list->artikel key=key item=item}
{assign var="Nummer" value=$object->xml->artikel_list->artikel[$counter++]->nummer}
{"SELECT nummer, mindesthaltbarkeitsdatum, chargenverwaltung FROM artikel WHERE nummer = '$Nummer' and lagerartikel = 1 and geloescht<>1 "|assignsql assign="artikel"}
<artikel>
<nummer>{$item->nummer}</nummer>
<lagerzahl>{$item->lagerzahl}</lagerzahl>
{if !($item->lager_platz)}
<lager_platz>Hauptlager</lager_platz>{else} <lager_platz>{$item->lager_platz}</lager_platz> {/if}
{if $artikel[0]->nummer == $item->nummer && $artikel[0]->mindesthaltbarkeitsdatum == 1 && $artikel[0]->chargenverwaltung == 2}
<mhd>31.12.9999</mhd>
<charge>DUMMY</charge>
{elseif $artikel[0]->nummer == $item->nummer && $artikel[0]->chargenverwaltung == 2}
<charge>DUMMY</charge>
{/if}
</artikel>
{/foreach}
</artikel_list>
</xml>
</response>

 

Beispiel 3: Einlesen von CSV-Dateien ohne Kopfzeile

Hinweis: Array von $csvwithoutheader wird nicht über den Bildschirm von $object ausgegeben. Den Inhalt aus $csvwithoutheader kannst du auch bspw. mit {$csvwithoutheader|@debug_print_var} ausgeben. Der Spaltenaufruf erfolgt über die Notation col0-n. 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <xml>
     <artikel_list>
 {foreach from=$csvwithoutheader key=keyrow item=Ab}
  <artikel>
     <nummer>{$Ab->col0}</nummer>
         <lagerzahl>{$Ab->col1}</lagerzahl>
</artikel>
{/foreach}
     </artikel_list>
    </xml>
</response>

 

Besonderheiten im Übertragen-Modul

Hier zeigen wir dir Besonderheiten von Smarty im Übertragen-Modul.

Verknüpfte Belege

In allen Belegen kannst du mit Hilfe von Smarty auf verknüpfte Belege zugreifen. Wenn z.B. zu einem Auftrag ein Lieferschein existiert, existiert auch ein Array $beleg->lieferschein[], in dem dann die entsprechenden Informationen des referenzierten Lieferscheines zur Verfügung stehen. Auf diese Art kannst du schnell auf ergänzende Belegnummern, Lieferdaten, Chargen oder Seriennummern zurückgreifen - auch bei der Erstellung eines Auftrages. Die Lieferscheinnummer z.B. erreichst du direkt über $beleg->lieferschein[0]->belegnr

Die Folgenden Daten stehen dir in den jeweiligen Belegen zur Verfügung, sofern ein entsprechender Beleg im System existiert.

Im Auftrag:

  • $beleg->bestellung[]
  • $beleg->angebot[]
  • $beleg->lieferschein[]
  • $beleg->rechnung[]
  • $beleg->retoure[]
  • $beleg->gutschrift[]

Im Lieferschein:

  • $beleg->bestellung[]
  • $beleg->rechnung[]

In der Rechnung:

  • $beleg->bestellung[]
  • $beleg->lieferschein[]

ArtikelStammdaten aus Positionen ansprechen

Über die Belegpositionen kannst du auch "darunterliegende" Strukturen abrufen, die nicht direkt im Beleg gespeichert sind. Ein Beispiel dafür ist das Gewicht eines Artikels. Dieses kannst du über {$position->articledata->gewicht} abrufen. So kannst du z.B. durch eine Multiplikation mit der Menge der Position und dem Aufaddieren aller Gewichte auch das Gesamtgewicht aller Artikel eines Beleges berechnen und übertragen. Über $position->articledata kannst du alle Spalten aus der Tabelle artikel ansprechen. Dabei solltest du immer beachten, ob Informationen aus den Artikel-Stammdaten evtl. in der Auftragsposition bereits verändert worden sein könnten. Im Zweifelsfall solltest du den Wert aus dem Beleg verwenden.

SQL-Abfragen

Im Übertragen-Modul kannst du zur Anreicherung von Daten auch allgemeine SQL-Anfragen erstellen und in den ausgegebenen Templates ausgeben. Dazu verwendest du folgende Syntax:

{"SELECT gln, rechnung_gln FROM adresse where lieferantennummer = '{$beleg->lieferantennummer}' "|assignsql assign="adressdata"}

Auf das Ergebnis kannst du dann über das zugewiesene Array adressdata zugreifen:

{$adressdata[0]->gln} // für den gezielten Aufruf des Arrays

Datenmanipulation und Formatumwandlung

Datumswerte können nach Anforderung ausgegeben werden:

  • Int. Datumsformat (ISO 8601): ​{$beleg->datum|date_format:'%Y-%m-%d'}
  • Deutsches Datumsformat (DIN 5008): ​{$beleg->datum|date_format:'%d.%m.%Y'}

Zahlen können nach Bedarf umformatiert werden. Hier am Beispiel der Spalte "Menge":

  • Ausgabe ohne Nachkommastellen (als Ganzzahl): ​{$position->menge|string_format:'%d'}
  • Ausgabe mit einer Nachkommastelle: ​​​{$position->menge|string_format:'%.1f'}
  • Ausgabe mit zwei Nachkommastellen: ​​{$position->menge|string_format:'%.2f'}​​

Grundsätzlich können alle Formate ausgegeben werden, die durch die Funktion sprintf in PHP verfügbar sind.

Felddefinitionen

Hier findest du eine Auflistung der verschiedenen Felddefinitionen. Eine vollständige Auflistung der verfügbaren Felder inkl. einer Übersetzung der Feldnamen und einer Beschreibung der Inhalte in Englisch ist jeweils unterhalb des Screenshots verlinkt.

Lieferschein

smarty_uebertragen-modul_01.png

Weitere Felddefinitionen findest du hier.

 

Tracking Rückmeldung

smarty_uebertragen-modul_02.png

Weitere Felddefinitionen findest du hier.

 

Lagerzahlen-Rückmeldung

smarty_uebertragen-modul_03.png

Weitere Felddefinitionen findest du hier.

 

Features

Mit Hilfe der integrierten Template-Engine Smarty können einfach und flexibel zeichenbasierte Ausgabestrukturen von Datenformaten wie CSV, XML oder JSON an die Bedürfnisse des Kunden angepasst werden. Im Grunde muss lediglich das vorhandene Zielformat in eine Textdatei kopiert und mit den entsprechenden Variablen gefüllt werden. Diese können dabei noch umformatiert werden.

Belegdaten finden sich z.B. in der Smarty-Variable $beleg und werden in gewohnter PHP-Objektschreibweise angesprochen, z.B. $beleg->kundennummer oder $beleg->belegnr. Die Namensgebung gleicht der Benennung von Datenbank-Spaltennamen. Auch ein Zugriff auf komplexere Strukturen ist möglich (je nach Beleg). So kann im Lieferschein auf den zu Grunde liegenden Auftrag zugegriffen werden: $beleg->auftrag->lieferdatum. Verkürztes Beispiel mit fiktivem Format {* Beleg-Stammdaten -------------------------------- *} {$beleg->status} {$beleg->datum|date_format:'%d.%m.%Y'} {$beleg->belegnr} {$beleg->kundennummer} {$beleg->name} {* Zugriff auf Daten des zugrundeliegenden Auftrages *} {$beleg->auftrag->lieferdatum} {* Weitere Felder entfernt *}

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

Beispiele

Im Folgenden haben wir dir einige Beispiele zusammengefasst, die dir die Ausgabe verschiedener Lieferscheinformate in den Formaten EDI, CSV und XML ermöglichen. Bitte prüfe bei eigener Anwendung die Spaltenbeschriftungen (CSV), Tagnamen (XML) und EDI-Spezifikationen. Natürlich sind auch weitere Ausgabeformate (wie z.B. JSON) denkbar.

Beispiel Lieferschein CSV (ausführlich)

Das folgende Beispiel listet ein ausführliches Beispiel für einen Export eines Lieferscheines in verschiedenen Formaten.

Format EDI

  • wird ergänzt -

Format CSV

"tracking";"beleg_status";"beleg_datum";"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";"artikel_nummer";"artikel_bezeichnung";"artikel_beschreibung";"artikel_menge";"artikel_preis";"artikel_rabatt";"artikel_waehrung";"artikel_lieferdatum";"artikel_sort";"artikel_umsatzsteuer";"artikel_einheit";"artikel_zolltarifnummer";"artikel_herkunftsland";"artikel_artikelnummerkunde";"wunschlieferdatum";"artikel_freifeld1";"artikel_freifeld2";"artikel_freifeld3";"artikel_freifeld40"{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}

Format XML

{$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} {foreach from=$beleg->positionen key=keypos item=position} {$position->nummer} {$position->bezeichnung} {$position->beschreibung} {$position->menge} {$position->preis} {$position->rabatt} {$position->waehrung} {$position->lieferdatum} {$position->sort} {$position->umsatzsteuer} {$position->einheit} {$position->zolltarifnummer} {$position->herkunftsland} {$position->artikelnummerkunde} {$position->freifeld1} {$position->freifeld2} {$position->freifeld3} {* Ggf. weitere Freifelder *} {$position->freifeld40} {/foreach} {if $beleg->versand} {foreach from=$beleg->versand key=keyversand item=tracking} {* Versand *} {$tracking->tracking} {/foreach} {/if}

Beispiel Lieferschein mit MHD

Im Folgenden werden Beispiele als Ergänzung zu obigen Code-Beispielen gezeigt, die nur die Besonderheiten in Bezug auf MHDs in einer Position berücksichtigen.

Format CSV

  • wird ergänzt -

Format XML

  • wird ergänzt -

Beispiel Lieferschein mit Charge

Im Folgenden werden Beispiele als Ergänzung zu obigen Code-Beispielen gezeigt, die nur die Besonderheiten in Bezug auf Chargen in einer Position berücksichtigen.

Format CSV

  • wird ergänzt -

Format XML

  • wird ergänzt -

Beispiel Lieferschein mit Charge und MHD

Im Folgenden werden Beispiele als Ergänzung zu obigen Code-Beispielen gezeigt, die nur die Besonderheiten in Bezug auf MHDs und Chargen in einer Position berücksichtigen.

Format CSV

  • wird ergänzt -

Format XML

  • wird ergänzt -

Beispiel Auftrag

Anwendbar nur bei direktem Fulfillment ohne Autoversand. Diese Option sollte genau geprüft werden, meistens ist die Übertragung von Lieferscheinen der optimale Weg.

Format EDI

  • wird ergänzt -

Format CSV

  • wird ergänzt -

Format XML

  • wird ergänzt -