Skip to content

OrderFlow Reporting Guide

Realtime Despatch Software Ltd

Document Version: 4.0.6

Document Built: 2020-03-04

This document and its content is copyright of Realtime Despatch Software Limited. All rights reserved.
You may not, except with our express written permission, distribute, publish or commercially exploit the content.
Any reproduction of part or all of the contents in any form is prohibited.

Labels

One of the primary uses of Jasper Reports in OrderFlow is in the creation of labels. Typically, labels will include barcodes to allow them to be scanned using a handheld terminal (HHT).

The most common types of labels produced in OrderFlow include the following:

  • product labels with barcodes
  • location labels
  • shipment courier labels
  • labels for licence plates
  • custom labels to support particular operational processes

Label Reports

As with despatch notes, labels are created in OrderFlow using using Jasper Reports. Labels can either be created using standalone reports, or using reports that are embedded into other processes. For examples, location labels would typically be created using standalone reports, while shipment courier labels are created as part of a 'Print Label' operation, normally invoked by a packer on the packing screen.

Standalone Labels

Standalone Labels are created using a combination of the following:

  • a data source, typically defined using SQL, to retrieve the data to be used to generate the label
  • optional parameters to restrict the data set
  • a Jasper Reports JRXML design

The JRXML design will typically include one or more barcodes.

An example of a standalone label is shown below:

Data Source

The data provider class is typically rtd.reports.dataprovider.SqlDataProvider, with a data source such as the following:

SELECT
   p.externalReference AS 'sku',
   p.barcode AS 'barcode',
   p.description AS 'description',
   c.name AS 'category'
FROM product p
LEFT JOIN product_category c ON p.categoryId = c.id
WHERE
p.deleted = 0
AND
p.activated is TRUE
#[include:text_string] AND
 (p.externalReference LIKE '%${literal:text_string}%'
OR
  p.barcode LIKE '%${literal:text_string}%'
OR
  p.description LIKE '%${literal:text_string}%')
#[include]
ORDER BY p.externalReference

The above example is for a product barcode generating report, which generates barcodes for labels matching the text_string parameter.

Design

The Jasper Report design for the label above includes the following.

<?xml version="1.0" encoding="UTF-8"?>
<jasperReport 
      xmlns="http://jasperreports.sourceforge.net/jasperreports" 
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
      xsi:schemaLocation="http://jasperreports.sourceforge.net/jasperreports 
                          http://jasperreports.sourceforge.net/xsd/jasperreport.xsd" 
      name="A5Label" pageWidth="290" pageHeight="290" orientation="Landscape" 
      whenNoDataType="NoDataSection" columnWidth="270" 
      leftMargin="10" rightMargin="10" topMargin="10" bottomMargin="10">
   <style name="default" isDefault="true" fontName="Verdana" fontSize="8">
      <box topPadding="0" leftPadding="0"/>
   </style>
   <style name="small" style="default" fontSize="7"/>
   <style name="header" vAlign="Middle" fontName="Verdana" fontSize="8"/>
   <field name="sku" class="java.lang.String">
      <fieldDescription><![CDATA[]]></fieldDescription>
   </field>
   <field name="barcode" class="java.lang.String">
      <fieldDescription><![CDATA[]]></fieldDescription>
   </field>
   <field name="description" class="java.lang.String">
      <fieldDescription><![CDATA[]]></fieldDescription>
   </field>
   <field name="category" class="java.lang.String">
      <fieldDescription><![CDATA[]]></fieldDescription>
   </field>
   <detail>
      <band height="270">
            ...
            <componentElement>
            <reportElement x="4" y="9" width="171" height="58">
               <printWhenExpression><![CDATA[!org.apache.commons.lang.StringUtils.isNumeric($F{barcode})]]></printWhenExpression>
            </reportElement>
            <jr:Code128 xmlns:jr="http://jasperreports.sourceforge.net/jasperreports/components" 
                        xsi:schemaLocation="http://jasperreports.sourceforge.net/jasperreports/components 
                                            http://jasperreports.sourceforge.net/xsd/components.xsd" 
                        moduleWidth="2.0" textPosition="none">
               <jr:codeExpression><![CDATA[$F{barcode}]]></jr:codeExpression>
            </jr:Code128>
         </componentElement>
      </band>
   </detail>
</jasperReport>

Notice of the use of the Code128 component; in this case as Code 128 barcode is being generated. More detail on the barcode is configuration is included in the 'Barcodes' section below.

Process-embedded Labels

Apart of the content, the main difference between standalone and embedded labels is in the data source. While standalone labels use a generic SQL-oriented data provider, embedded labels use data providers that only work within specific processes or interactions.

For shipment courier labels, some of the available data providers are shown below (note that the documentation for these applies as of OrderFlow 3.7.7):

Name Usage
rtd.courier.label.ParametersOnlyLabelDataProvider Used for labels for which uses only the supplied parameter values only. No Jasper Report Fields are used
rtd.courier.label.EmbeddedImageLabelDataProvider Labels with a single embedded label image, accessible using either 'labelImageFile' or 'labelImageStream' Parameter ($P{}) values.
rtd.courier.label.EmbeddedImagesLabelDataProvider Labels with one or more embedded images (usually, one per pacakge), accessible using either 'labelImageFile' or 'labelImageStream' Field ($F{}) values.
rtd.courier.label.IndexedShipmentOrPackageLabelDataProvider Labels for which the elements are defined within the Jasper Report, allowing for one or more field values.

Note that for all shipment courier labels, many of the parameter values are set up using the LabelDataPopulator class.

Name Usage
shipment The current shipment for which the label is being produced.
package If the label is being produced just for a single package, then identifies this package.
shipmentOrPackage Allows data that is common to shipments and packages to be referenced in a uniform way.
shipmentCourierOptions Represents courier options for the selected courier and service.
despatchNoteProperties Scoped properties from the 'despatch_note' property group.
sharedProperties Scoped properties from the 'courier_shared' property group.
addressProperties Scoped properties from the 'address' property group.
[courier]Properties Scoped properties from the courier-specific property group.
shipmentCourierProperties Represents courier-specific data that has been populated against the shipment.
despatchReference The shipment or package despatch reference.
countryLookup Can be used to look up the country name from the country code stored against the shipment.

An example JRXML file which uses EmbeddedImagesLabelDataProvider is shown below:

<?xml version="1.0" encoding="UTF-8"?>
<jasperReport xmlns="http://jasperreports.sourceforge.net/jasperreports" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://jasperreports.sourceforge.net/jasperreports http://jasperreports.sourceforge.net/xsd/jasperreport.xsd" name="4 by 6 label" pageWidth="288" pageHeight="432" columnWidth="288" leftMargin="0" rightMargin="0" topMargin="0" bottomMargin="0">
   <field name="labelImageFile" class="rtd.domain.DataFile"/>
   <field name="labelImageStream" class="java.io.InputStream"/>
   <detail>
      <band height="432">
         <image scaleImage="RetainShape" hAlign="Center" vAlign="Middle">
            <reportElement mode="Opaque" x="0" y="0" width="288" height="432" forecolor="#000000" backcolor="#FFFFFF"/>
            <imageExpression class="java.io.InputStream"><![CDATA[$F{labelImageStream}]]></imageExpression>
         </image>
      </band>
   </detail>
</jasperReport>

An example JRXML file which uses IndexedShipmentOrPackageLabelDataProvider is shown below:

<?xml version="1.0" encoding="UTF-8"?>
<jasperReport xmlns="http://jasperreports.sourceforge.net/jasperreports" 
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
   xsi:schemaLocation="http://jasperreports.sourceforge.net/jasperreports 
   http://jasperreports.sourceforge.net/xsd/jasperreport.xsd" name="4 by 6 label" 
   pageWidth="283" pageHeight="425" columnWidth="263" leftMargin="10" rightMargin="10" topMargin="10" bottomMargin="10">
   <parameter name="formattedDeliveryAddress" class="java.lang.String"/>
   <parameter name="contactName" class="java.lang.String"/>
   <parameter name="shipmentReference" class="java.lang.String"/>
   <parameter name="now" class="java.lang.String"/>
   <field name="despatchReference" class="java.lang.String"/>
   <field name="packageInfo" class="java.lang.String"/>
   <detail>
      <band height="400">
         <textField isStretchWithOverflow="true">
            <reportElement uuid="10aaa896-d7c9-4728-b2b9-adfeab764fd3" mode="Transparent" x="18" y="32" width="223" height="41" forecolor="#000000"/>
            <textElement textAlignment="Left" verticalAlignment="Bottom">
               <font size="15" isBold="false"/>
            </textElement>
            <textFieldExpression><![CDATA[$P{contactName}]]></textFieldExpression>
         </textField>
         <textField isStretchWithOverflow="true">
            <reportElement uuid="2b555a0d-f79e-4d3c-aa99-a04d0214de33" mode="Transparent" x="18" y="77" width="223" height="198" forecolor="#000000"/>
            <textElement textAlignment="Left" verticalAlignment="Top">
               <font size="15" isBold="false"/>
            </textElement>
            <textFieldExpression><![CDATA[$P{formattedDeliveryAddress}]]></textFieldExpression>
         </textField>
         <textField>
            <reportElement uuid="5d3281c1-52c6-434f-83f3-5ccc4a37777f" mode="Transparent" x="23" y="378" width="218" height="12"/>
            <textElement textAlignment="Right" verticalAlignment="Middle">
               <font size="9" isBold="false"/>
            </textElement>
            <textFieldExpression><![CDATA[$P{shipmentReference}]]></textFieldExpression>
         </textField>
         <componentElement>
            <reportElement uuid="57727cbf-0860-47de-bb41-3960b58a1eb4" x="18" y="285" width="223" height="42"/>
            <jr:Code128 xmlns:jr="http://jasperreports.sourceforge.net/jasperreports/components" xsi:schemaLocation="http://jasperreports.sourceforge.net/jasperreports/components http://jasperreports.sourceforge.net/xsd/components.xsd" moduleWidth="2.0" textPosition="none">
               <jr:codeExpression><![CDATA[$F{despatchReference}]]></jr:codeExpression>
            </jr:Code128>
         </componentElement>
         <textField pattern="">
            <reportElement uuid="475a6957-0faf-49f4-901d-d05ab295941c" x="23" y="347" width="218" height="12"/>
            <textElement verticalAlignment="Bottom" markup="html">
               <font size="7"/>
            </textElement>
            <textFieldExpression><![CDATA[$F{packageInfo}]]></textFieldExpression>
         </textField>
      </band>
   </detail>
</jasperReport>

Note that the packageInfo and despatchReference fields are generated using the field mapping:

<fieldmapper>
  <mappings>
    <mapping to="packageInfo">
      return 'Package ' + input.packageIndex + ' of ' + input.packageCount;
    </mapping>
    <mapping to="despatchReference">
      return input.shipmentOrPackage.despatchReference;
    </mapping>
  </mappings>
</fieldmapper>

Label Sizing and Printing

One of the most critical things to get right with labels is size.

JRXML work on the basis of a 72 pixel per inch representation. This can be used to determine the number of pixels for each dimension in your report.

For example, a 4 by 6 label will require a report that is 72 x 4 = 288 pixels wide, and 72 x 6 = 432 pixels in height.

In order to get the label to print correctly, the printer label stock settings will need to be checked to ensure that these match the actual dimensions of the label stock.

A typical routine for verifying the use of a label printer for printing labels will be as follows:

  • measure the label stock in each dimension, converting the measured values to inches.
  • multiply the number of inches to determine the required dimension for the JRXML.
  • create a simple standalone report for a label with these dimensions. Include in this report a barcode element, so that you can verify that the report and printer are set up correctly for barcode printing.
  • verify the printing of this label by running the report, then feeding the report to the printer.
  • ensure that the barcode appears to be appears to be crisp and free of jagged edges, and that it scans without any difficulty.

The printing step above can be done from the report output screen, by clicking on the 'Print' icon, as shown below.

Barcode label

Note that your browser will need to have Java applets enabled for the screen shown above to work.

Alternatively, you can download the printed report as a PDF document. Note, however, that printing a PDF output uses different image rendering and printing software from that typically used in OrderFlow operations, so a test of a PDF version of the document can only be regarded as a partial test.

Barcodes

Jasper Report has built-in support for barcode generation; a design tool such as iReport will easily allow you to embed a barcode such as the following into your report:

<jr:Code128 xmlns:jr="http://jasperreports.sourceforge.net/jasperreports/components" 
            xsi:schemaLocation="http://jasperreports.sourceforge.net/jasperreports/components 
                                http://jasperreports.sourceforge.net/xsd/components.xsd" 
            moduleWidth="2.0" 
            textPosition="none">
   <jr:codeExpression><![CDATA[$F{barcode}]]></jr:codeExpression>
</jr:Code128>

Depending on the length of the text, and the size of the barcode, the moduleWidth parameter may need to be adjusted to maike

Images

As with despatch notes, it is quite common to embed images onto labels. For example, the label itself may in its entirety contain a label image generated using a third party courier system. The Despatch Notes chapter contains details on how to embed images into Jasper Reports documents. The same discussion applies here: it is critical to get the image dimensions correct on the report so that the image does not need to scale, or if it does, scales in a way that does not result in any loss of printing quality.