Docs

Developer

XML

Inhalte

Barcodes

Kurzbeschreibung

Die XML-Sprache von intracon:bk stellt drei unterschiedliche Elemente zur Erzeugung von Barcodes bereit:

<Barcode>

<BarcodeFormatter>

<EpcBarcode>

Die Elemente unterscheiden sich insbesondere hinsichtlich der Herkunft des codierten Inhalts und ihres fachlichen Einsatzzwecks.

Während <Barcode> einen systemseitig erzeugten und zum Auftrag gespeicherten Barcode bereitstellt, kann mit <BarcodeFormatter> ein individueller Barcodeinhalt aufgebaut werden. <EpcBarcode> erzeugt einen standardisierten EPC-QR-Code für Zahlungsinformationen.

Einordnung

Bereich: Inhalte

Schwierigkeitsgrad: ⭐⭐⭐☆☆

Vorkenntnisse: Block · Content · Text · Variable

Siehe auch

Block

Variable

BlockProperties

Frame

Überblick

XML-Element	Herkunft des Barcodeinhalts	Typischer Einsatz
`<Barcode>`	Systemseitig generierter Barcodeinhalt	Identifikation eines Auftrags und Verarbeitung eingehender Rückläufer
`<BarcodeFormatter>`	Frei aus Texten, Variablen und weiteren Inhaltselementen aufgebaut	Individuelle Barcodes und QR-Codes
`<EpcBarcode>`	Definierte Zahlungsinformationen	EPC-QR-Code zur Übernahme von Überweisungsdaten in eine Banking-App

Alle drei Elemente erzeugen einen sichtbaren Dokumentinhalt und werden innerhalb eines <Content> verwendet.

Position innerhalb der Dokumentvorlage

Barcodes werden innerhalb eines <Content> und damit innerhalb eines <Block> definiert.

<Block>

    <Content>

        <Barcode
            NoText="true"
            Symbology="QR"
            Height="2000000"
            Width="2000000">
        </Barcode>

    </Content>

</Block>

Dasselbe gilt für <BarcodeFormatter> und <EpcBarcode>.

Wichtig

Die Barcodeelemente gehören nicht direkt unterhalb des <Body>.

Sie werden innerhalb eines <Content> verwendet, da sie einen sichtbaren Inhalt im erzeugten Dokument ausgeben.

Größenangaben

Die Attribute Height und Width verwenden EMU (English Metric Units).

Diese Einheit ermöglicht eine sehr genaue Definition von Größen innerhalb von Office-Dokumenten.

Umrechnung

EMU	Ungefähre Größe
`36000`	1 mm
`360000`	1 cm
`720000`	2 cm
`1080000`	3 cm
`1440000`	4 cm
`1800000`	5 cm
`2000000`	ca. 5,56 cm
`914400`	1 Zoll
`12700`	1 Punkt

Die Umrechnung erfolgt nach folgender Regel:

Zentimeter × 360000 = EMU

Beispiel für eine Breite von 4 cm:

4 × 360000 = 1440000

<Barcode
    Height="1440000"
    Width="1440000">
</Barcode>

Hinweis

Die tatsächlich sinnvolle Größe hängt von der verwendeten Symbologie, der Menge der codierten Daten und dem vorgesehenen Scanverfahren ab.

Ein Barcode sollte nach jeder Größenänderung mit einem geeigneten Scanner beziehungsweise einer entsprechenden App getestet werden.

Barcode

Zweck

Das XML-Element <Barcode> erzeugt einen systemseitig verwalteten Barcode.

Bei der Verarbeitung der Dokumentvorlage wird zum Auftrag ein Eintrag in der Barcode-Tabelle angelegt.

Dabei werden insbesondere folgende Informationen gespeichert:

Auftrags-ID,
Barcode-ID,
systemseitig generierter Barcode-Text,
gegebenenfalls ein Index.

Der Barcode-Text wird durch das System beziehungsweise eine dafür vorgesehene Prozedur erzeugt.

Diese Zuordnung ermöglicht es, einen später eingehenden Rückläufer anhand der Barcode-ID wieder mit den ursprünglichen Auftragsdaten zu verbinden.

XML-Wissen

<Barcode> dient nicht ausschließlich der sichtbaren Darstellung eines Barcodes.

Das Element erzeugt zusätzlich eine persistente technische Zuordnung zum Auftrag, die in nachgelagerten Prozessen ausgewertet werden kann.

Grundsyntax

<Barcode
    NoText="true"
    Symbology="COD128"
    Rotate="Rotate90"
    Height="2000000"
    Width="2000000"
    Index="true">
</Barcode>

Ein QR-Code kann beispielsweise so erzeugt werden:

<Barcode
    NoText="true"
    Symbology="QR"
    Height="2000000"
    Width="2000000">
</Barcode>

Mehrfache Verwendung innerhalb eines Auftrags

Wird <Barcode> innerhalb desselben Auftrags mehrfach verwendet, erzeugt das System nicht für jede Verwendung eine neue fachliche Barcode-ID und einen neuen Barcode-Text.

Stattdessen werden weitere Datensätze mit einer zusätzlichen Indexinformation erzeugt.

Dadurch können mehrere Vorkommen desselben Auftragsbarcodes unterschieden werden, während die grundsätzliche Zuordnung zum Auftrag erhalten bleibt.

Dieser Mechanismus ist insbesondere für Rückläufer- und Folgeprozesse relevant.

Attribute von Barcode

Attribut	Beschreibung
Form	Optionaler Bezeichner für eine Form beziehungsweise Ausprägung des Barcodes. Die konkrete Verwendung ist abhängig von der vorhandenen Systemkonfiguration.
Height	Höhe des Barcodes in EMU.
Index	Aktiviert die Verwendung beziehungsweise Speicherung einer Indexinformation für das Barcodevorkommen.
NoIndex	Unterdrückt eine Indexvergabe für das Barcodevorkommen.
NoText	Steuert, ob der im Barcode codierte Text zusätzlich lesbar unterhalb des Barcodes ausgegeben wird.
Rotate	Dreht den Barcode um den angegebenen Winkel.
Symbology	Legt den zu erzeugenden Barcodetyp fest.
Width	Breite des Barcodes in EMU.

Hinweis

Die Attribute Form, Index und NoIndex sollten nur eingesetzt werden, wenn das gewünschte Verhalten und die nachgelagerte Verarbeitung fachlich geklärt sind.

Insbesondere die Indexierung kann Auswirkungen auf Rückläufer- und Folgeprozesse haben.

NoText

Das Attribut NoText steuert die zusätzliche Ausgabe des Barcodeinhalts als lesbaren Text.

<Barcode NoText="true">
</Barcode>

Bei NoText="true" wird ausschließlich der grafische Barcode dargestellt.

Der codierte Inhalt wird nicht zusätzlich als Text unterhalb des Barcodes ausgegeben.

Wird NoText nicht gesetzt oder mit false verwendet, kann der Barcodeinhalt zusätzlich in lesbarer Form dargestellt werden.

Symbology

Das Attribut Symbology legt den Barcodetyp fest.

Zur Verfügung stehen:

Wert	Beschreibung
COD128	Linearer Code-128-Barcode
CODE39	Linearer Code-39-Barcode
CODE93	Linearer Code-93-Barcode
DataMatrix	Zweidimensionaler DataMatrix-Code
QR	Zweidimensionaler QR-Code

Beispiel:

<Barcode
    Symbology="DataMatrix"
    Height="1000000"
    Width="1000000">
</Barcode>

Developer-Tipp

Verwenden Sie bei der Auswahl des Wertes die IntelliSense.

Die Schreibweise muss exakt dem vom Developer angebotenen Wert entsprechen. Dies gilt insbesondere für den vom System angebotenen Wert COD128.

Rotate

Mit Rotate kann der Barcode gedreht werden.

Wert	Drehung
Rotate0	0 Grad
Rotate90	90 Grad
Rotate180	180 Grad
Rotate270	270 Grad

Beispiel:

<Barcode
    Symbology="COD128"
    Rotate="Rotate90"
    Height="2000000"
    Width="2000000">
</Barcode>

BarcodeFormatter

Zweck

Mit <BarcodeFormatter> kann ein individueller Barcodeinhalt erzeugt werden.

Im Gegensatz zu <Barcode> wird der codierte Wert nicht systemseitig als Auftragsbarcode generiert.

Stattdessen setzt sich der Inhalt aus den innerhalb des <BarcodeFormatter> enthaltenen XML-Elementen zusammen.

Hierfür können beispielsweise verwendet werden:

<Text>,
<Variable>,
<Break>,
weitere Elemente, die einen Inhalt bereitstellen.

Die enthaltenen Elemente werden verarbeitet und zu dem Wert zusammengesetzt, der anschließend im Barcode codiert wird.

Grundsyntax

<Block>

    <Content>

        <BarcodeFormatter
            Height="2000000"
            NoText="true"
            Symbology="QR"
            Width="2000000">

            <Text Content="www.hc-vision.de">
            </Text>

        </BarcodeFormatter>

    </Content>

</Block>

Individuellen Inhalt zusammensetzen

Der Barcodeinhalt kann aus mehreren Bestandteilen aufgebaut werden.

<Block>

    <Content>

        <BarcodeFormatter
            Height="2000000"
            NoText="true"
            Symbology="QR"
            Width="2000000">

            <Text Content="Zeile 1">
            </Text>

            <Break BreakType="column">
            </Break>

            <Variable Path="source.kvnr">
            </Variable>

        </BarcodeFormatter>

    </Content>

</Block>

Zunächst wird der statische Text verarbeitet. Anschließend wird der Inhalt der Variablen ergänzt.

Zugriff auf einen systemseitigen Barcode

Innerhalb eines <BarcodeFormatter> können auch Informationen eines zuvor erzeugten systemseitigen Barcodes verwendet werden.

<Block>

    <Content>

        <BarcodeFormatter
            Height="2000000"
            NoText="true"
            Symbology="QR"
            Width="2000000">

            <Text Content="Barcode-ID: ">
            </Text>

            <Variable Path="barcode.id">
            </Variable>

        </BarcodeFormatter>

    </Content>

</Block>

Der Variablenstamm barcode stellt unter anderem folgende Informationen bereit:

barcode.id,
barcode.text,
barcode.index.

Hinweis

Der Zugriff auf den Variablenstamm barcode kann die Erzeugung des systemseitigen Auftragsbarcodes auslösen, wenn bis zu diesem Zeitpunkt noch kein entsprechender Barcode vorhanden ist.

Attribute von BarcodeFormatter

<BarcodeFormatter> verwendet im Wesentlichen dieselben Darstellungsattribute wie <Barcode>.

Attribut	Beschreibung
Height	Höhe des Barcodes in EMU.
NoText	Unterdrückt bei `true` die zusätzliche lesbare Ausgabe des codierten Inhalts.
Rotate	Dreht den Barcode.
Symbology	Legt den Barcodetyp fest.
Width	Breite des Barcodes in EMU.

Der entscheidende Unterschied liegt nicht in der Darstellung, sondern in der Herkunft des codierten Inhalts:

Barcode
    → Inhalt wird systemseitig erzeugt

BarcodeFormatter
    → Inhalt wird aus den enthaltenen XML-Elementen aufgebaut

Typische Einsatzgebiete

<BarcodeFormatter> eignet sich beispielsweise für:

Internetadressen,
Versicherungsnummern,
Aktenzeichen,
kombinierte statische und dynamische Inhalte,
individuell zusammengesetzte QR-Codes,
technische Informationen für externe Folgeprozesse.

EpcBarcode

Zweck

Das XML-Element <EpcBarcode> erzeugt einen Barcode nach dem EPC-Standard.

Der erzeugte EPC-QR-Code kann mit einer geeigneten Banking-App eingelesen werden. Die im Barcode enthaltenen Zahlungsinformationen können dadurch zur Vorbelegung einer Überweisung verwendet werden.

Typische Inhalte sind:

Zahlungsempfänger,
IBAN,
BIC,
Betrag,
Verwendungszweck,
Referenz,
weitere Hinweise.

Grundsyntax

<Block>

    <Content>

        <EpcBarcode
            Version="1"
            Height="2000000"
            Encoding="UTF-8"
            Width="2000000"
            BicPath="custom.bic"
            IbanPath="custom.iban"
            AmountPath="custom.amount"
            PurposePath="custom.zweck"
            ReferencePath="custom.reference"
            UsagePath="custom.referenz"
            RecipientPath="custom.recipient"
            HintPath="custom.hint">
        </EpcBarcode>

    </Content>

</Block>

Die Zahlungsinformationen werden in diesem Beispiel vollständig aus Parametern der Dokumentvorlage gelesen.

Konstante und variable Werte

Für die meisten fachlichen Informationen stellt <EpcBarcode> jeweils zwei Attribute zur Verfügung:

ein Attribut mit der Endung Constant,
ein Attribut mit der Endung Path.

Constant

Ein Constant-Attribut enthält den zu verwendenden Wert direkt.

Beispiel:

<EpcBarcode
    IbanConstant="DE02120300000000202051"
    RecipientConstant="Musterkasse">
</EpcBarcode>

Path

Ein Path-Attribut enthält einen Variablenpfad.

Der tatsächliche Wert wird während der Dokumenterzeugung aus der angegebenen Variable gelesen.

Beispiel:

<EpcBarcode
    IbanPath="custom.iban"
    RecipientPath="custom.recipient">
</EpcBarcode>

Wichtig

Für dieselbe fachliche Information sollte entweder das zugehörige Constant-Attribut oder das zugehörige Path-Attribut verwendet werden.

Eine gleichzeitige Belegung beider Varianten ist zu vermeiden, da nicht eindeutig erkennbar ist, welcher Wert fachlich verwendet werden soll.

Attribute von EpcBarcode

Allgemeine Attribute

Attribut	Beschreibung
Version	Version des zu erzeugenden EPC-Barcodes.
Encoding	Zeichenkodierung des Barcodeinhalts, beispielsweise `UTF-8`.
Height	Höhe des Barcodes in EMU.
Width	Breite des Barcodes in EMU.
Rotate	Dreht den erzeugten Barcode.

Zahlungsinformationen

Fester Wert	Variablenpfad	Inhalt
AmountConstant	AmountPath	Zu übertragender Betrag
BicConstant	BicPath	BIC des Zahlungsempfängers
HintConstant	HintPath	Zusätzlicher Hinweis
IbanConstant	IbanPath	IBAN des Zahlungsempfängers
PurposeConstant	PurposePath	Zweck beziehungsweise fachliche Kennzeichnung der Zahlung
RecipientConstant	RecipientPath	Name des Zahlungsempfängers
ReferenceConstant	ReferencePath	Zahlungsreferenz
UsageConstant	UsagePath	Zusätzliche verwendungsbezogene Information

Hinweis

Welche Angaben für einen gültigen EPC-Barcode zwingend benötigt werden, hängt von den fachlichen Anforderungen und der verwendeten EPC-Version ab.

Der erzeugte Barcode sollte deshalb mit den tatsächlich vorgesehenen Banking-Apps getestet werden.

Vollständiges Beispiel mit Variablen

<Block>

    <Content>

        <EpcBarcode
            Version="1"
            Encoding="UTF-8"
            Height="2000000"
            Width="2000000"
            BicPath="custom.bic"
            IbanPath="custom.iban"
            AmountPath="custom.amount"
            PurposePath="custom.zweck"
            ReferencePath="custom.reference"
            UsagePath="custom.referenz"
            RecipientPath="custom.recipient"
            HintPath="custom.hint">
        </EpcBarcode>

    </Content>

</Block>

Vergleich der drei Barcodeelemente

Eigenschaft	Barcode	BarcodeFormatter	EpcBarcode
Sichtbare Barcodeausgabe	Ja	Ja	Ja
Verwendung innerhalb von `Content`	Ja	Ja	Ja
Systemseitig erzeugter Inhalt	Ja	Nein	Nein
Frei zusammensetzbarer Inhalt	Nein	Ja	Nein
Persistente Zuordnung zum Auftrag	Ja	Nein	Nein
Unterstützung von Rückläuferprozessen	Ja	Nicht automatisch	Nicht automatisch
EPC-Zahlungsstandard	Nein	Nicht automatisch	Ja
Variablen als Inhalt	Über Systemkontext	Ja	Über `*Path`-Attribute
Konstante Werte	Systemseitig	Über `<Text>`	Über `*Constant`-Attribute

Positionierung mit Frame

Die Attribute Height und Width bestimmen die Größe des Barcodes, nicht jedoch seine freie Position auf der Seite.

Für die Positionierung eines Barcodes kann innerhalb der <BlockProperties> ein <Frame> verwendet werden.

Vereinfachte Struktur:

<Block>

    <Content>

        <Barcode
            NoText="true"
            Symbology="QR"
            Height="2000000"
            Width="2000000">
        </Barcode>

    </Content>

    <BlockProperties>

        <Frame>

            ...

        </Frame>

    </BlockProperties>

</Block>

Über den Frame kann der zugehörige Block gezielt auf der Seite positioniert werden.

Developer-Tipp

Definieren Sie die Größe über Height und Width.

Verwenden Sie für die Positionierung des Barcodes vorzugsweise einen <Frame> innerhalb der <BlockProperties>.

Prüfen Sie anschließend sowohl die Vorschau als auch ein tatsächlich erzeugtes Testdokument.

Typische Fehler

Barcode außerhalb eines Content

Die Barcodeelemente erzeugen sichtbare Inhalte und gehören deshalb innerhalb eines <Content>.

Ungeeignete Größe

Ein zu kleiner Barcode kann von Scannern möglicherweise nicht zuverlässig erkannt werden.

Ein zu großer Barcode kann dagegen das Dokumentlayout beeinträchtigen.

Zu viele Daten

Insbesondere zweidimensionale Barcodes können umfangreiche Inhalte aufnehmen. Mit zunehmender Datenmenge wird der Barcode jedoch komplexer und benötigt gegebenenfalls eine größere Darstellungsfläche.

NoText falsch verstanden

NoText="true" entfernt nicht den codierten Inhalt.

Es unterdrückt lediglich dessen zusätzliche lesbare Darstellung unterhalb des Barcodes.

Constant und Path gleichzeitig verwendet

Bei <EpcBarcode> sollte für eine Information entweder der feste Wert oder ein Variablenpfad verwendet werden.

Ungetestete Drehung

Gedrehte Barcodes sollten mit dem vorgesehenen Scanverfahren getestet werden.

Position nur über Leerzeichen gesteuert

Die Position eines Barcodes sollte nicht durch vorangestellte Leerzeichen oder leere Blöcke erzeugt werden.

Hierfür sollte ein <Frame> innerhalb der <BlockProperties> verwendet werden.

Best Practices

Wählen Sie den Barcodetyp passend zum fachlichen Einsatzzweck.
Verwenden Sie <Barcode> für systemseitige Auftrags- und Rückläuferbarcodes.
Verwenden Sie <BarcodeFormatter> für individuell zusammengesetzte Inhalte.
Verwenden Sie <EpcBarcode> ausschließlich für EPC-konforme Zahlungsinformationen.
Legen Sie die Größe bewusst über Height und Width fest.
Positionieren Sie Barcodes über <Frame>.
Verwenden Sie die von der IntelliSense angebotenen Werte.
Testen Sie den Barcode mit dem tatsächlich vorgesehenen Scanner oder der vorgesehenen App.
Prüfen Sie bei <Barcode> die Auswirkungen auf nachgelagerte Rückläuferprozesse.
Vermeiden Sie unnötig große Datenmengen innerhalb eines Barcodes.
Verwenden Sie bei EPC-Daten entweder Constant oder Path für dieselbe Information.

Technischer Hinweis

Die drei Barcodeelemente verfolgen unterschiedliche technische Ziele:

Barcode
    → erzeugt einen systemseitigen Barcode
    → speichert die Zuordnung zum Auftrag
    → unterstützt Rückläufer- und Folgeprozesse

BarcodeFormatter
    → verarbeitet seine enthaltenen XML-Elemente
    → baut daraus einen individuellen Barcodeinhalt auf
    → erzeugt keine automatische Auftragszuordnung

EpcBarcode
    → verarbeitet definierte Zahlungsinformationen
    → erzeugt daraus einen EPC-konformen QR-Code
    → dient der Übernahme von Zahlungsdaten

Die sichtbare Darstellung wird bei allen drei Elementen durch die gewählte Symbologie, die Größe und gegebenenfalls die Drehung beeinflusst.

Zuletzt aktualisiert am 4. August 2026

Reference / Bausteine Hyperlink