Print document
See also: Print documents , Print document type , Print document category
Value resolver – Abstract
Purpose: Maps the data from one or more related objects to one of the Print documents applicable in the data context, and generates content from it in a selectable output format.
The Print document value resolver maps the data from one or more serializable objects to one of the Print documents applicable in the data context and returns the content generated from it in the selected Output format as a data object of the Content (content) type.
Based on the reference object of the Print document value resolver, an object of the 'Print' (core:Print) type is first created in a similar way to the interactive 'Print' (see also the 'Display Print XML' command in the 'Export' ribbon in relevant views). On one hand, the Print object contains general information about the applicable login context (especially user/user , company/currentOwner and language/locale). On the other hand, it contains the data of the printable objects (as a list in the printObjects field). As a rule, Print documents refer to selected content from the Print object, in which they access the structure of the Print XML via XPath expressions.
Background: What are 'printable objects':
All serializable objects are considered 'printable objects', i.e. objects that refer to a server-defined class and use its predefined data structure.
If the reference object of the Print document value resolver is a single serializable object, then its data appears as the only element of the list in the printObjects field.
If the reference object of the Print document value resolver is a list of objects, then the printObjects field lists the subset of serializable objects from that list.
►NOTE◄ While the interactive 'Printing' through the context of an overview ensures that all selected objects refer to the same class, the Print document value resolver can also be executed with a list of objects of different classes. If this option is used, this must be taken into account in an appropriate form when designing the Print documents and their Association criteria.
The selection of the print document used is made according to the following procedure:
If there is a value configuration for the Print document parameter, a 'Print document' entity is expected for its return value at runtime. The selection process via Association criteria and further parameters is then omitted.
Whether an explicitly provided 'Print document' entity has Association criteria assigned to it at all is just as irrelevant as whether any assigned Association criteria applies in context.
The data state of an explicitly provided 'Print document' entity can also be 'volatile' – i.e.: unsaved. It can therefore be different from the server-side state or not yet known there at all.
If the value configuration does not return a 'Print document' entity or one whose document type is not compatible with the selected Output format, the return value is 'No value' ($null). An error message will not occur!
Only if there is no value configuration for the Print document parameter, the conventional selection procedure with the following steps takes effect:
According to the all-matching principle, the Print documents applicable to the current context are determined by evaluating the Association criteria:
This applies to all Print documents with an assignment to at least one association criterion that applies in the current data context and for which read access exists in the current login context.
Assignments to a variable via the optional parameters Search key and Search value can be checked within the Association criteria.
If no print document exists or none of the configured Print documents are applicable, the Print document value resolver returns 'no value' (null).
As far as the configuration contains defaults for the partly optional parameters Document type, Mode and Category, the list of applicable Print documents is limited to 'suitable' candidates (for details see 'Configuration' below).
If none of the applicable Print documents meet all of the criteria used, no content is generated and the return value of the value resolver is 'no value' (null).
If several Print documents meet all criteria, the priority of the applicable association criteria (from step 1) determines the selection: The applicable association criterion with the highest value for the priority determines selection. If this still does not result in a clear assignment, the first print document from the list of candidates with the same priority is used.
If a print document that can be used for 'printing' can be identified according to this scheme, an attempt is then made to obtain the Output format parameterized in the configuration (see Print type) from this print document as a return value. The print document can take into account all contents from the data context contained in the Print XML, namely: printable objects (printObjects), User of session, Company of session and Current locale.
►NOTE◄ The options for the Output format basically correspond to the selection options in the ribbon under the Export tab and Print in the interactive flow:
Configuration
|
A selection for the Output format parameter is required. It defines the format of the generated action event content, i.e. the Print type for the export.
|
|
CAUTION
For the further configuration two variants are to be distinguished, which are described in the following sections.
Configuration with explicitly provided print document
|
As soon as there is a value configuration for the Print document parameter, all other parameters (except the mandatory Output format field) are hidden. The return value of the value configuration is expected to be an entity of the 'Print document' type, i.e. a specific definition for a print document (see Print documents). The Print document value resolver uses the possibly 'volatile' data status for the provided 'Print document' to generate the content for a document in the selected Output format from it – typically taking into account the data of the reference object. In the example on the right, a Variable value resolver provides the print document. Typically, this variable should be filled via a Search (Event action) for the Print documents entity, which contains suitable criteria (e.g. the name of the print document and possibly other properties). Assignment via an ID (id) statically defined by a Long value is not a really solid solution with regard to a Meta exchange between systems (e.g. test and production system) (see example below). ►NOTE◄ When selecting the Type, the selection of the correct 'Print document' option is crucial:
|
|
Configuration for the automatic assignment of a print document
|
The automatic assignment of a print document only takes effect if there is no value configuration for the Print document parameter. ►NOTE◄ An existing value configuration must be deleted via the context menu functions 'Cut' or 'Remove value' so that the configuration interface displays the selection parameters again. Assigning No value for the Print document parameter, on the other hand, is not useful for this purpose. |
|
|
The optional Document type parameter can be used to specify a particular Print document type with which the selected print document must comply. All Print documents must be uniquely assigned to a 'type' that can be selected here. Without any selection for the Document type, applicable print documents are accepted without regard to their 'type'. ►NOTE◄ Applicable Dynamic enum filters for the Print document type limit the selection during configuration, but not the applicability of print documents at runtime. ►NOTE◄ The 'GLS BOX' (GLS_BOX) type is available only if the relevant module is installed and licensed. |
|
|
A specification for the Mode parameter is required. It defines a requirement for the Print document mode that the selected print document must support. All Print documents must be clearly assigned to a 'mode' that can be selected here. The specification refers to whether the print document requires a single or multiple objects in the printObjects field of the specified Print XML (or Print object).
►NOTE◄ Applicable Dynamic enum filters for Print document mode limit the selection in the course of configuration, but not the usability of print documents at runtime. |
|
|
A Repeatable element for the Category parameter optionally allows to specify values from the dynamic enumeration Print document category. If at least one Category is selected, only Print documents whose 'category' corresponds to one of the values specified here are considered. As long as no Category is specified, applicable Print documents are accepted without regard to their 'category'. ►NOTE◄ Applicable Dynamic enum filters for the Print document category limit the selection during configuration, but not the applicability of print documents at runtime. |
|
|
The Search key and Search value parameters can be used in combination to specify by static texts that a variable with the name defined by Search key is assigned the text value from the Search value parameter before the selection of applicable print documents is executed based on Association criteria. Corresponding assignments can be examined within the Association criteria assigned for Print documents, e.g. to determine the exact match with the Search value using a Variable rule or to find a partial match in an Entity property rule using the Variable resolver (via Starts with, Ends with or Contains matcher). |
|
Examples
Simple example with direct provision of the print document
We have created a print document with the name 'HELLO_USER' and the Print document type 'RAW' and uploaded a text file with the following content to define the RAW output:
Hello {/core:Print/base:User/address/@name1}!This 'Print document' can be used in any context to generate a salutation text (e.g. for a note) for the logged-in user.
Runtime example:
Hello Karola!
The print document in question is meant to be used directly in the context of an event handling without taking Association criteria etc. into account, in order to output the document specified in the title of a note.
Configuration:
|
As a preparatory step, we perform a Search (Event action) to identify the relevant instance of the print document entity:
►NOTE◄
|
|
|
The 'Print document' identified via the myPrintDocument variable is subsequently used in a Print document resolver in the Print document parameter to define the content for the Title of a Show alert event action in conjunction with the 'Text' (TXT) Output format. The message below is defined as static text. ►NOTE◄ The Print document type 'RAW' provides plain text that can be printed directly. Runtime example:
►NOTE◄ In the example, the output is in English without regard to the Current locale. In the print document, one could access localized content for text sections. Alternatively, language-specific Print documents could be created and the Current locale could be included in the Search (Event action) to search for names like 'HELLO_USER_en' or 'HELLO_USER_fr'. |
|
More complex example with direct print document delivery
The simple filling of an 'XPath gap text' with information from the call context – as in the previous example – could be implemented even more 'directly' using the Template value resolver or a Concat strings, for example. But the application example was also kept untypically simple for the sake of clarity.
In practice, more complex print documents are typically used with the Print document type 'Jasper Report' (see Jaspersoft Studio integration), for which more complex Output formats (e.g. PDF) are then also supported.
The following configuration example demonstrates how, starting from a Search (Event action) with the 'Results list' mode, to let the user choose which print document to use to display context data in a new tab as a PDF.
Configuration:
|
Within an event handling the following event actions are concatenated:
|
|
Example with conventional selection of the print document
In the following example, the applicable print document is selected via the conventional mechanism, taking into account Association criteria and parameterized properties.
|
Triggered by a Custom action event, a Search (Event action) determines all Shipments with the working state 'Released' for a specific recipient. The recipient is informed by e-mail about the released shipments, receiving an HTML document in the e-mail attachment that reflects important information about a shipment in a standardized 'Delivery Note'. As shown in the example on the right, the 'Delivery Note' lists the names and values of all text attributes, numeric attributes and reference attributes in the shipment header to which a specific value is assigned. As values of a text attribute (TRACKING_LINK), a URL via Lobster Data Platform / Orchestration also appears here which provides further details on the tracking history of the respective shipment. |
|
The following example for the definition of a print document with the Document type 'RAW' illustrates how the source code for the HTML document shown above could be generated. Details on the syntax are discussed in the Template value resolver documentation, which uses the same logic to evaluate the data of a Print object via XPath expressions to generate a specific text output. Here, the source code for a complete HTML document is generated as text output that evaluates the relevant data of all Shipments that the printObjects field lists at runtime for the specific data context.
<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>►NOTE◄ Similar to this use case, XPath expressions could be used to generate the ZPL source code for a 'Zebra' label print with shipment data instead of an HTML document.
Configuration:
|
Within an event handling, the Search (Event action) is first executed to identify the relevant released Shipments.
|
|
Runtime example:
The e-mail shown below was generated with the Mail attachment 'details.htm' shown above:
►NOTE◄ The Preview above shows the e-mail body, which was also generated here in HTML format via the Print document value resolver. However, another print document was used here via the Category parameter with the selection 'Text module' (above: 'Delivery Note'), which uses a definition like the following:
<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>The HTML source code here does not need the html and body elements because they are provided in the e-mail.
In contrast to the HTML attachment, the print document for the mail body defines the tracking links as anchor elements (a), which could also be provided with an alternative label ('tracking link') if necessary.
►NOTE◄ For a public tracking link to work, a web service must be configured via Lobster_data to provide appropriate data.