Beim Erstellen von Dokumentvorlagen begegnen zwei Begriffe besonders häufig:

• Parameter
• Variablen

Obwohl beide eng zusammenarbeiten, erfüllen sie unterschiedliche Aufgaben.

Das Verständnis dieses Unterschieds erleichtert die Entwicklung und Wartung von Dokumentvorlagen erheblich.

Was ist ein Parameter?

Ein Parameter gehört immer zur Dokumentvorlage.

Er dient dazu, während der Dokumenterstellung einen Wert manuell durch den Mitarbeiter erfassen oder auswählen zu lassen.

Parameter sind somit keine Daten aus dem BK-Auftrag, sondern werden ausschließlich innerhalb der jeweiligen Dokumentvorlage definiert.

Ein Parameter besitzt:

• einen Namen,
• einen Datentyp,
• optional einen Standardwert,
• und den vom Mitarbeiter eingegebenen Wert.

Beispiele für Parameter:

• Name
• Ansprechpartner
• Freitext
• Datum
• Betrag
• Address

Der Parameter selbst erzeugt noch keine Ausgabe im Dokument.

Er stellt lediglich den eingegebenen Wert bereit.

Was ist eine Variable?

Eine Variable liest einen vorhandenen Wert und gibt ihn innerhalb des Dokuments aus oder verarbeitet ihn weiter.

Greift eine Variable auf einen Parameter zu, erfolgt dies über den Variablenstamm custom..

Beispiel:

<Variable Path="custom.Name">
</Variable>

Die Variable liest den Wert des Parameters Name und gibt dessen Inhalt im Dokument aus.

Das Zusammenspiel

Das Zusammenspiel lässt sich vereinfacht wie folgt darstellen:

Dokumentvorlage

        │

        ▼

Parameter

        │
        │ Mitarbeiter gibt Wert ein
        ▼

Variable

        │
        ▼

Dokument

Der Mitarbeiter füllt den Parameter.

Die Variable liest den Wert und verwendet ihn innerhalb der Dokumentvorlage.

Parameter gehören zur Dokumentvorlage

Parameter existieren ausschließlich innerhalb einer Dokumentvorlage.

Sie werden beispielsweise verwendet,

• um Freitexte einzugeben,
• Datumswerte auszuwählen,
• Beträge zu erfassen,
• Adressen zu übergeben,
• Auswahlfelder bereitzustellen.

Sie sind unabhängig von den Daten des BK-Auftrags.

BK-Auftragsdaten sind keine Parameter

Daten des BK-Auftrags werden nicht über Parameter bereitgestellt.

Sie stehen direkt als Variablen zur Verfügung.

Beispielsweise:

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

oder

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

Hier erfolgt der Zugriff unmittelbar über den entsprechenden Variablenstamm.

Es ist kein Parameter erforderlich.

Variablenstämme

Eine Variable greift immer über einen Variablenstamm auf ihren Wert zu.

Je nach Herkunft der Daten unterscheiden sich diese.

Beispiele:

Weitere Variablenstämme werden im Artikel Variable beschrieben.

Address als Beispiel

Ein Parameter kann auch komplexe Daten enthalten.

Ein Address-Parameter besteht beispielsweise aus mehreren Eigenschaften.

Address

├── Titel
├── Name
├── Straße
├── PLZ
└── Ort

Diese Eigenschaften können anschließend über eine Variable ausgegeben werden.

<Variable Path="address.name">
</Variable>

Parameter zwischen Bausteinen übergeben

Parameter können auch an Dokumentbausteine übergeben werden.

Hierfür wird das XML-Element <RefParam> verwendet.

Dadurch lassen sich wiederverwendbare Dokumentbausteine mit unterschiedlichen Werten aufrufen.

Parameter oder Variable?

Als Faustregel gilt:

Typische Fehler

Parameter mit BK-Auftragsdaten verwechseln

Parameter gehören ausschließlich zur Dokumentvorlage.

Daten des BK-Auftrags werden direkt über entsprechende Variablenstämme, beispielsweise source., gelesen.

Parameter direkt ausgeben wollen

Ein Parameter erzeugt selbst keine Ausgabe.

Er muss immer über eine Variable gelesen werden.

Beispiel:

<Variable Path="custom.Name">
</Variable>

Falschen Variablenstamm verwenden

Für Parameter wird der Variablenstamm custom. verwendet.

Ein anderer Variablenstamm greift auf eine andere Datenquelle zu.

Best Practices

• Parameter nur für Werte verwenden, die der Mitarbeiter eingeben oder auswählen soll.
• Aussagekräftige Parameternamen verwenden.
• Für die Ausgabe immer eine Variable verwenden.
• BK-Auftragsdaten direkt über den passenden Variablenstamm verwenden.
• Wiederverwendbare Dokumentbausteine über <RefParam> parametrisieren.

Developer-Tipp

Ein einfacher Merksatz lautet:

Parameter = Eingabe

Variable = Ausgabe

Der Mitarbeiter füllt den Parameter.

Die Variable liest anschließend dessen Wert und gibt ihn im Dokument aus.

Siehe auch

• Variable
• RefParam
• Reference
• Dokumentbausteine