Etiketten-API für WaWi, ERP, Lagerverwaltung & mehr
"Barcode Forge" gibt es als Standard und als Developer Edition. Letztere erweitert die Software um eine
API-Schnittstelle, die es ermöglicht, Barcode-Etiketten aus der eigenen Anwendung zu drucken
(z.B. Lagerverwaltung, Warenwirtschaftssystem, ERP etc.).
Die Etiketten-API – Alles, was Sie wissen müssen
Ihre Anwendung speichert die zu druckenden Daten in einer XML-Datei und übergibt den Pfad an die API. Der erste Parameter ist ein im GUI-Modus erstelltes Etikettenlayout (Projektdatei):
bcf.exe "C:\Etiketten\Layout.bcfp" "C:\TEMP\Druckauftrag.xml"
Nachfolgend das Beispiel einer XML-Druckauftragsdatei, welche 2 Datensätze mit jeweils 3 Feldern zum Drucken übergibt. Pro Datensatz soll die API dabei jeweils 3 Etikettenkopien drucken.
<?xml version="1.0" encoding="UTF-8"?>
<printjob labelsperrow="3" printdirection="vertical" startpositionx="2" startpositiony="4">
</printjob>
<printjob labelsperrow="3" printdirection="vertical" startpositionx="2" startpositiony="4">
<printservice name="default" tray="1"/>
<fieldmap>
<field>ArtikelNr</field>
<field>Bezeichnung</field>
<field>Gewicht</field>
</fieldmap>
<data>
<row>
<cell>123</cell>
<cell>Apfel</cell>
<cell>200</cell>
</row>
<row>
<cell>456</cell>
<cell>Orange</cell>
<cell>180</cell>
</row>
</data>
</printjob>
Referenz der Elemente und Attribute
1. Druckauftrag: Die zum Wurzelelement printjob gehörenden und allesamt optionalen Attribute enthalten Parameter für den aktuellen Druckauftrag. labelsperrow definiert die Anzahl Etikettenkopien, die pro Datensatz gedruckt werden sollen. Default-Wert ist 1. printdirection bestimmt die Druckrichtung, falls der Druck auf Etikettenbögen erfolgt. Mögliche Werte sind "horizontal" (default) und "vertical". startpositionx und startpositiony legen die Position des ersten zu bedruckenden Etiketts auf dem Etikettenbogen fest, beginnend jeweils mit 1. Nicht im obigen Beispiel abgebildet: Mit designno kann festgelegt werden, welcher der drei Etikettenentwürfe (römisch I, II, III in der GUI) genutzt wird. Mögliche Werte sind entsprechend 1 (default), 2 oder 3.2. Druckdienst: Das optionale printservice-Element spezifiziert den zu verwendenden Druckdienst. Das name-Attribut gibt den Namen des Druckers an (Groß-/Kleinschreibung beachten). Der im GUI-Modus ausgewählte Drucker kann mit "default" oder "" oder durch Weglassen des Attributs adressiert werden. Mit tray kann ein Papierschacht ausgewählt werden. Die ganzzahligen IDs der Papierschächte eines Druckers werden im GUI-Modus angezeigt. Bei Weglassen des Attributs wird der im GUI-Modus ausgewählte Papierschacht verwendet.
3. Feldzuordnungen: Im fieldmap-Element (optional) werden Zuordnungen von Feldnamen eines Barcode Forge-Projektes zu Spaltennummern der Datensätze innerhalb der aktuellen XML-Druckauftragsdatei hergestellt. So wird z.B. im ersten field-Subelement das Feld innerhalb des Barcode Forge-Projektes referenziert, in welches jeweils der erste Wert eines Datensatzes eingepflegt wird, usw. Wird das fieldmap-Element ausgelassen, so gilt die gemeinsame Position als Verknüpfung.
4. Daten: Das data-Element enthält schließlich die "eigentlichen" Daten für den Etikettendruck in Form von keinem, einem oder mehreren row-Subelementen, welche ihrerseits aus keinem, einem oder mehreren cell-Subelementen bestehen können. Nicht im obigen Beispiel abgebildet: Ein row-Element kann zusätzlich das optionale Attribut labels besitzen. Damit lässt sich die zu druckende Menge Etiketten für den jeweiligen Datensatz individuell definieren. Fehlt das Attribut, dann bestimmt das unter (1) beschriebene labelsperrow-Attribut die Menge.
Zu beachten beim Erzeugen der XML-Datei
1. Innerhalb der für den Etikettendruck bestimmten (Nutz-)Daten müssen die Zeichen < > & " ' durch entsprechende HTML4-Entities ersetzt werden: < > & " ' (Diese Ersetzung gewährleistet, dass das XML wohlgeformt bleibt und potenzielle Parsing-Fehler vermieden werden.)Beispiel einer Methode in Java, welche dies bewerkstelligt:
static String[] HTML4_ESC_CHARS = { "<", ">", "\"", "'", "&" };
static String[] HTML4_ESC_ENTITIES = { "<", ">", """, "'", "&" };
static String escapeHtml4(String s) {
for (int i=4; i>=0; i--) // Reihenfolge wichtig! '&' sollten als erste ersetzt werden
s = s.replace(HTML4_ESC_CHARS[i], HTML4_ESC_ENTITIES[i]);
return s;
}
static String[] HTML4_ESC_ENTITIES = { "<", ">", """, "'", "&" };
static String escapeHtml4(String s) {
for (int i=4; i>=0; i--) // Reihenfolge wichtig! '&' sollten als erste ersetzt werden
s = s.replace(HTML4_ESC_CHARS[i], HTML4_ESC_ENTITIES[i]);
return s;
}
2. Anstelle von UTF-8 wie im obigen Beispiel (siehe erste Zeile) können auch andere gängige Zeichensätze verwendet werden (ISO-8859-x, Cp1252, UTF-16 usw.). Die XML-Datei sollte immer mit dem in ihr deklarierten Zeichensatz erstellt werden.
Status-/Fehlerbehandlung
Nach dem Druckvorgang liefert die API einen sogenannten Exit Code zurück – in der Programmierung von Batch-Dateien auch als ERRORLEVEL bekannt. Der Exit Code ist eine Ganzzahl, die Auskunft darüber gibt, mit welchem Ergebnis ein Programm beendet wurde. Programmiersprachen, welche in der Lage sind, (externe) Prozesse zu starten, stellen idR. auch Funktionen bzw. Methoden zum Abfragen des Exit Code nach Beendigung eines Prozesses zur Verfügung. Das aufrufende Programm kann diese Funktionen nutzen, um auf mögliche Fehler entsprechend zu reagieren.Exit Codes:
0 – Druckvorgang erfolgreich ausgeführt und beendet
101 – Projektdatei nicht gefunden
102 – XML-Druckauftragsdatei nicht gefunden
103 – I/O-Fehler beim Laden der Projektdatei / beschädigte Projektdatei
104 – I/O-Fehler beim Laden der XML-Druckauftragsdatei
105 – Korrupte XML-Druckauftragsdatei / kein wohlgeformtes XML
201 – Horizontale Startposition außerhalb des möglichen Bereichs
202 – Vertikale Startposition außerhalb des möglichen Bereichs
203 – Druckdienst (mit dem spezifizierten Namen) nicht gefunden
204 – Papierschacht (mit der spezifizierten ID) nicht gefunden
301 – Fehler beim Drucken
101 – Projektdatei nicht gefunden
102 – XML-Druckauftragsdatei nicht gefunden
103 – I/O-Fehler beim Laden der Projektdatei / beschädigte Projektdatei
104 – I/O-Fehler beim Laden der XML-Druckauftragsdatei
105 – Korrupte XML-Druckauftragsdatei / kein wohlgeformtes XML
201 – Horizontale Startposition außerhalb des möglichen Bereichs
202 – Vertikale Startposition außerhalb des möglichen Bereichs
203 – Druckdienst (mit dem spezifizierten Namen) nicht gefunden
204 – Papierschacht (mit der spezifizierten ID) nicht gefunden
301 – Fehler beim Drucken
Standardmäßig zeigt die API bei Auftreten von Fehlern zusätzlich einen Fehlerdialog an. Soll die Fehlerbehandlung vollständig an die aufrufende Anwendung übertragen werden, so kann das Anzeigen von Fehlerdialogen mit Hilfe des optionalen Parameters -showerrors=no unterbunden werden:
bcf.exe -showerrors=no "C:\Etiketten\Layout.bcfp" "C:\TEMP\Druckauftrag.xml"