Customizer Manual Report

Definition
Part of TPiSCAN Documentation
by Nicolas Gabron

Software Development
Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 1 of 68
Last update Nicolas Gabron 2014-10-15 06:48 PM
Customizer Manual Report Definition

Legal notice
All brand and product names mentioned in this document are trademarks of their respective
owners.
This document was written for internal use at Wincor-Nixdorf and is not intended for direct
distribution to customers.
The reproduction, transmission or use of this document or its contents is not permitted without
express authority. Offenders will be liable for damages. All rights, including rights created by patent
grant or registration of a utility model or design, are reserved.
Delivery subject to availability; technical modifications possible.

Copyright ©Wincor Nixdorf International GmbH, 2013

Software Solutions
Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 2 of 68
Customizer Manual Report Definition Contents

Contents
0 Document History ................................................................................................................ 4
1 Introduction .......................................................................................................................... 5
2 Report Definition .................................................................................................................. 6
2.1 Global Properties – Element reportDefinition ........................................................ 9
2.2 Input Fields – Element inputs....................................................................................... 9
2.2.1 Time Period and Precision – Element timePeriodInput ................................. 10
2.2.2 One Currency – Element currencyInput ........................................................... 14
2.2.3 One Store – Element storeInput........................................................................ 15
2.2.4 One Lane – Element storeLaneInput ................................................................ 16
2.2.5 One Attendant – Element storeAttendantInput ............................................. 18
2.2.6 One Lane, One Attendant – Element storeLaneAttendantInput................... 19
2.2.7 One Zone – Element zoneInput .......................................................................... 20
2.2.8 Several Stores – Element storeListInput ....................................................... 22
2.2.9 Several Lanes – Element storeLaneListInput ................................................ 23
2.2.10 Several Attendants – Element storeAttendantListInput ......................... 24
2.2.11 Several Zones – Element zoneListInput....................................................... 26
2.2.12 Integer Value – Element integerInput .......................................................... 27
2.3 SQL Query – Element sqlQuery .................................................................................. 28
2.3.1 Input Values – Element inputValues ................................................................. 28
2.3.2 Conditions – Elements ifInputValue and ifDatabase .................................. 31
2.4 Data Sheet – Element dataSheet ................................................................................ 33
2.4.1 Columns – Element column .................................................................................. 34
2.5 Charts – Element charts ............................................................................................. 38
2.5.1 Pie Chart – Element pieChart3d ......................................................................... 38
2.5.2 General Line Chart – Element xyLineChart ....................................................... 40
2.5.3 Bar Chart – Element barChart............................................................................. 43
2.5.4 Chronological Line Chart – Element timeSeriesChart .................................... 47
3 Translations ....................................................................................................................... 52
3.1 Static Parts of User Interface ....................................................................................... 52
3.2 Dynamic Parts of User Interface .................................................................................. 54
3.3 Values for Lists, Data Sheets, and Charts ................................................................... 58
4 Deployment ........................................................................................................................ 61
4.1 Static Deployment ......................................................................................................... 61
4.2 Dynamic Deployment .................................................................................................... 63
5 Summary ............................................................................................................................ 65
6 Appendix ............................................................................................................................ 67
6.1 Differences between Derby, MySQL and ORACLE ..................................................... 67

Software Solutions
Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 3 of 68
Customizer Manual Report Definition Document History

0 Document History
V Date Author Change

1 06-JUN-2013 Nicolas Gabron Initial version

2 14-JUN-2013 Nicolas Gabron Review results integrated

3 15-OCT-2014 Nicolas Gabron Appendix with differences between Derby, MySQL and
Oracle added; typos corrected

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 4 of 68
Customizer Manual Report Definition Introduction

1 Introduction
Beginning with version 8.2.0, TPiSCAN contains two new reporting modules in the web
applications Store and Enterprise Manager. The new web modules are called Report Execution
and Report Maintenance
The web module Report Execution allows the selection of a report from a list. Afterwards the
parameter of the report can be changed and the report can be executed. The result can be
displayed as data sheet or as chart.
The web module Report Maintenance allows the upload and deployment of changed or new
reports to the headquarters or a set of stores. This web module is very similar to the well-known
web modules Catalog Maintenance, Text Maintenance and Cash Settings Maintenance.
The reports are completely configurable. All texts including values read from the database can be
translated. The reports rely on the reworked statistics database model. Up to now, new reports can
only be created manually. Each report consists of one configuration file (XML) defining the report
itself and one configuration file (keyword value list) with translations for each supported language.
All reports have to be packed together in a ZIP file.
This document shall enable customizers and administrators to create, correct, extend, test, and
deploy reports for the new reporting modules of TPiSCAN version 8.2.0 and newer. To do so,
these persons should have solid knowledge of the basic technologies XML and SQL including
suitable tools. These persons should also be familiar with the statistics data produced by
TPiSCAN. Last but not least, these persons should have a good understanding of the expectations
of the future users of the reports. What do the users want to see? How do they want to influence
the data shown?
The new reporting provides a lot of building blocks that can be used very flexibly to realize reports.
Chapter 2 describes the report definition in detail. It contains a lot of screen shots, diagrams, and
examples.
Chapter 3 describes the translation of the user interface and the values shown in the data sheet or
in the charts. It also contains some screen shots and examples.
Chapter 4 roughly describes how a new or corrected report definition is deployed, so that it can be
used in the Enterprise or Store Manager.
Chapter 5 contains a summary of all steps necessary to create and test a new report definition.
It should be kept in mind that TPiSCAN is no POS application. If precise financial figures shall be
presented in a report, the POS application is responsible. TPiSCAN provides data about
operations that are under its control like attendant requests, POS calls, and interactions with
peripheral devices it controls.
This document does not explain the data model of the TPiSCAN statistics database. It also does
not describe how to figure out SQL queries to efficiently extract the desired data from the
database. The TPiSCAN team will assist on request.

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 5 of 68
Customizer Manual Report Definition Report Definition

2 Report Definition
Each report is defined by one XML configuration file describing all parts of the report except the
translations. The SQL query necessary to gather data from the statistics database is embedded in
the XML file and can be enriched by XML elements.
Here is a complete example for a simple report that shows the number of bulky items sold per hour
or per day for the current week or the last week and for a selectable store. It shall give a first
impression of the report definition. All details are explained in the following chapters. The
embedded SQL query is marked in red.
<?xml version="1.0" encoding="UTF-8"?>
<reportDefinition version="1.0.0" name="BulkyItems" level="enterpriseAndStore"
expert="false" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="ReportConfig.xsd">
<inputs>
<timePeriodInput name="timePeriodInput">
<timePeriod default="currentWeek" values="currentWeek lastWeek"/>
<startTimestamp/>
<endTimestamp/>
<precision default="oneDay" values="oneHour oneDay"/>
</timePeriodInput>
<storeInput name="storeInput">
<storeName/>
</storeInput>
</inputs>
<sqlQuery>
SELECT MIN(TIMEPERIOD.STARTTIME) AS STARTTIME,
MAX(TIMEPERIOD.ENDTIME) AS ENDTIME,
SUM(CASE WHEN GENERALSTATISTICS.BULKYITEMCOUNTER IS NULL THEN 0 ELSE
GENERALSTATISTICS.BULKYITEMCOUNTER END) AS BULKYITEMCOUNTER
FROM TIMEPERIOD
LEFT OUTER JOIN GENERALSTATISTICS ON TIMEPERIOD.TIMEPERIODID =
GENERALSTATISTICS.TIMEPERIODID
LEFT OUTER JOIN LANE ON GENERALSTATISTICS.LANEID = LANE.LANEID
LEFT OUTER JOIN STORE ON LANE.STOREID = STORE.STOREID
WHERE TIMEPERIOD.STARTTIME &gt;=
<inputValue name="startTimestamp" input="timePeriodInput"/>
AND TIMEPERIOD.STARTTIME &lt;=
<inputValue name="endTimestamp" input="timePeriodInput"/>
AND STORE.NAME =
<inputValue name="storeName" input="storeInput"/>
<ifInputValue name="precision" input="timePeriodInput" matches="oneHour">
<then>
GROUP BY TIMEPERIOD.STARTYEAR,
TIMEPERIOD.STARTMONTH,
TIMEPERIOD.STARTDAY,
TIMEPERIOD.STARTHOUR
ORDER BY TIMEPERIOD.STARTYEAR,
TIMEPERIOD.STARTMONTH,
TIMEPERIOD.STARTDAY,
TIMEPERIOD.STARTHOUR
</then>
</ifInputValue>
<ifInputValue name="precision" input="timePeriodInput" matches="oneDay">
<then>
GROUP BY TIMEPERIOD.STARTYEAR,
TIMEPERIOD.STARTMONTH,
TIMEPERIOD.STARTDAY
ORDER BY TIMEPERIOD.STARTYEAR,
TIMEPERIOD.STARTMONTH,
TIMEPERIOD.STARTDAY
</then>
</ifInputValue>

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 6 of 68
Customizer Manual Report Definition Report Definition

</sqlQuery>
<dataSheet linesPerPage="10">
<columns>
<column name="startTime" type="dateTime"
format="%1$td.%1$tm.%1$tY %1$tH:%1$tM" source="sqlQuery"
sqlQueryColumnName="STARTTIME"/>
<column name="endTime" type="dateTime"
format="%1$td.%1$tm.%1$tY %1$tH:%1$tM" source="sqlQuery"
sqlQueryColumnName="ENDTIME"/>
<column name="bulkyItemCounter" type="integer" format="%d" source="sqlQuery"
sqlQueryColumnName="BULKYITEMCOUNTER"/>
</columns>
</dataSheet>
<charts>
<timeSeriesChart name="bulkyItemCounterChart">
<manyColumnsToManyTimeSeriesMapping>
<timeSerieses>
<timeSeries name="bulkyItemCounter">
<periods source="dataSheet" dataSheetColumnName="startTime"/>
<values source="dataSheet"
dataSheetColumnName="bulkyItemCounter"/>
</timeSeries>
</timeSerieses>
</manyColumnsToManyTimeSeriesMapping>
</timeSeriesChart>
</charts>
</reportDefinition>

This report produces the following user interface in the TPiSCAN Enterprise Manager:

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 7 of 68
Customizer Manual Report Definition Report Definition

In simple terms each report definition is a single XML file. Its name can be freely chosen. The file
consists of a header and four main sections:
<?xml version="1.0" encoding="UTF-8"?>
<reportDefinition ...>
<inputs>
...
</inputs>
<sqlQuery>
...
</sqlQuery>
<dataSheet ...>
...
</dataSheet>
<charts>
...
</charts>
</reportDefinition>

The header contains the root element reportDefinition and defines the name and other
global properties of the report.
The first section contains the element inputs and defines the input fields shown on the left side of
the user interface
The second section contains the element sqlQuery and defines the SQL query used to gather
data from the statistics database.
The third section contains the element dataSheet and defines the table shown on the right side
of the user interface.

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 8 of 68
Customizer Manual Report Definition Report Definition

The fourth section contains the element charts and is optional. It defines the diagrams shown on
the right side of the user interface.
These elements will be explained in detail in the next chapters.

2.1 Global Properties – Element reportDefinition

The root element reportDefinition defines global properties for a report. It has five attributes:

Attribute Use Description

name required The technical name of the report. It should not contain
blanks.

level required Where shall the report be offered?

enterprise – Enterprise Manager only
store – Store Manager only
enterpriseAndStore – Enterprise and Store Manager

expert required Is the report for experts only?

false – normal report
true – expert report
Expert reports are only shown in the list of reports, if the
“More” button has been pressed before.

executeImmediately optional Shall the report be executed immediately after selection

from the list of reports?
false (default) – execute on button click
true – execute immediately

version required Always 1.0.0

In addition, the root element reportDefinition has two attributes for the schema validation:
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:noNamespaceSchemaLocation="ReportConfig.xsd"
Example:
<?xml version="1.0" encoding="UTF-8"?>
<reportDefinition version="1.0.0" name="BulkyItems" level="enterpriseAndStore"
expert="false" executeImmediately="false"
mlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="ReportConfig.xsd">
...
</reportDefinition>

2.2 Input Fields – Element inputs

The element inputs defines one or more blocks of input fields for a report. It has no attributes
and can contain the following sub-elements describing blocks of input fields:
- timePeriodInput (time period and precision)
- currencyInput (one currency)

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 9 of 68
Customizer Manual Report Definition Report Definition

- storeInput (one store)

- storeLaneInput (one lane)
- storeAttendantInput (one attendant)
- storeLaneAttendantInput (one lane and one attendant)
- zoneInput (one zone)
- storeListInput (several stores)
- storeLaneListInput (several lanes)
- storeAttendantListInput (several attendants)
- zoneListInput (several zones)
- integerInput (integer value)
There are two kinds of input fields for stores, lanes, attendants and zones. The first kind supports
the selection of exactly one item. The second kind supports the selection of multiple items. It
depends on the requirements of the report, if the selection of multiple items makes sense. Both
kinds of input fields deliver different presentations of the selected item(s) and have to be integrated
differently with the SQL query. Details follow in chapter 2.3.1.
Each sub-element has a mandatory attribute name that defines a technical name for the input
block. The name must be unique, must not contain blanks and is later on used to reference the
input block. The order of the sub-elements is arbitrary and defines the order of the input fields on
the user interface. Each sub-element can be used multiple times, if necessary. None of these sub-
elements is required.
These elements will be explained in detail in the next chapters.
Example:
<?xml version="1.0" encoding="UTF-8"?>
<reportDefinition ...>
<inputs>
<timePeriodInput name="timePeriodInput">
...
</timePeriodInput>
<storeInput name="storeInput">
...
</storeInput>
</inputs>
...
</reportDefinition>

2.2.1 Time Period and Precision – Element timePeriodInput

The element timePeriodInput defines a block of four input fields suitable for the input of a time
period like the current month, the last year and so on including an arbitrary time period between
two dates. In addition, it allows the selection of a precision like one hour, one day and so on.

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 10 of 68
Customizer Manual Report Definition Report Definition

The user interface looks as follows:

Normally the start date and the end date are computed from the selected period. The only
exception is the pseudo period “from … to …”. In this case the start date and the end date can be
selected individually from a calendar.
When the input field for the start date or end date is clicked, then a calendar dialog appears that
looks as follows:

In addition to the attribute name described in chapter 2.2, the element timePeriodInput has
four mandatory sub-elements for the four input fields:
- timePeriod
- startTimestamp
- endTimestamp
- precision
Each of these sub-elements defines one input field.

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 11 of 68
Customizer Manual Report Definition Report Definition

The element timeperiod defines the input field for the time period and has four attributes:

Attribute Use Description

values optional Which time periods shall be offered?

today – today
yesterday – yesterday
lastSevenDays – last 7 days
lastThirtyDays – last 30 days
currentWeek – current week
currentMonth – current month
currentQuarter – current quarter
currentYear – current year
lastWeek – last week
lastMonth – last month
lastQuarter – last quarter
lastYear – last year
fromTo – individual time period between to arbitrary dates
Several time periods can be offered; they must be separated
by blanks. By default all time periods are offered.

default required The time period that is initially selected. It must be one of the
time periods defined by the attribute values.

fixed optional Shall the input field be fixed?

false (default) – the time period can be selected
true – the default time period is used

show optional Shall the input field be shown on the user interface?
true (default) – the input field is shown
false – the input field is not shown

The element startTimeStamp defines the input field for the start date and time and has five
attributes:

Attribute Use Description

default optional The time and date that is initially presented. The format is
the standard XML schema format for date and time (YYYY-
MM-DDTHH:MM:SS), e.g. 2013-06-20T17:36:48. By default
the actual date and time is selected. Only evaluated if the
time period fromTo is used.

showHours optional Shall it be possible to select an hour also?

false (default) – only a date can be selected
true – an hour can be selected, too

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 12 of 68
Customizer Manual Report Definition Report Definition

Attribute Use Description

showMinutes optional Shall it be possible to select a minute also?

false (default) – only a date can be selected
true – a minute can be selected, too

fixed optional Shall the input field be fixed?

false (default) – the date and time can be changed
true – the default date and time

show optional Shall the input field be shown on the user interface?
true (default) – the input field is shown
false – the input field is not shown

The element endTimeStamp defines the input field for the end date and time and has the same
five attributes like the element startTimeStamp.
The element precision defines the input field for the precision and has four attributes:

Attribute Use Description

values optional Which precisions shall be offered?

oneHour – 1 hour
oneDay – 1 one day
oneWeek – 1 week
oneMonth – 1 month
oneQuarter – 1 quarter
oneYear – 1 year
Several precisions can be offered; they must be separated
by blanks. By default all precisions are offered.

default required The precision that is initially selected. It must be one of the
precisions defined by the attribute values.

fixed optional Shall the input field be fixed?

false (default) – the precision can be selected
true – the default precision is used

show optional Shall the input field be shown on the user interface?
true (default) – the input field is shown
false – the input field is not shown

Example:
<?xml version="1.0" encoding="UTF-8"?>
<reportDefinition ...>
<inputs>
...
<timePeriodInput name="timePeriodInput">
<timePeriod values="currentQuarter currentYear fromTo" default="fromTo"
fixed="false" show="true"/>

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 13 of 68
Customizer Manual Report Definition Report Definition

<startTimestamp default="2013-06-01T00:00:00" fixed="false" show="true"

showHours="false" showMinutes="false"/>
<endTimestamp default="2012-06-30T23:59:59" fixed="false" show="true"
showHours="false" showMinutes="false"/>
<precision values="oneDay oneMonth" default="oneDay" fixed="false"
show="true"/>
</timePeriodInput>
...
</inputs>
...
</reportDefinition>

2.2.2 One Currency – Element currencyInput

The element currencyInput defines a block of one input field for the selection of one currency
based on the actual data in the statistics database.
The user interface looks as follows:

In addition to the attribute name described in chapter 2.2, the element currencyInput has one
mandatory sub-element for the input field:
- currencyCode
The element currencyCode defines the input field for the currency and has four attributes:

Attribute Use Description

default optional The ISO 4217 code of the currency that is initially selected,
e.g. EUR, GBP, USD. By default nothing is selected. If the
special value “all” is allowed by the attribute enableAll, it
can also be used as default using the code @all.

enableAll optional Shall the special value “all” be offered?

false (default) – special value “all” is not offered
true – special value “all” is offered
The special value “all” can be useful for SQL queries that
shall deliver data for one currency or for all currencies.

fixed optional Shall the input field be fixed?

false (default) – the currency can be selected
true – the default currency is used

show optional Shall the input field be shown on the user interface?
true (default) – the input field is shown
false – the input field is not shown

Example:
<?xml version="1.0" encoding="UTF-8"?>
<reportDefinition ...>
<inputs>
...
<currencyInput name="currencyInput">

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 14 of 68
Customizer Manual Report Definition Report Definition

<currencyCode default="EUR" enableAll="false" fixed="false" show="true"/>

</currencyInput>
...
</inputs>
...
</reportDefinition>

2.2.3 One Store – Element storeInput

The element storeInput defines a block of one input field for the selection of exactly one store
based on the actual data in the statistics database.
The user interface looks as follows:

When the input field is clicked, then a dialog with a list of the existing stores appears that looks as
follows:

In addition to the attribute name described in chapter 2.2, the element storeInput has one
mandatory sub-element for the input field:
- storeName
The element storeName defines the input field for the store name and has four attributes.

Attribute Use Description

default optional The name of the store that is initially selected. By default
nothing is selected. If it is allowed to select all stores using
the attribute enableAll, the value @all can be used to
select all stores initially.

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 15 of 68
Customizer Manual Report Definition Report Definition

Attribute Use Description

enableAll optional Shall it be allowed to select all stores?

false (default) – only a single store can be selected
true – all stores can be selected in addition
To allow the selection of all stores can be useful for SQL
queries that shall deliver data for one store or for all stores.

fixed optional Shall the input field be fixed?

false (default) – the store name can be selected
true – the default store name is used

show optional Shall the input field be shown on the user interface?
true (default) – the input field is shown
false – the input field is not shown

Example:
<?xml version="1.0" encoding="UTF-8"?>
<reportDefinition ...>
<inputs>
...
<storeInput name="storeInput">
<storeName default="" enableAll="false" fixed="false" show="true"/>
</storeInput>
...
</inputs>
...
</reportDefinition>

2.2.4 One Lane – Element storeLaneInput

The element storeLaneInput defines a block of two input fields for the selection of exactly one
lane from one store based on the actual data in the statistics database.
The user interface looks as follows:

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 16 of 68
Customizer Manual Report Definition Report Definition

When one of the input fields is clicked, then a dialog with a list of the existing stores or lanes
appears that looks as follows:

The lane names are only unique within a store, so a store must be selected first before a lane can
be selected. If all stores are selected, then all lanes are selected, too, and no lane names are
shown.
In addition to the attribute name described in chapter 2.2, the element storeLaneInput has two
mandatory sub-elements for the input fields:
- storeName
- laneName
The element storeName defines the input field for the store name and has the same four
attributes that are described in chapter 2.2.3.
The element laneName defines the input field for the lane name and has four attributes:

Attribute Use Description

default optional The name of the lane that is initially selected. By default
nothing is selected. If it is allowed to select all lanes using
the attribute enableAll, the value @all can be used to
select all lanes initially.

enableAll optional Shall it be allowed to select all lanes?

false (default) – only a single lane can be selected
true – all lanes can be selected in addition
To allow the selection of all lanes can be useful for SQL
queries that shall deliver data for one lane or for all lanes.

fixed optional Shall the input field be fixed?

false (default) – the lane name can be selected
true – the default lane name is used

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 17 of 68
Customizer Manual Report Definition Report Definition

Attribute Use Description

show optional Shall the input field be shown on the user interface?
true (default) – the input field is shown
false – the input field is not shown

Example:
<?xml version="1.0" encoding="UTF-8"?>
<reportDefinition ...>
<inputs>
...
<storeLaneInput name="storeLaneInput">
<storeName enableAll="true" default="@all" fixed="false" show="true"/>
<laneName enableAll="true" default="@all" fixed="false" show="true"/>
</storeLaneInput>
...
</inputs>
...
</reportDefinition>

2.2.5 One Attendant – Element storeAttendantInput

The element storeAttendantInput defines a block of two input fields for the selection of
exactly one attendant from one store based on the actual data in the statistics database.
The user interface looks as follows:

When one of the input fields is clicked, then a dialog with a list of the existing stores or attendants
appears that looks as follows:

The attendant names are only unique within a store, so a store must be selected first before an
attendant can be selected. If all stores are selected, then all attendants are selected, too, and no
attendant names are shown.

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 18 of 68
Customizer Manual Report Definition Report Definition

In addition to the attribute name described in chapter 2.2, the element storeAttendantInput
has two mandatory sub-elements for the input fields:
- storeName
- attendantName
The element storeName defines the input field for the store name and has the same four
attributes that are described in chapter 2.2.3.
The element attendantName defines the input field for the attendant name and has four
attributes:

Attribute Use Description

default optional The name of the attendant that is initially selected. By default
nothing is selected. If it is allowed to select all attendants
using the attribute enableAll, the value @all can be used
to select all attendants initially.

enableAll optional Shall it be allowed to select all attendants?

false (default) – only a single attendant can be selected
true – all attendants can be selected in addition
To allow the selection of all attendants can be useful for SQL
queries that shall deliver data for one attendant or for all
attendants.

fixed optional Shall the input field be fixed?

false (default) – the attendant name can be selected
true – the default attendant name is used

show optional Shall the input field be shown on the user interface?
true (default) – the input field is shown
false – the input field is not shown

Example:
<?xml version="1.0" encoding="UTF-8"?>
<reportDefinition ...>
<inputs>
...
<storeAttendantInput name="storeAttendantInput">
<storeName default="" enableAll="false" fixed="false" show="true"/>
<attendantName default="" enableAll="false" fixed="false" show="true"/>
</storeAttendantInput>
...
</inputs>
...
</reportDefinition>

2.2.6 One Lane, One Attendant – Element storeLaneAttendantInput

The element storeLaneAttendantInput defines a block of three input fields for the selection
of exactly one lane and one attendant from one store based on the actual data in the statistics
database.

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 19 of 68
Customizer Manual Report Definition Report Definition

The user interface looks as follows:

When one of the input fields is clicked, then a dialog with a list of the existing stores or lanes or
attendants appears – see chapter 2.2.4 or 2.2.5 or 2.2.6.
The lane names and the attendant names are only unique within a store, so a store must be
selected first before a lane or an attendant can be selected. If all stores are selected, then all lanes
and all attendants are selected, too, and no lane names and attendant names are shown.
In addition to the attribute name described in chapter 2.2, the element storeLaneInput has
three mandatory sub-elements for the input fields:
- storeName
- laneName
- attendantName
The element storeName defines the input field for the store name and has the same four
attributes that are described in chapter 2.2.3.
The element laneName defines the input field for the lane name and has the same four attributes
that are described in chapter 2.2.4.
The element attendantName defines the input field for the attendant name and has the same
four attributes that are described in chapter 2.2.5.
Example:
<?xml version="1.0" encoding="UTF-8"?>
<reportDefinition ...>
<inputs>
...
<storeLaneAttendantInput name="storeLaneAttendantInput">
<storeName default="" enableAll="false" fixed="false" show="true"/>
<laneName default="@all" enableAll="true" fixed="false" show="true"/>
<attendantName default="@all" enableAll="true" fixed="false" show="true"/>
</storeLaneAttendantInput>
...
</inputs>
...
</reportDefinition>

2.2.7 One Zone – Element zoneInput

The element zoneInput defines a block of one input field for the selection of exactly one zone
based on the actual data in the statistics database.
The user interface looks as follows:

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 20 of 68
Customizer Manual Report Definition Report Definition

When the input field is clicked, then a dialog with a list of the existing zones appears that looks as
follows:

In addition to the attribute name described in chapter 2.2, the element zoneInput has one
mandatory sub-element for the input field:
- zoneName
The element zoneName defines the input field for the zone name and has four attributes.

Attribute Use Description

default optional The name of the zone that is initially selected. By default
nothing is selected. If it is allowed to select all zones using
the attribute enableAll, the value @all can be used to
select all zones initially.

enableAll optional Shall it be allowed to select all zones?

false (default) – only a single zone can be selected
true – all zones can be selected in addition
To allow the selection of all zones can be useful for SQL
queries that shall deliver data for one zone or for all zones.

fixed optional Shall the input field be fixed?

false (default) – the zone name can be selected
true – the default zone name is used

show optional Shall the input field be shown on the user interface?
true (default) – the input field is shown
false – the input field is not shown

Example:
<?xml version="1.0" encoding="UTF-8"?>
<reportDefinition ...>
<inputs>
...

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 21 of 68
Customizer Manual Report Definition Report Definition

<zoneInput name="zoneInput">
<zoneName default="Food" enableAll="false" fixed="false" show="true"/>
</zoneInput>
...
</inputs>
...
</reportDefinition>

2.2.8 Several Stores – Element storeListInput

The element storeListInput defines a block of one input field for the selection of several
stores based on the actual data in the statistics database.
The user interface looks as follows:

When the input field is clicked, then a dialog with a list of the existing stores appears that looks as
follows:

In addition to the attribute name described in chapter 2.2, the element storeListInput has one
mandatory sub-element for the input field:
- storeNames
The element storeNames defines the input field for the store names and has three attributes.

Attribute Use Description

default optional The name of the store that is initially selected. By default
nothing is selected. The value @all can be used to select all
stores initially.

fixed optional Shall the input field be fixed?

false (default) – the store names can be selected
true – the default store name is used

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 22 of 68
Customizer Manual Report Definition Report Definition

Attribute Use Description

show optional Shall the input field be shown on the user interface?
true (default) – the input field is shown
false – the input field is not shown

Example:
<?xml version="1.0" encoding="UTF-8"?>
<reportDefinition ...>
<inputs>
...
<storeListInput name="storeListInput">
<storeNames default="@all" fixed="false" show="true"/>
</storeListInput>
...
</inputs>
...
</reportDefinition>

2.2.9 Several Lanes – Element storeLaneListInput

The element storeLaneListInput defines a block of two input fields for the selection of
several lanes from one store based on the actual data in the statistics database.
The user interface looks as follows:

When one of the input fields is clicked, then a dialog with a list of the existing stores or lanes
appears that looks as follows:

The lane names are only unique within a store, so a store must be selected first before lanes can
be selected. If all stores are selected, then all lanes are selected, too, and no lane names are
shown.

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 23 of 68
Customizer Manual Report Definition Report Definition

In addition to the attribute name described in chapter 2.2, the element storeLaneInput has two
mandatory sub-elements for the input fields:
- storeName
- laneNames
The element storeName defines the input field for the store name and has the same four
attributes that are described in chapter 2.2.3.
The element laneNames defines the input field for the lane names and has three attributes:

Attribute Use Description

default optional The name of the lane that is initially selected. By default
nothing is selected. The value @all can be used to select all
lanes initially.

fixed optional Shall the input field be fixed?

false (default) – the lane names can be selected
true – the default lane name is used

show optional Shall the input field be shown on the user interface?
true (default) – the input field is shown
false – the input field is not shown

Example:
<?xml version="1.0" encoding="UTF-8"?>
<reportDefinition ...>
<inputs>
...
<storeLaneListInput name="storeLaneListInput">
<storeName default="" enableAll="false" fixed="false" show="true"/>
<laneNames default="" fixed="false" show="true"/>
</storeLaneListInput>
...
</inputs>
...
</reportDefinition>

2.2.10 Several Attendants – Element storeAttendantListInput

The element storeAttendantListInput defines a block of two input fields for the selection of
several attendants from one store based on the actual data in the statistics database.
The user interface looks as follows:

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 24 of 68
Customizer Manual Report Definition Report Definition

When one of the input fields is clicked, then a dialog with a list of the existing stores or attendants
appears that looks as follows:

The attendant names are only unique within a store, so a store must be selected first before
attendants can be selected. If all stores are selected, then all attendants are selected, too, and no
attendant names are shown.
In addition to the attribute name described in chapter 2.2, the element storeLaneInput has two
mandatory sub-elements for the input fields:
- storeName
- attendantNames
The element storeName defines the input field for the store name and has the same four
attributes that are described in chapter 2.2.3.
The element attendantNames defines the input field for the attendant names and has three
attributes:

Attribute Use Description

default optional The name of the attendant that is initially selected. By default
nothing is selected. The value @all can be used to select all
attendants initially.

fixed optional Shall the input field be fixed?

false (default) – the attendant names can be selected
true – the default attendant name is used

show optional Shall the input field be shown on the user interface?
true (default) – the input field is shown
false – the input field is not shown

Example:
<?xml version="1.0" encoding="UTF-8"?>
<reportDefinition ...>
<inputs>
...

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 25 of 68
Customizer Manual Report Definition Report Definition

<storeAttendantListInput name="storeAttendantListInput">
<storeName default="@all" enableAll="true" fixed="false" show="true"/>
<attendantNames default="@all" fixed="false" show="true"/>
</storeAttendantListInput>
...
</inputs>
...
</reportDefinition>

2.2.11 Several Zones – Element zoneListInput

The element zoneListInput defines a block of one input field for the selection of several zones
based on the actual data in the statistics database.
The user interface looks as follows:

When the input field is clicked, then a dialog with a list of the existing zones appears that looks as
follows:

In addition to the attribute name described in chapter 2.2, the element zoneListInput has one
mandatory sub-element for the input field:
- zoneNames
The element zoneNames defines the input field for the zone names and has three attributes.

Attribute Use Description

default optional The name of the zone that is initially selected. By default
nothing is selected. The value @all can be used to select all
zones initially.

fixed optional Shall the input field be fixed?

false (default) – the zone names can be selected
true – the default zone name is used

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 26 of 68
Customizer Manual Report Definition Report Definition

Attribute Use Description

show optional Shall the input field be shown on the user interface?
true (default) – the input field is shown
false – the input field is not shown

Example:
<?xml version="1.0" encoding="UTF-8"?>
<reportDefinition ...>
<inputs>
...
<zoneListInput name="zoneListInput">
<zoneNames default="Food" fixed="false" show="true"/>
</zoneListInput>
...
</inputs>
...
</reportDefinition>

2.2.12 Integer Value – Element integerInput

The element integerInput defines a block of one input field for an integer number.
The user interface looks as follows:

In addition to the attribute name described in chapter 2.2, the element integerInput has one
mandatory sub-element for the input field:
- integerNumber
The element integerNumber defines the input field for the integer value and has five attributes:

Attribute Use Description

default optional The integer value that is initially presented. By default

nothing is presented.

minValue optional The minimum integer value allowed. By default there is no

restriction.

maxValue optional The maximum integer value allowed. By default there is no

restriction.

fixed optional Shall the input field be fixed?

false (default) – the integer value can be changed
true – the default integer value is used

show optional Shall the input field be shown on the user interface?
true (default) – the input field is shown
false – the input field is not shown

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 27 of 68
Customizer Manual Report Definition Report Definition

Example:
<?xml version="1.0" encoding="UTF-8"?>
<reportDefinition ...>
<inputs>
...
<integerInput name="integerInput">
<integerNumber default="5" minValue="1" maxValue="10" fixed="false"
show="true"/>
</integerInput>
...
</inputs>
...
</reportDefinition>

2.3 SQL Query – Element sqlQuery

The element sqlQuery defines the SQL query for a report. It has no attributes. All text between
the begin tag and end tag is interpreted as SQL query. The SQL query must contain exactly one
SELECT statement. This SELECT statement can be of any complexity that the database engine
used by TPiSCAN supports and can also contain sub-queries. It is executed on the statistics
database using JDBC and returns a result set. The result set is later on displayed as table or as
diagram.
Example:
<?xml version="1.0" encoding="UTF-8"?>
<reportDefinition ...>
...
<sqlQuery>
SELECT STORE.NAME AS STORENAME,
LANE.NAME AS LANENAME
FROM STORE
INNER JOIN LANE ON STORE.STOREID = LANE.STOREID
</sqlQuery>
...
</reportDefinition>

Caution: Some characters that are often used in SQL queries are reserved in XML and must be
replaced by so-called XML character entities.
Examples: <  &lt; >  &gt; &  &amp; "  &quot;

2.3.1 Input Values – Element inputValues

The actual values of the input fields defined by the element inputs described in chapter 2.2 can
be integrated in the SQL query using a sub-element inputValue. The sub-element inputValue
can be placed anywhere and anytime within the text defining the SQL query. Before the SQL query
is executed, each occurrence of the sub-element inputValue is replaced by the actual value of
the input field as text. The sub-element inputValue has two attributes:

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 28 of 68
Customizer Manual Report Definition Report Definition

Attribute Use Description

name required The technical name of the input value. The available input values
depend on the referenced block of input fields as defined by the next
table.
storeName – one store name
storeNames – list of several store names
laneName – one lane name
laneNames – list of several lane names
attendantName – one attendant name
attendantNames – list of several attendant names
zoneName – one zone name
zoneNames – list of zone names
currencyCode – one currency code
allAttendants – true, if all attendants selected, otherwise false
allCurrencies – true, if all currencies selected, otherwise false
allLanes – true, if all lanes selected, otherwise false
allStores – true, if all stores selected, otherwise false
allZones – true, if all zones selected, otherwise false
startTimestamp – start date and time
endTimestamp – end date and time
timePeroid – time period, possible values see chapter 2.2.1
precision – precision, possible values see chapter 2.2.1
integerNumber – an integer value

input required The name of the referenced block of input fields. Corresponds to the
attribute name of the elements timePeriodInput,
currencyInput, storeInput and so on, see chapter 2.2.

The following table shows which block of input fields delivers which input values:

Block of Input Fields Available Input Values

timePeriodInput (see chapter 2.2.1) timePeriod

startTimestamp
endTimestamp
precision

currencyInput (see chapter 2.2.2) currencyCode

allCurrencies

storeInput (see chapter 2.2.3) storeName

allStores

storeLaneInput (see chapter 2.2.4) storeName

allStores
laneName
allLanes

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 29 of 68
Customizer Manual Report Definition Report Definition

Block of Input Fields Available Input Values

storeAttendantInput (see chapter 2.2.5) storeName

allStores
attendantName
allAttendants

storeLaneAttendantInput (see chapter 2.2.6) storeName

allStores
laneName
allLanes
attendantName
allAttendants

zoneInput (see chapter 2.2.7) zoneName

allZones

storeListInput (see chapter 2.2.8) storeNames

allStores

storeLaneListInput (see chapter 2.2.9) storeName

allStores
laneNames
allLanes

storeAttendantListInput (see chapter 2.2.10) storeName

allStores
attendantNames
allAttendants

zoneListInput (see chapter 2.2.11) zoneNames

allZones

integerInput (see chapter 2.2.12) integerNumber

All input values are formatted in a way that makes their use in an SQL query as easy as possible.
If an input value consists of exactly one name or identifier or code, the name is enclosed in single
quotes. If an input value consists of a list of names, each name is enclosed in single quotes and
the names are separated by commas so that the list can be easily used in an IN clause. Time
stamps are formatted like YYYY-MM-DD HH:MM:SS and are enclosed in single quotes. This
format is directly accepted by Derby and MySQL. Oracle is explicitly set to this format each time
when the report engine opens a connection. Boolean values are formatted as TRUE and FALSE.
Integer values are formatted straight forward.
Example using storeInput (see chapter 2.2.3):
<?xml version="1.0" encoding="UTF-8"?>
<reportDefinition ...>
<inputs>
<storeInput name="storeInput">
<storeName/>
</storeInput>
</inputs>
<sqlQuery>
SELECT STORE.NAME AS STORENAME,
LANE.NAME AS LANENAME
FROM STORE

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 30 of 68
Customizer Manual Report Definition Report Definition

INNER JOIN LANE ON STORE.STOREID = LANE.STOREID

WHERE STORE.NAME = <inputValue name="storeName" input="storeInput"/>
</sqlQuery>
...
</reportDefinition>

Example using storeListInput (see chapter 2.2.8):

<?xml version="1.0" encoding="UTF-8"?>
<reportDefinition ...>
<inputs>
<storeListInput name="storeListInput">
<storeNames default="@all"/>
</storeListInput>
</inputs>
<sqlQuery>
SELECT STORE.NAME AS STORENAME,
LANE.NAME AS LANENAME
FROM STORE
INNER JOIN LANE ON STORE.STOREID = LANE.STOREID
WHERE STORE.NAME IN ( <inputValue name="storeNames" input="storeListInput"/> )
</sqlQuery>
...
</reportDefinition>

Example using integerInput (see chapter 2.2.12)

<?xml version="1.0" encoding="UTF-8"?>
<reportDefinition ...>
<inputs>
...
<integerInput name="integerInput">
<integerNumber default="5" minValue="1" maxValue="1000"/>
</integerInput>
</inputs>
<sqlQuery>
SELECT ...
FROM ...
WHERE ...
FETCH FIRST <inputValue name="integerNumber" input="integerInput"/> ROWS ONLY
</sqlQuery>
...
</reportDefinition>

2.3.2 Conditions – Elements ifInputValue and ifDatabase

The actual values of the input fields can also be used to mark parts of the SQL query as optional
using a sub-elements ifInputValue with its nested elements then and else. The sub-element
ifInputValue can be placed anywhere and anytime within the text defining the SQL query and
defines the condition. The nested element then is mandatory and defines the part of the SQL
query that shall be used if the condition is fulfilled. The nested element else is optional and
defines the part of the SQL query that shall be used if the condition is not fulfilled.
The sub-element ifInputValue has three attributes:

Attribute Use Description

name required The name of the input value. Depends on the referenced input field.
The possible values are the same that are listed for the element
inputValue in the tables above.

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 31 of 68
Customizer Manual Report Definition Report Definition

Attribute Use Description

input required The name of the referenced block of input fields. Corresponds to the
attribute name of the elements timePeriodInput, currencyInput,
storeInput and so on, see chapter 2.2.

matches required The condition as regular expression using the Java regular expression
syntax provided by the class java.util.regex.Pattern. The
regular expression is applied on the actual input value.

The nested sub-elements then and else have no attributes.

Example using timePeriodInput (see chapter 2.2.1):
<?xml version="1.0" encoding="UTF-8"?>
<reportDefinition ...>
<inputs>
<timePeriodInput name="timePeriodInput">
<timePeriod default="lastThirtyDays"/>
<startTimestamp/>
<endTimestamp/>
<precision default="oneDay" values="oneDay oneMonth"/>
</timePeriodInput>
</inputs>
<sqlQuery>
SELECT ...
FROM ...
WHERE ...
<ifInputValue name="precision" input="timePeriodInput" matches="oneDay">
<then>
GROUP BY TIMEPERIOD.STARTYEAR,
TIMEPERIOD.STARTMONTH,
TIMEPERIOD.STARTDAY
</then>
<else>
GROUP BY TIMEPERIOD.STARTYEAR,
TIMEPERIOD.STARTMONTH
</else>
</ifInputValue>
</sqlQuery>
...
</reportDefinition>

Example using storeListInput (see chapter 2.2.8), an improvement of the previous example
using this input field:
<?xml version="1.0" encoding="UTF-8"?>
<reportDefinition ...>
<inputs>
<storeListInput name="storeListInput">
<storeNames default="@all"/>
</storeListInput>
</inputs>
<sqlQuery>
SELECT STORE.NAME AS STORENAME,
LANE.NAME AS LANENAME
FROM STORE
INNER JOIN LANE ON STORE.STOREID = LANE.STOREID
<ifInputValue name="allStores" input="storeListInput" matches="false">
<then>
WHERE STORE.NAME IN ( <inputValue name="storeNames"
input="storeListInput"/> )
</then>
</ifInputValue>

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 32 of 68
Customizer Manual Report Definition Report Definition

</sqlQuery>
...
</reportDefinition>

Sometimes it will be necessary to realize parts of the SQL query differently to support several
database engines. In this case the sub-element ifDatabase can be used. It is very similar to the
sub-element ifInputValue including the nested elements then and else and has one attribute:

Attribute Use Description

name required The name of database engine:

derby – Java Derby database engine (normally used by TPiSCAN)
mysql – MySQL database engine
oracle – Oracle database engine

Example:
<?xml version="1.0" encoding="UTF-8"?>
<reportDefinition ...>
...
<sqlQuery>
SELECT ...
FROM ...
WHERE ...
<ifDatabase name="derby">
<then>
FETCH FIRST 10 ROWS ONLY
</then>
<else>
LIMIT 10
</else>
</ifDatabase>
GROUP BY ...
</sqlQuery>
...
</reportDefinition>

2.4 Data Sheet – Element dataSheet

The element datasheet defines the data table shown on the right side of the user interface. It can
contain data from the result set of the SQL query defined by the element sqlQuery (see chapter
2.3) or computed data. The data can be later on visualized as diagram or exported to a CSV file.
The user interface looks as follows:

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 33 of 68
Customizer Manual Report Definition Report Definition

The element dataSheet itself describes global properties of the data sheet and has five
attributes:

Attribute Use Description

linesPerPage required The number of lines that shall be shown on one page of
the data sheet.

exportFileName optional The name of the CSV file if the data is exported. By
default the technical name of the report is used (see
chapter 2.1).

exportFileField optional The field separator of the CSV file. By default a comma
Separator is used.

exportFileDecimal optional The decimal separator of the CSV file. By default a

Separator period is used.

exportFileEncoding optional The encoding of the CSV file:

default – the Java default character encoding
provided by the class java.nio.charset.Charset.
It is derived from the locale and charset of the operating
system. In Western Europe it is ISO 8859-1.
utf8WithBom – UTF-8 with BOM (byte order mark)
utf8WithoutBom – UTF-8 without BOM

Example:
<?xml version="1.0" encoding="UTF-8"?>
<reportDefinition ...>
...
<dataSheet linesPerPage="10" exportFileName="Basic-Data.csv"
exportFileFieldSeparator=";" exportFileDecimalSeparator=","
exportFileEncoding="utf8WithBom">
...
</dataSheet>
...
</reportDefinition>

2.4.1 Columns – Element column

The element dataSheet has a mandatory sub-element columns with no attributes that embraces
one or several sub-elements column. The order of the column elements defines the order of the
columns on the user interface. Each sub-element column defines one column of the data sheet
and has eight attributes:

Attribute Use Description

name required The technical name of the column. The name must be
unique, must not contain blanks and is later on used to
reference the column.

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 34 of 68
Customizer Manual Report Definition Report Definition

Attribute Use Description

type required The data type of the column:

integer – integer value
decimal – decimal value
string – string
dateTime – date and time
decimalWithCurrency – decimal value with a
currency code

format required The format of the column using the Java formatting
syntax provided by the class java.util.Formatter.
The format is applied on the actual value of each cell.

source required The source of the column:

sqlQuery – the values of the column are taken from
the result set of the SQL query
computed – the values of the column are computed
from other columns

sqlQueryColumnName optional The name of the column from the result set of the SQL
query that shall provide the values for this column of the
data sheet. Only evaluated if the attribute source is set
to sqlQuery.

sqlQueryCurrency optional The name of the column from the result set of the SQL
ColumnName query that shall provide the currencies for this column of
the data sheet. Only evaluated if the attribute source is
set to sqlQuery and if the attribute type is set to
decimalWithCurrency.

computationMethod optional The method to compute the values of this column from
other columns:
percentage – compute values as percentage from the
values of the column specified by the attribute
baseValueColumnName
Only evaluated if the attribute source is set to
computed.

baseValueColumn optional The name of the column that shall be used as base
Name value for a computed column. Only evaluated if the
attribute source is set to computed and if the attribute
computationMethod is set to percentage.

Normally the source of a column in the data sheet is a column from the result set of the SQL query.
The type of the SQL query column must be compatible to the type of the data sheet column.
Following combinations are allowed:

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 35 of 68
Customizer Manual Report Definition Report Definition

SQL Type Data Sheet Type

CHAR string

VARCHAR string

INTEGER integer

SMALLINT integer

DECIMAL decimal

DECIMAL and decimalWithCurrency

CHAR or VARCHAR

TIMESTAMP dateTime

Example:
<?xml version="1.0" encoding="UTF-8"?>
<reportDefinition ...>
...
<sqlQuery>
SELECT STORE.NAME AS STORENAME,
LANE.NAME AS LANENAME
FROM STORE
INNER JOIN LANE ON STORE.STOREID = LANE.STOREID
</sqlQuery>
<dataSheet linesPerPage="11”>
<columns>
<column name="storeName" type="string" format="%s" source="sqlQuery"
sqlQueryColumnName="STORENAME"/>
<column name="laneName" type="string" format="%s" source="sqlQuery"
sqlQueryColumnName="LANENAME"/>
</columns>
</dataSheet>
...
</reportDefinition>

Data sheet columns of type decimalWithCurrency combine the data from two columns from
the result set of the SQL query. The first SQL column delivers the values. The second SQL column
delivers the ISO 4217 currency codes. The currency is only shown in the data sheet, if %s is used
as format. The modifiers are the same as for the %f format. Given a value of 12 and a currency
code of EUR, the format "%.2s" will deliver “12,00 €” and the format "%.2f" will deliver “12,00” in
Germany. For the format %s the symbol shown for the currency and the decimal separator are
chosen by the Java class java.text.NumberFormat based on the locale of the operating
system.
Example:
<?xml version="1.0" encoding="UTF-8"?>
<reportDefinition ...>
...
<dataSheet ...>
<columns>
<column name="totalAmount" type="decimalWithCurrency" format="%.2s"
source="sqlQuery" sqlQueryColumnName="TOTALAMOUNT"
sqlQueryCurrencyColumnName="CURRENCYCODE"/>
...
</columns>
</dataSheet>

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 36 of 68
Customizer Manual Report Definition Report Definition

...
</reportDefinition>

It is possible to use the value several times in a format to display different parts of the value. This
is useful for data sheet columns of type dateTime. Given a value of April 23rd, 2013, 8 AM, the
format "%1$td.%1$tm.%1$tY %1$tH:%1$tM" will deliver “23.04.2013 08:00”. This format also
shows that it is possible to include static text in the format.
Example:
<?xml version="1.0" encoding="UTF-8"?>
<reportDefinition ...>
...
<dataSheet ...>
<columns>
<column name="startTime" type="dateTime"
format="%1$td.%1$tm.%1$tY %1$tH:%1$tM" source="sqlQuery"
sqlQueryColumnName="STARTTIME"/>
<column name="availableTime" type="integer" format="%d min"
source="sqlQuery" sqlQueryColumnName="AVAILABLETIME"/>
...
</columns>
</dataSheet>
...
</reportDefinition>

Data sheet columns can also be computed from other data sheet columns. Currently only the
computation of percentages is available.
Example:
<?xml version="1.0" encoding="UTF-8"?>
<reportDefinition ...>
...
<dataSheet ...>
<columns>
<column name="counter" type="integer" format="%d" source="sqlQuery"
sqlQueryColumnName="COUNTER"/>
<column name="percentage" type="decimal" format="%.1f %%" source="computed"
computationMethod="percentage" baseValueColumnName="counter"/>
...
</columns>
</dataSheet>
...
</reportDefinition>

The resulting data sheet looks as follows:

Counter Percentage

5 12.5 %

20 50.0 %

5 12.5 %

10 25.0 %

It is possible to replace or translate values shown in data sheet columns of type string by using
a sub-element translations embracing one or several sub-elements translation. Details
follow in chapter 3.3.

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 37 of 68
Customizer Manual Report Definition Report Definition

2.5 Charts – Element charts

The optional element charts defines one or more diagrams for a report. If the report shall have
no diagram, the element can be omitted. It has no attributes and can contain the following sub-
elements describing charts:
- pieChart3d (pie chart)
- xyLineChart (general line chart)
- barChart (bar chart)
- timeSeriesChart (chronological line chart)
Each sub-element has a mandatory attribute name that defines a technical name for the chart. The
name must be unique, must not contain blanks and is later on used to reference the chart. The
order of the sub-elements is arbitrary and defines the order of the charts on the user interface.
Each sub-element can be used multiple times, if necessary. None of these sub-elements is
required.
These elements will be explained in detail in the next chapters.
Example:
<?xml version="1.0" encoding="UTF-8"?>
<reportDefinition ...>
...
<charts>
<pieChart3d ...>
...
</pieChart3d>
<timeSeriesChart ...>
...
</timeSeriesChart>
</charts>
</reportDefinition>

2.5.1 Pie Chart – Element pieChart3d

The element pieChard3d defines a pie chart drawn in 3D style. It looks as follows:

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 38 of 68
Customizer Manual Report Definition Report Definition

The element pieChart3d has two attributes:

Attribute Use Description

name required The technical name of the chart. The name must be unique,
must not contain blanks and is later on used to reference the
chart.

legend optional Shall a legend be drawn?

false (default) – no legend is drawn
true – a legend is drawn explaining each color (segment)

Example:
<?xml version="1.0" encoding="UTF-8"?>
<reportDefinition ...>
...
<charts>
<pieChart3d name="pieChart3d" legend="true">
...
</pieChart3d>
...
</charts>
</reportDefinition>

The mapping of data from a data source to the diagram is defined by a sub-element. The pie chart
supports only one kind of mapping.

One Column to One Pie Mapping

This simple mapping creates one pie chart segment for each value of one data source column.
The label for each segment is defined by a second column.
Example:

Column 1 Column 2

A 30 B
A
B 20
C
C 10

The element for this mapping is named oneColumnToOnePieMapping. It has no attributes and
two sub-elements:
- keys
- values
The element keys defines the source and the formatting of the labels for the segments of the pie
chart. It has three attributes:

Attribute Use Description

source required The source of the data:

dataSheet – the data sheet shall be used as data
source for the labels

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 39 of 68
Customizer Manual Report Definition Report Definition

dataSheetColumnName optional The name of the data sheet column to be used for the
labels. Only evaluated if the attribute source is set to
dataSheet.

format optional The format for the labels using the Java formatting
syntax provided by the class java.util.Formatter.
The format is applied on the actual value for each label.
By default the values are directly used as labels.

The element values defines the source for the size of the segments of the pie chart. It has two
attributes:

Attribute Use Description

source required The source of the data:

dataSheet – the data sheet shall be used as data
source for the size of the segments

dataSheetColumnName optional The name of the data sheet column to be used for the
size. Only evaluated if the attribute source is set to
dataSheet. The data sheet column must have the
type integer or decimal.

Example:
<?xml version="1.0" encoding="UTF-8"?>
<reportDefinition ...>
...
<charts>
<pieChart3d ...>
<oneColumnToOnePieMapping>
<keys source="dataSheet" dataSheetColumnName="value" format="%.2s"/>
<values source="dataSheet" dataSheetColumnName="percentage"/>
</oneColumnToOnePieMapping>
</pieChart3d>
...
</charts>
</reportDefinition>

2.5.2 General Line Chart – Element xyLineChart

The element xyLineChart defines a general purposes line chart consisting of arbitrary points
defined by x and y coordinates connected to a line. It can show several lines at once. The diagram
looks as follows:

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 40 of 68
Customizer Manual Report Definition Report Definition

The element xyLineChart has three attributes:

Attribute Use Description

name required The technical name of the chart. The name must be unique,
must not contain blanks and is later on used to reference the
chart.

legend optional Shall a legend be drawn?

false (default) – no legend is drawn
true – a legend is drawn explaining each line

plotOrientation required The drawing direction:

vertical – x-axis is horizontal, y-axis is vertical
horizontal – x-axis is vertical, y-axis is horizontal

Example:
<?xml version="1.0" encoding="UTF-8"?>
<reportDefinition ...>
...
<charts>
<xyLineChart name="xyLineChart" legend="false" plotOrientation="vertical">
...
</xyLineChart>
...
</charts>
</reportDefinition>

The mapping of data from a data source to the diagram is defined by a sub-element. The general
line chart supports only one kind of mapping.

Many Columns to Many XY Lines Mapping

This mapping creates one line for each specified pair of data source columns. One column delivers
the x-values; the other column delivers the y-values. Each pair of columns builds the
corresponding line. The same column can be used for more than one line.

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 41 of 68
Customizer Manual Report Definition Report Definition

Example:

Col. 1 Col. 2 Col. 3 Col. 4 Col. 5

A 1 7 2 12

B 3 8 4 11

C 5 9 6 10

The element for this mapping is named manyColumnsToManyXyLinesMapping. It has no

attributes and a sub-element xySerieses with no attributes that embraces one or several sub-
elements xySeries. Each sub-element xySeries defines the series of data for one line and has
one attribute:

Attribute Use Description

name required The technical name of the series of data for one line. The
name must be unique, must not contain blanks and is later
on used to reference the series of data.

In addition, the element xySeries has two sub-elements:

- xValues
- yValues
These elements define the source for the x- and y-values for one line of the line chart. Both have
two attributes:

Attribute Use Description

source required The source of the data:

dataSheet – the data sheet shall be used as data
source for the x- or y-values

dataSheetColumnName optional The name of the data sheet column to be used for the
x- or y-values. Only evaluated if the attribute source is
set to dataSheet. The data sheet column must have
the type integer or decimal.

Example:
<?xml version="1.0" encoding="UTF-8"?>
<reportDefinition ...>
...
<charts>
<xyLineChart ...>
<manyColumnsToManyXyLinesMapping>
<xySerieses>
<xySeries name="averageSize">
<xValues source="dataSheet" dataSheetColumnName="height"/>
<yValues source="dataSheet" dataSheetColumnName="averageWeight"/>
</xySeries>
<xySeries name="minimumSize">
<xValues source="dataSheet" dataSheetColumnName="height"/>
<yValues source="dataSheet" dataSheetColumnName="minimumWeight"/>
</xySeries>

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 42 of 68
Customizer Manual Report Definition Report Definition

</xySerieses>
</manyColumnsToManyXyLinesMapping>
</xyLineChart>
...
</charts>
</reportDefinition>

2.5.3 Bar Chart – Element barChart

The element barChart defines a bar chart. It can show several data series at once using different
colors for the bars. The diagram looks as follows:

The element barChart has three attributes:

Attribute Use Description

name required The technical name of the chart. The name must be unique,
must not contain blanks and is later on used to reference the
chart.

legend optional Shall a legend be drawn?

false (default) – no legend is drawn
true – a legend is drawn explaining each line

plotOrientation required The drawing direction:

vertical – the bars are drawn in vertical direction
horizontal – the bars are drawn in horizontal direction

Example:
<?xml version="1.0" encoding="UTF-8"?>
<reportDefinition ...>
...
<charts>
<barChart name="barChart" legend="true" plotOrientation="vertical">
...
</barChart>
...
</charts>
</reportDefinition>

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 43 of 68
Customizer Manual Report Definition Report Definition

The mapping of data from a data source to the diagram is defined by a sub-element. The bar chart
supports two kinds of mapping.

One Column to One Bar Color Mapping

This simple mapping creates one bar for each value of one data source column. The label for each
bar is defined by a second column. All bars have the same color.
Example:

Column 1 Column 2

A 5

B 4

C 6
A B C

The element for this mapping is named oneColumnToOneBarColorMapping. It has no attributes

and two sub-elements:
- keys
- values
The element keys defines the source and the formatting of the labels for the bars of the bar chart.
It has three attributes:

Attribute Use Description

source required The source of the data:

dataSheet – the data sheet shall be used as data
source for the labels

dataSheetColumnName optional The name of the data sheet column to be used for the
labels. Only evaluated if the attribute source is set to
dataSheet.

format optional The format for the labels using the Java formatting
syntax provided by the class java.util.Formatter.
The format is applied on the actual value for each label.
By default the values are directly used as labels.

The element values defines the source for the size of the bars of the bar chart. It has two
attributes:

Attribute Use Description

source required The source of the data:

dataSheet – the data sheet shall be used as data
source for the size of the bars

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 44 of 68
Customizer Manual Report Definition Report Definition

dataSheetColumnName optional The name of the data sheet column to be used for the
size. Only evaluated if the attribute source is set to
dataSheet. The data sheet column must have the
type integer or decimal.

Example:
<?xml version="1.0" encoding="UTF-8"?>
<reportDefinition ...>
...
<charts>
<barChart ...>
<oneColumnToOneBarColorMapping>
<keys source="dataSheet" dataSheetColumnName="posItemDescription"/>
<values source="dataSheet" dataSheetColumnName="weightAttReqCounter"/>
</oneColumnToOneBarColorMapping>
</barChart>
...
</charts>
</reportDefinition>

One Column to Many Bar Colors Mapping

This mapping also creates one bar for each value of one data source column. The label for each
bar is also defined by a second column, but in this case several values can share one label. The
different bars for the same label are drawn in different colors. The color is indirectly defined by a
third column. There are as many colors as there are different values in the third column.
Example:

Column 1 Column 2 Column 3

A 5 XXX

A 2 YYY

B 4 XXX

B 7 YYY A B C
C 6 XXX
XXX YYY
C 3 YYY

The element for this mapping is named oneColumnToManyBarColorsMapping. It has no

attributes and three sub-elements:
- rowKeys
- columnKeys
- values
The element rowKeys defines the source for the colors and the formatting of the description of
each color in the legend of the bar chart. It has three attributes:

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 45 of 68
Customizer Manual Report Definition Report Definition

Attribute Use Description

source required The source of the data:

dataSheet – the data sheet shall be used as data
source for the colors

dataSheetColumnName optional The name of the data sheet column to be used for the
colors. Only evaluated if the attribute source is set to
dataSheet.

format optional The format for the description of the colors in the
legend using the Java formatting syntax provided by the
class java.util.Formatter. The format is applied
on the actual value for each description. By default the
values are directly used as description.

The element columnKeys defines the source and the formatting of the labels for the bars of the
bar chart. It has three attributes:

Attribute Use Description

source required The source of the data:

dataSheet – the data sheet shall be used as data
source for the labels

dataSheetColumnName optional The name of the data sheet column to be used for the
labels. Only evaluated if the attribute source is set to
dataSheet.

format optional The format for the labels using the Java formatting
syntax provided by the class java.util.Formatter.
The format is applied on the actual value for each label.
By default the values are directly used as labels.

The element values defines the source for the size of the bars of the bar chart. It has two
attributes:

Attribute Use Description

source required The source of the data:

dataSheet – the data sheet shall be used as data
source for the size of the bars

dataSheetColumnName optional The name of the data sheet column to be used for the
size. Only evaluated if the attribute source is set to
dataSheet. The data sheet column must have the
type integer or decimal.

Example:
<?xml version="1.0" encoding="UTF-8"?>
<reportDefinition ...>

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 46 of 68
Customizer Manual Report Definition Report Definition

...
<charts>
<barChart ...>
<oneColumnToManyBarColorsMapping>
<rowKeys source="dataSheet" dataSheetColumnName="operation" format="%s"/>
<columnKeys source="dataSheet" dataSheetColumnName="value"
format="%.2s"/>
<values source="dataSheet" dataSheetColumnName="counter"/>
</oneColumnToManyBarColorsMapping>
</barChart>
...
</charts>
</reportDefinition>

2.5.4 Chronological Line Chart – Element timeSeriesChart

The element timeSeriesChart defines a line chart where the x-axis is built by a chronological
sequence from the oldest to the newest point of time contained in the data. It can show several
lines at once. The diagram looks as follows:

The element timeSeriesChart has two attributes:

Attribute Use Description

name required The technical name of the chart. The name must be unique,
must not contain blanks and is later on used to reference the
chart.

legend optional Shall a legend be drawn?

false (default) – no legend is drawn
true – a legend is drawn explaining each line

Example:
<?xml version="1.0" encoding="UTF-8"?>
<reportDefinition ...>
...
<charts>
<timeSeriesChart name="timeSeriesChart" legend="true">
...
</timeSeriesChart>
...
</charts>

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 47 of 68
Customizer Manual Report Definition Report Definition

</reportDefinition>

The mapping of data from a data source to the diagram is defined by a sub-element. The
chronological line chart supports two kinds of mapping.

Many Columns to Many Time Series Mapping

This mapping creates one line for each specified pair of data source columns. One column delivers
the points in time; the other column delivers the values. Each pair of columns builds the
corresponding line. The same column can be used for more than one line.
Example:

Column 1 Column 2 Column 3

20.05.2013 3 5

21.05.2013 4 8

22.05.2013 6 7

20-May 21-May 22-May

The element for this mapping is named manyColumnsToManyTimeSeriesMapping. It has no

attributes and a sub-element timeSerieses with no attributes that embraces one or several sub-
elements timeSeries. Each sub-element timeSeries defines the series of data for one line
and has one attribute:

Attribute Use Description

name required The technical name of the series of data for one line. The
name must be unique, must not contain blanks and is later
on used to reference the series of data.

In addition, the element xySeries has two sub-elements:

- periods
- values
The element periods defines the source for the points in time for one line of the line chart (x-
axis). It has two attributes:

Attribute Use Description

source required The source of the data:

dataSheet – the data sheet shall be used as data
source for the points of time

dataSheetColumnName optional The name of the data sheet column to be used for the
points of time. Only evaluated if the attribute source is
set to dataSheet. The data sheet column must have
the type dateTime.

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 48 of 68
Customizer Manual Report Definition Report Definition

The element values defines the source for the values for one line of the line chart (y-axis). It has
two attributes:

Attribute Use Description

source required The source of the data:

dataSheet – the data sheet shall be used as data
source for the values

dataSheetColumnName optional The name of the data sheet column to be used for the
values. Only evaluated if the attribute source is set to
dataSheet. The data sheet column must have the
type integer or decimal.

Example:
<?xml version="1.0" encoding="UTF-8"?>
<reportDefinition ...>
...
<charts>
<timeSeriesChart ...>
<timeSerieses>
<timeSeries name="transactions">
<periods source="dataSheet" dataSheetColumnName="begin"/>
<values source="dataSheet" dataSheetColumnName="transactions"/>
</timeSeries>
<timeSeries name="voidedTransactions">
<periods source="dataSheet" dataSheetColumnName="begin"/>
<values source="dataSheet"
dataSheetColumnName="voidedTransactions"/>
</timeSeries>
</timeSerieses>
</timeSeriesChart>
...
</charts>
</reportDefinition>

One Column to Many Time Series Mapping

This mapping creates several lines for one specified pair of data source columns. One column
delivers the points in time; the other column delivers the values. A third column defines to which
line this value belongs. There are as many lines as there are different values in the third column.
Example:

Column 1 Column 2 Column 3

23.05.2013 10 XXX

23.05.2013 6 YYY

24.05.2013 8 XXX

24.05.2013 7 YYY
23-May 24-May 25-May
25.05.2013 4 XXX

25.05.2013 9 YYY XXX YYY

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 49 of 68
Customizer Manual Report Definition Report Definition

The element for this mapping is named oneColumnToManyTimeSeriesMapping. It has no

attributes and three sub-elements:
- keys
- periods
- values
The element keys defines the source for the selection of a line and the formatting of the
description of each line in the legend of the line chart. It has three attributes:

Attribute Use Description

source required The source of the data:

dataSheet – the data sheet shall be used as data
source for the selection of a line

dataSheetColumnName optional The name of the data sheet column to be used for the
selection of a line. Only evaluated if the attribute
source is set to dataSheet.

format optional The format for the description of the lines in the legend
using the Java formatting syntax provided by the class
java.util.Formatter. The format is applied on the
actual value for each description. By default the values
are directly used as description.

The element periods defines the source for the points in time for all lines (x-axis) of the line chart.
It has two attributes:

Attribute Use Description

source required The source of the data:

dataSheet – the data sheet shall be used as data
source for the points in time

dataSheetColumnName optional The name of the data sheet column to be used for the
points in time. Only evaluated if the attribute source is
set to dataSheet. The data sheet column must have
the type dateTime.

The element values defines the source for the values for all lines of the line chart (y-axis). It has
two attributes:

Attribute Use Description

source required The source of the data:

dataSheet – the data sheet shall be used as data
source for the values

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 50 of 68
Customizer Manual Report Definition Report Definition

dataSheetColumnName optional The name of the data sheet column to be used for the
values. Only evaluated if the attribute source is set to
dataSheet. The data sheet column must have the
type integer or decimal.

Example:
<?xml version="1.0" encoding="UTF-8"?>
<reportDefinition ...>
...
<charts>
<timeSeriesChart ...>
<oneColumnToManyTimeSeriesMapping>
<keys source="dataSheet" dataSheetColumnName="zoneName" format="%s"/>
<periods source="dataSheet" dataSheetColumnName="startTime"/>
<values source="dataSheet" dataSheetColumnName="totalAmount"/>
</oneColumnToManyTimeSeriesMapping>
</timeSeriesChart>
...
</charts>
</reportDefinition>

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 51 of 68
Customizer Manual Report Definition Translations

3 Translations
Each report can be translated separately to several languages. The translations are defined in
properties files. A properties file is simply a text file with keyword-value pairs. There is one
properties file for each report and each language. Here is an example with English translations for
the sample report definition from chapter 2 showing the number of bulky items:
title=Bulky Items
description=This report shows the number of bulky items as sum over one store.
input-timePeriodInput-timePeriod-title=Period
input-timePeriodInput-startTimestamp-title=Start Time
input-timePeriodInput-endTimestamp-title=End Time
input-timePeriodInput-precision-title=Precision
input-storeInput-storeName-title=Store
dataSheet-column-startTime-title=Start Time
dataSheet-column-endTime-title=End Time
dataSheet-column-bulkyItemCounter-title=Bulky Items
chart-bulkyItemCounterChart-title=Bulky Items
chart-bulkyItemCounterChart-timeAxisLabel=Time
chart-bulkyItemCounterChart-valueAxisLabel=Bulky Items

And here the same example with German translations:

title=Sperrige Artikel
description=Dieser Bericht zeigt die Anzahl der sperrigen Artikel als Summe über eine
Filiale.
input-timePeriodInput-timePeriod-title=Zeitraum
input-timePeriodInput-startTimestamp-title=Anfangszeit
input-timePeriodInput-endTimestamp-title=Endzeit
input-timePeriodInput-precision-title=Auflösung
input-storeInput-storeName-title=Filiale
dataSheet-column-startTime-title=Startzeit
dataSheet-column-endTime-title=Endzeit
dataSheet-column-bulkyItemCounter-title=Sperrige Artikel
chart-bulkyItemCounterChart-title=Sperrige Artikel
chart-bulkyItemCounterChart-timeAxisLabel=Zeit
chart-bulkyItemCounterChart-valueAxisLabel=Sperrige Artikel

The details are described in the following chapters.

3.1 Static Parts of User Interface

Some parts of the user interface of the web module Report Execution do not depend on the
reports, these parts are static.

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 52 of 68
Customizer Manual Report Definition Translations

Example (the dotted ellipses mark dynamic elements where only some values are statically
translated):

These parts can be translated in the same way as in all other web modules by changing or adding
properties files with translations for the web module itself.
Normally the web applications Enterprise and Store Manager are embedded in the Enterprise and
Store Business Server. In this case all files of the web applications are part of the so-called
Customer Base package. Then the properties files with the translations for the web module Report
Execution can be found in the directory <TPiSCAN_HOME>/customers/<CUSTOMER_NAME>/
base-<VERSION_NUMBER>/webapps-embedded/wn-tpiscan-<CUSTOMER_NAME>-
enterprise-manager/reportexecution/texts or .../wn-tpiscan-
<CUSTOMER_NAME>-store-manager/... . The files are named
reportengine_xx.properties and reportexecution_xx.properties. "xx" must be
replaced by an ISO 639-2 language code (two lower case letters).
Example (file reportexecution_en.properties):
title-text.text=Execute Report
pleaseSelectAReport-text.text=Please select a report
parameters-text.text=Parameters
more-text.text=More
...

The existing files for English and German already contain all keys that can be translated. If a new
language shall be supported, the English file can be copied to have a starting point. The language
code in the file name must be replaced by the code of the new language. Then all translations
have to be changed to proper values.
Normally the encoding of these properties files is ISO 8859-1 (see Java class
java.util.Properties). This encoding basically supports Western European languages. If

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 53 of 68
Customizer Manual Report Definition Translations

this is not sufficient, it is also possible to use UTF-8 as encoding. In this case the file must begin
with a byte order mark (BOM) in UTF-8, i.e. the bytes EF BB BF. Otherwise TPiSCAN will not
recognize this encoding.

3.2 Dynamic Parts of User Interface

Most parts of the user interface of the web module Report execution depend on the report, i.e. are
defined by the report definition. These parts are dynamic.
Example:

These parts can also be translated using properties files, but in this case these properties files are
part of the report. The name of the properties files must be equal to the name of the report
configuration XML file followed by an underline and the ISO 639-2 language code, so they follow
the same naming scheme as described in the previous chapter.
Example:

Purpose File name

Report configuration file ReportBulkyItems.xml

English translation file ReportBulkyItems_en.properties

German translation file ReportBulkyItems_de.properties

The keys that have to be translated mostly depend on the report definition. The various blocks of
input fields (see chapter 2.2) and the various charts (see chapter 0) need different translations.

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 54 of 68
Customizer Manual Report Definition Translations

The following tables show all keys that can appear somewhere including their context and
purpose.

Global Properties (see chapter 2.1)

Key Purpose

title The title of the report shown in the drop down list in the header area

description The description of the report shown in the main area as long as the report has
not been executed

Input Fields (see chapter 2.2)

Input Block Key Purpose

Time period and input-[name]-timePeriod- The title for the time period input
precision title field
(see chapter 2.2.1)
input-[name]- The title for the start date and
startTimestamp-title time input field

input-[name]-endTimestamp- The title for the end date and

title time input field

input-[name]-precision- The title for the precision input

title field

One currency input-[name]-currencyCode- The title for the currency code

title input field
(see chapter 2.2.2)

One store input-[name]-storeName- The title for the store name input
title field
(see chapter 2.2.3)

One lane input-[name]-storeName- The title for the store name input
title field
(see chapter 2.2.4)
input-[name]-laneName- The title for the lane name input
title field

One attendant input-[name]-storeName- The title for the store name input
title field
(see chapter 2.2.5)
input-[name]- The title for the attendant name
attendantName-title input field

One lane, one input-[name]-storeName- The title for the store name input
attendant title field
(see chapter 2.2.6)
input-[name]-laneName- The title for the lane name input
title field

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 55 of 68
Customizer Manual Report Definition Translations

Input Block Key Purpose

input-[name]- The title for the attendant name

attendantName-title input field

One zone input-[name]-zoneName- The title for the zone name input
title field
(see chapter 2.2.7)

Several stores input-[name]-storeNames- The title for the store names

title input field
(see chapter 2.2.8)

Several lanes input-[name]-storeName- The title for the store name input
title field
(see chapter 2.2.9)
input-[name]-laneNames- The title for the lane names input
title field

Several attendants input-[name]-storeName- The title for the store name input
title field
(see chapter 2.2.10)
input-[name]- The title for the attendant names
attendantNames-title input field

Several zones input-[name]-zoneNames- The title for the zone names

title input field
(see chapter 2.2.11)

Integer value input-[name]- The title for the integer value

integerNumber-title input field
(see chapter 2.2.12)

The placeholder [name] must be replaced by the name of the input block defined by the attribute
name of the corresponding input element.
Example:
<storeInput name="storeInput1">  input-storeInput1-timePeriod-title

Data sheet (see chapter 2.4)

Key Purpose

dataSheet-column-[name]-title The title of the data sheet column

The placeholder [name] must be replaced by the name of a data sheet column defined by the
attribute name of the corresponding column element.
Example:
<column name="storeName">  dataSheet-column -storeName- title

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 56 of 68
Customizer Manual Report Definition Translations

Charts (see chapter 0)

Chart Key Purpose

Pie chart chart-[name1]-title The title for the chart

(see chapter 2.5.1)

General line chart chart-[name1]-title The title for the chart

(see chapter 2.5.2)
chart-[name1]-xAxisLabel The label for the x-axis, if the
chart is drawn vertically

chart-[name1]-yAxisLabel The label for the y-axis, if the

chart is drawn vertically

chart-[name1]-xySeries- The Description of a data series

[name2]-key for a line, shown in the legend

Bar chart chart-[name1]-title The title for the chart

(see chapter 2.5.3)
chart-[name1]-valueAxisLabel The label for the x-axis, if the
chart is drawn vertically

chart-[name1]- The label for the y-axis, if the

categoryAxisLabel chart is drawn vertically

Chronological line chart-[name1]-title The title for the chart

chart
chart-[name1]-timeAxisLabel The label for the x-axis
(see chapter 2.5.3)
chart-[name1]-valueAxisLabel The label for the y-axis

chart-[name1]-timeSeries- The description of a data series

[name2]-key for a line, shown in the legend.
Only used by the “Many
Columns to Many Time Series
Mapping”.

The placeholder [name1] must be replaced by the name of a chart defined by the attribute name
of the corresponding chart element. The placeholder [name2] must be replaced by the name of a
data series defined by the attribute name of the corresponding data series element.
Example:
<timeSeriesChart name="timeSeriesChart3" ...>
...
<timeSeries name="transactions">

chart-timeSeriesChart3-timeSeries-transactions-key
The order of the keys is not important. If translations are missing, the key is shown instead in the
user interface, surrounded by two angle brackets.

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 57 of 68
Customizer Manual Report Definition Translations

Example:
title=Coupons
description=This report shows the number of coupons entered as sum over all stores or
all selected lanes of one store.
input-timePeriodInput-timePeriod-title=Period
input-timePeriodInput-startTimestamp-title=Start Time
input-timePeriodInput-endTimestamp-title=End Time
input-timePeriodInput-precision-title=Precision
input-storeLaneListInput-storeName-title=Store
input-storeLaneListInput-laneNames-title=Lanes
dataSheet-column-startTime-title=Start Time
dataSheet-column-endTime-title=End Time
dataSheet-column-couponCounter-title=Coupons
chart-couponCounterChart-title=Coupons
chart-couponCounterChart-timeAxisLabel=Time
chart-couponCounterChart-valueAxisLabel=Coupons

3.3 Values for Lists, Data Sheets, and Charts

Some of the values shown in the user interface of the web module Report execution can or must
also be translated.
Example:

The translation of values is also part of the report specific translation properties files described in
the previous chapter (see chapter 3.2).

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 58 of 68
Customizer Manual Report Definition Translations

Input Fields (see chapter 2.2)

The values shown by the input fields for currencies and zones must be translated, if these input
fields are used by a report. The following table shows all corresponding keys. All currency codes
and/or all zone names present in the statistics database must be translated.

Input Block Key Purpose

One currency input-[name1]- The translation for a currency code

currencyCode-value- read from the statistics database and
(see chapter 2.2.2) [name2] shown in the currency code input field

One zone input-[name1]- The translation for a zone name read

zoneName-value-[name2] from the statistics database and shown
(see chapter 2.2.7)
in the zone name input field

Several zones input-[name1]- The translation for a zone name read

zoneNames-value- from the statistics database and shown
(see chapter 2.2.11) [name2] in the zone names input field

The placeholder [name1] must be replaced by the name of the input block defined by the attribute
name of the corresponding input element. The placeholder [name2] must be replaced by a
currency code or zone name as present in the statistics database. If a zone name in the statistics
database contains blanks the blanks must be left out.
Example (German, statistics database contains two zone names “Food” and “Non Food”):
...
input-zoneListInput1-zoneNames-title=Zonen
input-zoneListInput1-zoneNames-value-Food=Lebensmittel
input-zoneListInput1-zoneNames-value-NonFood=Andere Waren
...

Data sheet (see chapter 2.4)

The values shown by the data sheet can be replaced by other values or can be translated, as long
as they are part of a column of type string. Normally these values are read from the statistics
database. To make these values replaceable or translatable, the element column of the data
sheet (see chapter 2.4.1) must be extended by a sub-element translations with no attributes
that embraces one or several sub-elements translation. Each sub-element translation
defines one translated value of the corresponding column of the data sheet and has three
attributes:

Attribute Use Description

value required The value of the corresponding column that shall be

translated

text optional The direct replacement text for the value. If this attribute
is present and the given value occurs in the
corresponding column, it is replaced by this text
independently of the language.

textId optional The text ID (key) to be used to translate the value in the
current language. Only evaluated if the attribute text is
not present.

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 59 of 68
Customizer Manual Report Definition Translations

If a data sheet column contains values that are not included in the translations, these values are
shown unchanged. If a value has a text ID assigned that does not exists in the translations
properties file of the actual language, the text ID is shown surrounded by two angle brackets.
Example:
<?xml version="1.0" encoding="UTF-8"?>
<reportDefinition ...>
...
<dataSheet ...>
<columns>
<column name="denominationType" type="string" ...>
<translations>
<translation value="C" textId="dataSheet-column-type-value-coin"/>
<translation value="N" textId="dataSheet-column-type-value-note"/>
<translation value="X" textId="dataSheet-column-type-value-unknown"/>
</translations>
</column>
...
</columns>
</dataSheet>
...
</reportDefinition>

The text IDs (keys) defined for the translation of values in the data sheet should follow the rules
used for the other keys.

Key Purpose

dataSheet-column-[name1]-value- The translation for a value of a column of

[name2] the data sheet. Normally the values are
read from the statistics database.

The placeholder [name1] must be replaced by the name of a data sheet column defined by the
attribute name of the corresponding column element. The placeholder [name2] must be replaced
by a text ID defined by the attribute textID of the corresponding translation element.
Example (English):
...
dataSheet-column-denominationType-title=Denomination Type
dataSheet-column-denominationType-value-coin=Coin
dataSheet-column-denominationType-value-note=Note
dataSheet-column-denominationType-value-unknown=Unknown
...

Example (German):
...
dataSheet-column-denominationType-title=Stückelungstyp
dataSheet-column-denominationType-value-coin=Münze
dataSheet-column-denominationType-value-note=Note
dataSheet-column-denominationType-value-unknown=Unbekannt
...

Charts (see chapter 0)

Since all charts have the data sheet as input, the charts automatically take over the replacements
or translations defined for the data sheet. There is nothing to configure in addition.

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 60 of 68
Customizer Manual Report Definition Deployment

4 Deployment
New or corrected reports must be deployed to make them available for the users. The reports can
be deployed statically as part of a customer base package or dynamically using the web
applications Store or Enterprise Manager. In both cases the XML configuration files and the
translations properties files of all reports have to be packed in a flat ZIP file first.
Example:

ReportBasicData.xml
ReportBasicData_de.properties
ReportBasicData_en.properties
ReportCashPayments.xml  MyReports.zip
ReportCashPayments_de.properties
ReportCashPayments_en.properties
...

4.1 Static Deployment

Reports can be deployed statically by making them a part of the customer base package. This
procedure is very simple. It is only necessary to copy the reports ZIP file created before to the
Customization Center working folder for this customer, namely into the sub-folder
.../<CUSTOMER_NAME>/base/defaultremote/reportdef-1. The name of the report ZIP
file must be wn-tpiscan-<CUSTOMER_NAME>-reportdef-1-default.zip at this place:

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 61 of 68
Customizer Manual Report Definition Deployment

It is also possible to use the standard reports provided by the TPiSCAN team, if no customer
specific requirements have to be fulfilled. In this case it is only necessary to click the “Add Report
Definitions” button or menu option in the Customization Center:

Afterwards the customer base package has to be recreated using the Customization Center in both
cases. When this package is installed and activated on the enterprise or store server and the
business server run composite is running, then the new reports are available for the users.
Statically deployed reports are only valid as long as there are no dynamic deployments (see next
chapter).

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 62 of 68
Customizer Manual Report Definition Deployment

4.2 Dynamic Deployment

Reports can be deployed dynamically by using the web module Report Maintenance contained in
the Enterprise and Store Manager. This procedure is very similar to the deployment of catalogs,
texts or cash settings using the respective web modules. The first step is to upload a new reports
ZIP file to the WebDAV server:

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 63 of 68
Customizer Manual Report Definition Deployment

Afterwards the new reports can be published and deployed to a previously defined destination:

When the new reports are deployed in the headquarters, it may take some time until the new
reports are transported to the stores and are available for the users. This depends on the data
transport times configured for the data distribution feature of TPiSCAN Enterprise Server. The web
module Report Execution only reads the reports when it is opened, so it may be necessary to close
and re-open the web module to see the new reports.

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 64 of 68
Customizer Manual Report Definition Summary

5 Summary
The previous chapters have explained the definition of reports, their translation, and their
deployment in detail. This chapter shall give a short summary of all steps to create and test a new
report and can be used as a checklist.
At the beginning the following questions shall be answered:
- What shall the report show?
- Where can the necessary data be found?
- Which parameters shall be offered to narrow the data?
- How shall the data be visualized as data sheet?
- How shall the data be visualized as charts?
Based on the answers to these questions the following steps shall be finished:
- Create test data for the new report on a demo installation of TPiSCAN by performing
adequate actions
- Develop and test a SQL query based on the TPiSCAN statistics database using a tool like
SQuirreL SQL Client (http://squirrel-sql.sourceforge.net/). Use the standard reports
provided by the TPiSCAN team and the examples in this document as inspiration. Identify
and test parts that
- have to be replaced by the actual values of parameters (input values)
- are only valid for specific values of parameters (parameter conditions)
- depend on the database engine (database conditions)
- Create a new XML configuration file for the report using a tool like XMLSpy
(http://www.altova.com/xmlspy.html). Use the standard reports provided by the TPiSCAN
team and the examples in this document as inspiration. The TPiSCAN team can provide an
XML schema for the report configuration file to make its editing easier.
- Add the XML header and the root element (see chapter 2.1)
- Add elements for each block of input fields (see chapter 2.2)
- Add an element for the SQL query (see chapter 2.3)
- Insert elements for input values and conditions in the SQL query
- Add elements for the data sheet including all columns (see chapter 2.4). Keep in mind
that columns can also be computed from other columns.
- Add elements for each value that shall be translated (see chapter 3.3)
- Add elements for the charts (see chapter 0)
- Create a new properties file for each language to translate the report using a text editor.
Use the standard reports provided by the TPiSCAN team and the examples in this
document as inspiration.
- Add keys and translations for the dynamic parts of the user interface (see chapter 3.2)
- Add keys and translations for values that must or shall be translated (see chapter 3.3)
- Put all files of the report in a flat ZIP file
- Deploy the reports ZIP file (see chapter 4)
- Test the new report. Missing translations are indicated by their key enclosed in two angled
brackets. If something else doesn’t work and the error message shown is not sufficient,
there is more information in the web log file <TPiSCAN_DATA_HOME>/customers/
<CUSTOMER_NAME>/work-1/store-server/log/tpiscan-web-wn-tpiscan-
store-manager.log or .../enterprise-server/log/tpiscan-web-wn-

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 65 of 68
Customizer Manual Report Definition Summary

tpiscan-enterprise-manager.log. These log files show the actual values of

parameters, the actual SQL query, the response from the database and so on. Search for
the string ReportEngine.executeQuery().
Example:
...
POST /iScanReportExecution/reportexecution/pages/report-execution.xhtml
...
ReportEngine.executeQuery()
Report name: BulkyItems
Input values: timePeriodInput.timePeriod=currentWeek timePeriodInput.startTimestamp=
2013-06-02T00:00:00 timePeriodInput.endTimestamp=2013-06-08T23:59:59
timePeriodInput.precision=oneDay storeInput.storeName=Muenchen storeInput.allStores=
false
Translations: 13 lines
SQL query: SELECT MIN(TIMEPERIOD.STARTTIME) AS STARTTIME, MAX(TIMEPERIOD.ENDTIME) AS
ENDTIME, SUM(CASE WHEN GENERALSTATISTICS.BULKYITEMCOUNTER IS NULL THEN 0 ELSE
GENERALSTATISTICS.BULKYITEMCOUNTER END) AS BULKYITEMCOUNTER FROM TIMEPERIOD LEFT
OUTER JOIN GENERALSTATISTICS ON TIMEPERIOD.TIMEPERIODID =
GENERALSTATISTICS.TIMEPERIODID LEFT OUTER JOIN LANE ON GENERALSTATISTICS.LANEID =
LANE.LANEID LEFT OUTER JOIN STORE ON LANE.STOREID = STORE.STOREID WHERE
TIMEPERIOD.STARTTIME >= '2013-06-02 00:00:00' AND TIMEPERIOD.STARTTIME <=
'2013-06-08 23:59:59' AND STORE.NAME = 'Muenchen' GROUP BY TIMEPERIOD.STARTYEAR,
TIMEPERIOD.STARTMONTH, TIMEPERIOD.STARTDAY ORDER BY TIMEPERIOD.STARTYEAR,
TIMEPERIOD.STARTMONTH, TIMEPERIOD.STARTDAY
Database connection: jdbc:derby://localhost:33308/enterprisestatistics;create=false
Result: dataset with 7 rows and 3 columns
...
finished after 1,192 s
...

Have fun!

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 66 of 68
Customizer Manual Report Definition Appendix

6 Appendix

6.1 Differences between Derby, MySQL and ORACLE

UNION on String Constants
Example:
SELECT 'abc' AS COLUMN1,
...
FROM ...
WHERE ...
UNION
SELECT 'defg' AS COLUMN1,
...
FROM ...
WHERE ...

Oracle and MySQL return the string constants as VARCHAR(n). Derby returns the string constants
as CHAR(n) where n is the length of the longest string constant. All shorter strings are padded with
blanks. To avoid this the string constants must be explicitly converted to VARCHAR(n) for Derby.
Example:
SELECT CAST('abc' AS VARCHAR(10)) AS COLUMN1,
...
FROM ...
WHERE ...
UNION
SELECT CAST('defg' AS VARCHAR(10)) AS COLUMN1,
...
FROM ...
WHERE ...

String Concatenation
Example:
SELECT 'abc' || 'defg' AS COLUMN1,
...
FROM ...
WHERE ...

Derby and Oracle support the string concatenation operator || . MySQL doesn’t support this
operator and offers the function CONCAT(a, b, ...) instead.
Example:
SELECT CONCAT('abc', 'defg') AS COLUMN1,
...
FROM ...
WHERE ...

Result Set Restriction

All databases have their own SQL clauses to restrict the result set delivered by a query to the first
n records.
Derby offers a FETCH FIRST clause.
Example:
SELECT ...
FROM ...

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 67 of 68
Customizer Manual Report Definition Appendix

WHERE ...
FETCH FIRST 10 ROWS ONLY

MySQL offers a LIMIT clause.

Example:
SELECT ...
FROM ...
WHERE ...
LIMIT 10

Oracle offers a pseudo column ROWNUM that has to be used in a nested SELECT statement.
Example:
SELECT * FROM (
SELECT ...
FROM ...
WHERE ...
) WHERE ROWNUM <= 10

Data Types INT and SMALLINT

Oracle does not really support the data types INT and SMALLINT. By default INT and SMALLINT
are automatically replaced by NUMBER(38). This consumes too much space. Therefore INT has
to be replaced explicitly by NUMBER(10); and SMALLINT has to be replaced explicitly by
NUMBER(5).

Data Type VARCHAR(n)

VARCHAR(n) is reserved in Oracle. It has to be replaced by VARCHAR2(n). Oracle interprets the
maximum string length n as bytes by default, not as characters! Oracle interprets empty strings
(strings of length 0, e. g. '') as NULL! WHERE clauses using empty strings as condition (e. g.
COLUMN1 <> '') do not work on Oracle!

Data Type TIMESTAMP

The report engine expects that values of the data type TIMESTAMP are formatted like YYYY-MM-
DD HH:MM:SS (e. g. 2014-07-27 15:47:53). On Derby and MySQL this is the default. On Oracle
the default timestamp format depends on the locale and is rather unusual. Therefore the report
engine sets the default timestamp format on Oracle explicitly to the expected one using the SQL
statement ALTER SESSION SET NLS_TIMESTAMP_FORMAT='YYYY-MM-DD HH24:MI:SS'.

DROP TABLE
On Oracle tables are only dropped physically, if PURGE is added to the SQL statement.
Example:
DROP TABLE table1 PURGE

MySQL is the only database that supports fail-safe dropping of a table if the table doesn’t exist by
adding IF EXISTS to the SQL statement.
Example:
DROP TABLE IF EXISTS table1

Connections, Databases, Schemas, Users and Permissions

The meaning and handling of connections, databases, schemas, users and permissions differ
between Derby, MySQL and Oracle. For more details see the documentation of these database
engines.

Retail Software Solutions

Wincor Nixdorf Retail Division

Customizer_Manual_Report_Definition.docx Page 68 of 68