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
- in ein Zielformat zu konvertieren und anschließend
- 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
- aus einem anderen System zu importieren,
- zu interpretieren, dann
- in ein xentral Zielformat zu konvertieren und anschließend
- 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>
Übertragung mit Typ API
API steht als technische Übertragungsart im Standard zur Verfügung. Weitere verfügbare Übertragungsarten sind FTP, FTPS (Benutzername und Passwort, keine Zertifikate), SFTP, E-Mail und die lokale Speicherung auf dem Server.
Der Umgang mit Smarty erfolgt hier nach derselben Weise, wie wenn eine andere Übertragungsart verwendet wird. Allerdings können hier api-spezifische Anforderungen wie Authentifizierung, Header oder application-type zu beachten sein. Wenn du mit einer Authentifizierung arbeitest, die ein Passwort benötigt, werden im Tab Dateien werden keine Enträge angezeigt. Erfolgreiche Übertragungen können zum aktuellen Zeitpunkt nur im Übertragen-Monitor nachvollzogen werden, wenn zum entsprechenden Beleg bzw. der entsprechenden Aktion “hochgeladen” in einer grünen Erfolgsmeldung steht. Möglicherweise werden nur unzureichende Fehlermeldungen bei der Übertragung zurückgemeldet, weshalb du hier auf ein ausführliches error-logging vom Zielsystem angewiesen bist.
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
Weitere Felddefinitionen findest du hier.
Tracking Rückmeldung
Weitere Felddefinitionen findest du hier.
Lagerzahlen-Rückmeldung
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 -