Druckdokument
Siehe auch: Druckdokumente, Druckdokumenttyp, Druckdokumentkategorie
Wertauflöser - Kurzfassung
Zweck: Bildet die Daten von einem oder mehreren Bezugsobjekten auf ein explizit bereitgestelltes oder eines der im Datenkontext anwendbaren Druckdokumente ab und erzeugt daraus Inhalt in einem wählbaren Ausgabeformat.
Der Druckdokument-Wertauflöser bildet die Daten von einem oder mehreren serialisierbaren Objekten auf ein explizit bereitgestelltes oder eines der im Datenkontext anwendbaren Druckdokumente ab und gibt den daraus im gewählten Ausgabeformat erzeugten Inhalt als Datenobjekt des Typs Aktionsereignis-Inhalt (content) zurück.
Ausgehend vom Bezugsobjekt des Druckdokument-Wertauflösers wird analog zum interaktiven "Drucken" zunächst ein Objekt vom Typ "Drucken" (core:Print) erzeugt (s. a. Befehl "Druck-XML anzeigen" im "Export"-Ribbon in relevanten Views). Das Print-Objekt enthält einerseits allgemeine Informationen zum anwendbaren Anmeldekontext (v. a. Benutzer/user , Firma/currentOwner und Sprache/locale). Andererseits beinhaltet es die Daten der druckbaren Objekte (als Liste im Feld printObjects). In der Regel beziehen sich Druckdokumente auf ausgewählte Inhalte aus dem Print-Objekt, in dem sie über XPath-Ausdrücke auf die Struktur des Druck-XML zugreifen.
Hintergrund: Was sind "druckbare Objekte"?
Als "druckbare Objekte" werden alle serialisierbaren Objekte betrachtet, also solche, die sich auf eine serverseitig definierte Klasse beziehen und deren vordefinierte Datenstruktur verwenden.
Handelt es sich beim Bezugsobjekt des Druckdokument-Wertauflösers um ein einzelnes serialisierbares Objekt, dann erscheinen dessen Daten als einziges Element der Liste im Feld printObjects.
Handelt es sich beim Bezugsobjekt des Druckdokument-Wertauflösers um eine Liste von Objekten, dann listet das Feld printeObjects die Teilmenge der serialisierbaren Objekte aus dieser Liste auf.
►HINWEIS◄ Während beim interaktiven "Drucken" durch den Kontext einer Übersicht sichergestellt ist, dass sich alle selektierten Objekte auf dieselbe Klasse beziehen, kann der Druckdokument-Wertauflöser auch mit einer Liste von Objekten unterschiedlicher Klassen ausgeführt werden. Sofern von dieser Möglichkeit Gebrauch gemacht wird, ist dies bei der Gestaltung der Druckdokumente und deren Zuordnungskriterien in geeigneter Form zu berücksichtigen.
Die Auswahl des effektiv verwendeten Druckdokuments erfolgt nach folgendem Schema:
Wenn eine Wert-Konfiguration für den Parameter Druckdokument vorliegt, wird für dessen Rückgabewert zur Laufzeit eine "Druckdokument"-Entität erwartet. Der Auswahlprozess über Zuordnungskriterien und weitere Parameter entfällt dann.
Ob einer explizit bereitgestellten "Druckdokument"-Entität überhaupt Zuordnungskriterien zugewiesen sind, ist ebenso unerheblich wie ob zugewiesene Zuordnungskriterien im Kontext zutreffen.
Der Datenstand einer explizit bereitgestellten "Druckdokument"-Entität kann auch "volatil" - also: ungespeichert - sein. Sie kann also gegenüber dem serverseitigen Stand geändert oder dort noch überhaupt nicht bekannt sein.
Liefert die Wert-Konfiguration keine "Druckdokument"-Entität oder eine, deren Dokumenttyp nicht mit dem gewählten Ausgabeformat kompatibel ist, ist der Rückgabewert "Kein Wert" ($null). Eine Fehlermeldung tritt nicht auf!
Nur wenn keine Wert-Konfiguration für den Parameter Druckdokument vorliegt, greift das konventionellen Auswahlverfahren mit den folgenden Schritten:
Nach dem all-matching-Prinzip werden durch die Auswertung von Zuordnungskriterien die für den aktuellen Kontext anwendbaren Druckdokumente ermittelt:
Dies betrifft alle Druckdokumente mit einer Zuweisung zu mindestens einem Zuordnungskriterium, das im aktuellen Datenkontext zutrifft und für das im aktuellen Anmeldekontext Lesezugriff besteht.
Zuweisungen zu einer Variablen über die optionalen Parameter Suchschlüssel und Suchwert können innerhalb Zuordnungskriterien geprüft werden.
Falls kein Druckdokument existiert oder keines der konfigurierten Druckdokumente anwendbar ist, gibt der Druckdokument-Wertauflöser "kein Wert" (null) zurück.
Soweit die Konfiguration Vorgaben für die teilweise optionalen Parameter Dokumenttyp, Modus und Kategorie beinhaltet, wir die Liste der anwendbaren Druckdokumente auf "geeignete" Kandidaten eingeschränkt (Detail s. "Konfiguration").
Entspricht keines der anwendbaren Druckdokumente sämtlichen verwendeten Kriterien, wird kein Inhalt erzeugt und der Rückgabewert des Wertauflösers ist "kein Wert" (null).
Falls mehrere Druckdokumente sämtliche Kriterien erfüllen, gibt die Priorität der zutreffenden Zuordnungskriterien (aus dem 1. Schritt) den Ausschlag: Das zutreffende Zuordnungskriterium mit dem höchsten Wert für die Priorität bestimmt die Auswahl. Ergibt auch das noch keine eindeutige Zuordnung, wird das erste Druckdokument aus der Liste der gleich priorisierten Kandidaten verwendet.
Sofern nach diesem Schema ein für den "Druck" anwendbares Druckdokument identifiziert werden konnte, wird anschließend versucht, aus diesem Druckdokument das in der Konfiguration parametrierte Ausgabeformat (s. Drucktyp) als Rückgabewert zu gewinnen. Das Druckdokument kann dabei alle Inhalte aus dem Datenkontext berücksichtigen, die im Druck-XML enthalten sind, namentlich: druckbare Objekte (printObjects), Benutzer der Session, Firma der Session und Aktuelle Sprache.
►HINWEIS◄ Die Optionen für das Ausgabeformat entsprechen grundsätzlich den Auswahlmöglichkeiten im Ribbon unter "Export/Druck" im interaktiven Ablauf:
Konfiguration
|
Eine Auswahl für den Parameter Ausgabeformat ist Pflicht. Sie legt das Format des erzeugten Aktionsereignis-Inhalts, also den Drucktyp für den Export fest.
|
|
ACHTUNG
Für die weitere Konfiguration sind zwei Varianten zu unterscheiden, die in den folgenden Abschnitten beschrieben werden.
Konfiguration mit explizit bereitgestelltem Druckdokument
|
Sobald eine Wert-Konfiguration für den Parameter Druckdokument vorliegt, werden alle weiteren Parameter (außer dem Pflichtfeld Ausgabeformat) ausgeblendet. Als Rückgabewert der Wert-Konfiguration wird eine Entität des Typs "Druckdokument" erwartet, also eine konkrete Definition für ein Druckdokument (s. Druckdokumente). Der Druckdokument-Wertauflöser verwendet den ggf. "volatilen" Datenstand für das bereitgestellte "Druckdokument", um daraus - typischerweise unter Berücksichtigung der Daten des Bezugsobjekts - den Inhalt für ein Dokument im ausgewählten Ausgabeformat zu erzeugen. Im Beispiel rechts soll ein Variable-Wertauflöser das Druckdokument bereitstellen. Typischerweise sollte man diese Variable über eine Suche (Ereignisaktion) für die Entität Druckdokumente befüllen, die geeignete Kriterien (z. B. den Namen des Druckdokuments und ggf. weitere Eigenschaften) enthält. Die Zuweisung über eine durch einen Long-Wert statisch festgelegte ID (id) ist mit Blick auf einen Meta Exchange zwischen Systemen (z. B. Test- und Produktivsystem) keine wirklich solide Lösung (s. Beispiel unten). ►HINWEIS◄ Bei der Auswahl für den Typ ist die Auswahl der richtigen "Druckdokument"-Option entscheidend:
|
|
Konfiguration für die automatische Zuweisung eines Druckdokuments
|
Die automatische Zuweisung eines Druckdokuments greift nur, wenn für den Parameter Druckdokument keine Wert-Konfiguration vorliegt. ►HINWEIS◄ Eine bestehende Wert-Konfiguration muss über die Kontextmenüfunktionen "Ausschneiden" oder "Wert entfernen" gelöscht werden, damit die Konfigurationsoberfläche die Auswahlparameter wieder anzeigt. Das Zuweisen von Kein Wert für den Parameter Druckdokument ist dagegen nicht zielführend für diesen Zweck. |
|
|
Der optionale Parameter Dokumenttyp kann verwendet werden, um einen bestimmten Druckdokumenttyp festzulegen, dem das auszuwählende Druckdokument entsprechen muss. Alle Druckdokumente müssen eindeutig einem hier auswählbaren "Typ" zugeordnet sein. Ohne Auswahl für den Dokumenttyp werden anwendbare Druckdokumente ohne Rücksicht auf ihren "Typ" akzeptiert. ►HINWEIS◄ Anwendbare Dynamische Aufzählungsfilter für den Druckdokumenttyp schränken die Auswahl im Zuge der Konfiguration ein, nicht aber die Anwendbarkeit von Druckdokumenten zur Laufzeit. ►HINWEIS◄ Der Typ "GLS BOX" (GLS_BOX) ist nur verfügbar, wenn das betreffende Modul installiert und lizenziert ist. |
|
|
Eine Angabe für den Parameter Modus ist Pflicht. Sie definiert eine Anforderung für den Druckdokumentmodus, den das auszuwählende Druckdokument unterstützen muss. Alle Druckdokumente müssen eindeutig einem hier auswählbaren "Modus" zugeordnet sein. Die Angabe bezieht sich darauf, ob das Druckdokument im printObjects-Feld des übergebenen Druck-XML (bzw. Print-Objekts) ein einzelnes oder multiple Objekte erwartet.
►HINWEIS◄ Anwendbare Dynamische Aufzählungsfilter für den Druckdokumentmodus schränken die Auswahl im Zuge der Konfiguration ein, nicht aber die Anwendbarkeit von Druckdokumenten zur Laufzeit. |
|
|
Ein Wiederholendes Element für den Parameter Kategorie ermöglicht optional die Angabe von Werten aus der Dynamischen Aufzählung Druckdokumentkategorie. Sofern mindesten eine Kategorie ausgewählt ist, werden nur Druckdokumente berücksichtigt, deren "Kategorie" einem der hier angegebenen Werte entspricht. Solange keine Kategorie angegeben ist, werden anwendbare Druckdokumente ohne Rücksicht auf ihre "Kategorie" akzeptiert. ►HINWEIS◄ Anwendbare Dynamische Aufzählungsfilter für die Druckdokumentkategorie schränken die Auswahl im Zuge der Konfiguration ein, nicht aber die Anwendbarkeit von Druckdokumenten zur Laufzeit. |
|
|
Die Parameter Suchschlüssel und Suchwert können in Kombination genutzt werden, um durch statische Texte anzugeben, dass einer Variablen mit dem per Suchschlüssel definierten Namen der Textwert aus dem Parameter Suchwert zugeordnet wird, bevor die Auswahl der anwendbaren Druckdokumente anhand von Zuordnungskriterien ausgeführt wird. Entsprechende Zuweisungen können innerhalb der für Druckdokumente zugewiesenen Zuordnungskriterien untersucht werden, etwa um mit einer Variablenregel die exakte Übereinstimmung mit dem Suchwert festzustellen oder in einer Objekt-Feld-Regel mit dem Variable-Wertauflöser (per Beginnt mit, Endet mit oder Enthält-Matcher) eine teilweise Übereinstimmung. |
|
Beispiele
Einfaches Beispiel mit direkter Bereitstellung des Druckdokuments
Wir haben ein Druckdokument mit dem Namen "HELLO_USER" und dem Druckdokumenttyp "RAW" angelegt und zur Definition der RAW-Ausgabe eine Textdatei mit folgendem Inhalt hochgeladen:
Hello {/core:Print/base:User/address/@name1}!Dieses "Druckdokument" kann in einem beliebigen Kontext eingesetzt werden, um einen Anrede-Text (z. B. für einen Hinweis) für den angemeldeten Benutzer zu erzeugen.
Laufzeitbeispiel:
Hello Karola!
Das betreffende Druckdokument soll im Kontext einer Ereignisbehandlung ohne Berücksichtigung von Zuordnungskriterien etc. direkt herangezogen werden, um den im Titel eines Hinweises auszugeben.
Konfiguration:
|
Als vorbereitenden Schritt führen wir eine Suche (Ereignisaktion) aus, um die relevante Instanz der Druckdokument-Entität zu identifizieren:
►ANMERKUNGEN◄
|
|
|
Das über die Variable myPrintDocument identifizierte "Druckdokument" wird anschließen in einem Druckdokument-Wertauflöser im Parameter Druckdokument verwendet, um in Verbindung mit dem Ausgabeformat "Text" (TXT) den Inhalt für den Titel einer Hinweis anzeigen-Ereignisaktion zu definieren. Die Meldung unterhalb ist als statischer Text definiert. ►HINWEIS◄ Der Druckdokumenttyp "RAW" liefert hier Klartext, der direkt ausgegeben werden kann. Laufzeitbeispiel:
►ANMERKUNG◄ Im Beispiel erfolgt die Ausgabe ohne Rücksicht auf die die Aktuelle Sprache in Englisch. Im Druckdokument könnten man zwar auf lokalisierte Inhalte für Textabschnitte zugreifen. Alternativ könnte man auch sprachspezifische Druckdokumente erstellen und die Aktuelle Sprache bei der Suche (Ereignisaktion) einbeziehen, um nach Namen wie "HELLO_USER_en" oder "HELLO_USER_fr" zu suchen. |
|
Komplexeres Beispiel mit direkter Bereitstellung des Druckdokuments
Das reine Ausfüllen eines "XPath-Lückentexts" mit Informationen aus dem Aufrufkontext - wie im vorherigen Beispiel - könnte man z. B. über den Vorlage-Wertauflöser oder eine Textverkettung noch "direkter" umsetzen. Aber das Anwendungsbeispiel war zugunsten der Übersichtlichkeit auch untypisch einfach gehalten.
In der Praxis kommen typischerweise aufwändigere Druckdokumente mit dem Druckdokumenttyp "Jasper Report" (s. Integration Jaspersoft Studio) zum Einsatz, für die dann auch komplexere Ausgabeformate (z. B. PDF) unterstützt werden.
Das folgende Konfigurationsbeispiel demonstriert, wie man ausgehend von einer Suche (Ereignisaktion) mit dem Modus "Ergebnisliste" dem Benutzer die Wahl überlässt, welches Druckdokument verwendet werden soll, um Kontextdaten in einem neuen Tab als PDF anzuzeigen.
Konfiguration:
|
Innerhalb einer Ereignisbehandlung werden folgende Ereignisaktion verkettet:
|
|
Beispiel mit konventioneller Auswahl des Druckdokuments
Im folgenden Beispiel wird das anwendbare Druckdokument über den konventionellen Mechanismus unter Berücksichtigung von Zuordnungskriterien und parametrierten Eigenschaften ausgewählt.
|
Ausgelöst durch ein Eigenes Aktionsevent soll eine Suche (Ereignisaktion) alle Sendungen mit dem Arbeitsstatus "Freigegeben" für einen bestimmten Empfänger ermitteln. Der Empfänger soll per E-Mail über die freigegebenen Sendungen informiert werden und dabei im E-Mail-Anhang ein HTML-Dokument erhalten, das wichtige Informationen zu einer Sendung in einem standardisierten "Lieferschein" widerspiegelt. Wie im Beispiel rechts gezeigt, soll der "Lieferschein" dabei die Namen und Werte von allen Textattributen, Numerischen Attributen und Referenzattribute im Sendungskopf tabellarisch auflisten, denen ein konkreter Wert zugewiesen ist. Als Werte eines Textattributs (TRACKING_LINK) erscheint hier auch eine URL über die Lobster Data Platform / Orchestration weitere Details zur Tracking-Historie der jeweiligen Sendung bereitstellt. |
|
Das folgende Beispiel für die Definition eines Druckdokuments mit dem Dokumententyp "RAW" soll veranschaulichen, wie der Quelltext für das oben angezeigte HTML-Dokument erzeugt werden könnte. Details zur Syntax werden in der Dokumentation für den Vorlage-Wertauflöser erörtert, der nach derselben Logik die Daten eines Print-Objekts über XPath-Ausdrücke auswertet, um eine bestimmte Textausgabe zu generieren. Hier soll der Quelltext für ein komplettes HTML-Dokument als Textausgabe erzeugt werden, das die relevanten Daten aller Sendungen auswertet, die das Feld printObjects zur Laufzeit für den konkreten Datenkontext auflistet.
<html><body><h2>{$r(de.lobster.scm.base.bto.workingstate.WorkingState,RELEASED)}</h3><hr>{$foreach({//printObjects/*})<h3>{$r(de.lobster.scm.print.PrintDocumentKind,DELIVERY_NOTE)} #{@id} - {$with({attributes/shp:ShipmentDate/value[@dateType='ARRIVAL_PLANNED']/date}){$date(dd.MM.yy,{@start};{@timeZone})}}</h3><style> table \{border: 1px solid grey; font-family: Courier\} tr:nth-child(odd) \{background-color: #DDDDDD;\} td:nth-child(1) \{background-color: grey; color: white; text-align:right\}</style><table> {$foreach({attributes/shp:ShipmentText/value[textValue/text()!='']})<tr><td>{@textType}</td><td>{textValue}</td></tr>} {$foreach({attributes/shp:ShipmentNumericValue/value[@value>0]})<tr><td>{@numericValueType}</td><td>{@value} {@unit}</td></tr>} {$foreach({attributes/shp:ShipmentReference/value[@reference!='']})<tr><td>{@referenceType}</td><td>{@reference}</td></tr>}</table>}</body></html>►HINWEIS◄ Analog zu diesem Anwendungsfall könnten XPath-Ausdrücke verwendet werden, um anstelle eines HTML-Dokuments den ZPL-Quelltext für einen "Zebra"-Etikettendruck mit Sendungsdaten zu erzeugen.
Konfiguration:
|
Innerhalb einer Ereignisbehandlung wird zunächst die Suche (Ereignisaktion) ausgeführt, um die relevanten freigegebenen Sendungen zu identifizieren.
|
|
Laufzeitbeispiel:
Die nachfolgend abgebildete E-Mail wurde mit dem oben abgebildeten E-Mail-Anhang "details.htm" erzeugt:
►ANMERKUNG◄ Die oben abgebildete Vorschau zeigt den E-Mail-Body, der hier ebenfalls im HTML-Format über den Druckdokument-Wertauflöser erzeugt wurde. Allerdings wurde dabei über den Kategorie-Parameter mit der Auswahl "Textbaustein" (oben: "Lieferschein") ein anderes Druckdokument herangezogen, das eine Definition wie die folgende verwendet:
<h3>{$r(de.lobster.scm.base.bto.workingstate.WorkingState,RELEASED)}</h3><hr><ul>{$foreach({//printObjects/*})<li>{$r(de.lobster.scm.print.PrintDocumentKind,DELIVERY_NOTE)} #{@id}- {$with({attributes/shp:ShipmentDate/value[@dateType='ARRIVAL_PLANNED']/date}){$date(yyyy-MM-dd,{@start};{@timeZone})}}- {$with({attributes/shp:ShipmentText/value[@textType='TRACKING_LINK']})<a HREF="{textValue}">{textValue}</a>}</li>}</ul><hr>Der HTML-Quelltext kommt hier ohne die Elemente html und body aus, da diese im E-Mail bereitgestellt werden.
Im Unterschied zum HTML-Anhang definiert das Druckdokument für den Mail-Body die Tracking-Links als Anker-Elemente (a), die ggf. auch mit einer alternativen Beschriftung ("Tracking-Link") versehen werden könnten.
►HINWEIS◄ Damit ein öffentlicher Tracking-Link funktioniert, muss per Lobster_data ein Web-Service konfiguriert werden, der geeignete Daten bereitstellt.