How to build report templates

Report templates are zip files containing all resources required to generate a report. This section describes the structure of report templates.

For a deep understanding of Jasper Reports the following sources are recommended:

Tooling

Jaspersoft Studio is the recommended tool by Jaspersoft to edit jrxml files.

Basic structure

A report template contains at least one single jrxml file, an XML file which describes the layout of the generated report.

The following code block shows a sample of a report which only prints a page header and footer. It can be considered as a minimal report template.

sample.jrxml
<?xml version="1.0" encoding="UTF-8"?>
<jasperReport
    xmlns="http://jasperreports.sourceforge.net/jasperreports"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://jasperreports.sourceforge.net/jasperreports http://jasperreports.sourceforge.net/xsd/jasperreport.xsd"
    name="Test" pageWidth="595" pageHeight="842" whenNoDataType="AllSectionsNoDetail"
    columnWidth="555" leftMargin="20" rightMargin="20" topMargin="20" bottomMargin="20"
    uuid="3404c519-e6e3-4a8c-ba35-4f49f7561b1a">
    <background>
        <band splitType="Stretch"/>
    </background>
    <title>
        <band splitType="Stretch"/>
    </title>
    <pageHeader>
        <band height="50" splitType="Stretch">
            <line>
                <reportElement x="0" y="36" width="555" height="1" uuid="1f3f78b4-8e27-4d14-bf42-b78a56195112"/>
            </line>
            <staticText>
                <reportElement x="0" y="14" width="315" height="20" uuid="bb0ae07d-f417-47dc-8b52-982f02b6f99e"/>
                <textElement>
                    <font isBold="true"/>
                    <paragraph leftIndent="10" rightIndent="10"/>
                </textElement>
                <text><![CDATA[Sample Report]]></text>
            </staticText>
        </band>
    </pageHeader>
    <columnHeader>
        <band splitType="Stretch"/>
    </columnHeader>
    <detail>
        <band height="24" splitType="Stretch">
        </band>
    </detail>
    <columnFooter>
        <band splitType="Stretch"/>
    </columnFooter>
    <pageFooter>
        <band height="34" splitType="Stretch">
            <textField>
                <reportElement x="164" y="10" width="80" height="20" uuid="6b60238f-9f9d-4653-acff-9faffc2570ee"/>
                <textElement textAlignment="Right"/>
                <textFieldExpression><![CDATA["Page "+$V{PAGE_NUMBER}+" of"]]></textFieldExpression>
            </textField>
            <textField evaluationTime="Report">
                <reportElement x="244" y="10" width="40" height="20" uuid="c4dafacf-0621-4abe-99f5-d1df21c004de"/>
                <textFieldExpression><![CDATA[" " + $V{PAGE_NUMBER}]]></textFieldExpression>
            </textField>
            <line>
                <reportElement x="0" y="6" width="555" height="1" uuid="1732aabe-c5b2-49e5-9bd4-785a6ae75c89"/>
            </line>
            <textField pattern="yyyy-MM-dd HH:mm:ss">
                <reportElement x="455" y="10" width="100" height="20" uuid="eccec6c9-ef07-46a4-b6cd-b67a582d080b"/>
                <textFieldExpression><![CDATA[new java.util.Date()]]></textFieldExpression>
            </textField>
        </band>
    </pageFooter>
    <summary>
        <band splitType="Stretch"/>
    </summary>
</jasperReport>
The attribute whenNoDataType="AllSectionsNoDetail" on the root <jasperReport> element is required. Otherwise a blank page is produced.

Reference resources

Included in the jrxml file any other kind of file can be part of a report template. A typical example is for example an image file which should be used as a logo inside the report.

The structure of the report template can be extended like this:

/+- sample.jrxml
 +- logo.png

The path that references the image file inside the jrxml file is the filename logo.png.

sample.jrxml extended with logo
<?xml version="1.0" encoding="UTF-8"?>
<jasperReport ...>
...
    <pageHeader>
        <band height="50" splitType="Stretch">
            ...
            </staticText>
            <image>
                <reportElement x="430" y="9" width="125" height="40" uuid="18cab714-55f3-4b3c-a542-055dd1c6238c"/>
                <imageExpression><![CDATA["logo.png"]]></imageExpression>
            </image>
        </band>
    </pageHeader>
...

If images are stored in sub folders, the structure might look like this:

/+- sample.jrxml
 +- images
     +- logo.png

The path used to reference the file from the jrxml file is "images/logo.png".

sample.jrxml extended with a logo
<?xml version="1.0" encoding="UTF-8"?>
<jasperReport ... >
...
    <pageHeader>
        <band height="50" splitType="Stretch">
            ...
            </staticText>
            <image>
                <reportElement x="430" y="9" width="125" height="40" uuid="18cab714-55f3-4b3c-a542-055dd1c6238c"/>
                <imageExpression><![CDATA["images/logo.png"]]></imageExpression>
            </image>
        </band>
    </pageHeader>
...

Fields

A field defines an access name and the type of a value inside one row (or feature) of a data source. A field value can be accessed in data expressions using the $F{<field name>} syntax.

<!-- declare a well-known field of an entry in the data source -->
<field name="Name" class="java.lang.String"/>

<!-- now this can be used to access the value of a field -->
<staticText>
      ...
     <text><![CDATA[$F{Name}]]></text>
</staticText>

<!-- also methods of the value instance can be called -->
<staticText>
      ...
     <text><![CDATA[$F{Name}.toLowerCase()]]></text>
</staticText>

Parameters

A parameter defines a static constant or a value required to be set before report generation. A parameter value can be accessed in data expressions using the $P{<parameter name>} syntax.

<!-- a constant -->
<parameter name="ARCGIS_SERVER_BASE_URL" class="java.lang.String" isForPrompting="false">
  <defaultValueExpression><![CDATA[http://localhost:6090/arcgis/services]]></defaultValueExpression>
</parameter>

<!-- a required parameter -->
<parameter name="FEATURE_IDS" class="java.lang.String" isForPrompting="true"></parameter>

<!-- use a parameter -->
<staticText>
      ...
     <text><![CDATA[$P{ARCGIS_SERVER_BASE_URL}]]></text>
</staticText>

The JasperReport engine provides some built-in parameters, which do not need to be declared.

Here is a list of some of the generated parameters.

Name Description

REPORT_PARAMETERS_MAP

Contains a map with all user defined and built-in parameters

REPORT_CONNECTION

User supplied java.sql.Connection used for JDBC data sources

REPORT_DATA_SOURCE

User supplied instance of JRDataSource representing either one of the built-in data source types or a user-defined one

REPORT_MAX_COUNT

A java.lang.Integer value, allowing the users to limit the records from data source.

REPORT_SCRIPTLET

Points to net.sf.jasperreports.engine.JRAbstractScriptlet and contains an instance of the report scriptlet provided by the user, with the global scriptletClass attribute.

REPORT_LOCALE

A java.util.Locale instance, containing the locale required by the resource bundle

REPORT_RESOURCE_BUNDLE

Points to java.util.ResourceBundle object and contains localized messages

REPORT_TIME_ZONE

A java.util.TimeZone instance, used for date formatting

REPORT_VIRTUALIZER

An instance of net.sf.jasperreports.engine.JRVirtualizerobject, used for page virtualization (optimize memory consumption)

REPORT_CLASS_LOADER

A java.lang.ClassLoader instance to be used during the report filling process to load resources such as images, fonts and subreport templates

IS_IGNORE_PAGINATION

If set to java.lang.Boolean.TRUE the report is generated on one long page and page break does not occur

JASPER_REPORT

The current report instance

Variables

A variable can be used to encapsulate frequently used data expressions and to perform some calculations. A variable value can be accessed in data expressions using the $V{<variable name>} syntax.

<!-- declare a variable -->
<variable name="FeatureTitle" class="java.lang.String">
        <variableExpression><![CDATA["This is feature " + $F{Name}]]></variableExpression>
</variable>

<!-- use a variable -->
<staticText>
      ...
     <text><![CDATA[$V{FeatureTitle}]]></text>
</staticText>

The JasperReport engine provides some built-in variables, which do not need to be declared.

Here is a list of some of the generated variables.

Name Description

PAGE_NUMBER

Current page number. It can be used to display both the current page number and the total number of pages using a special feature of JasperReports text field elements, the evaluationTime attribute.

COLUMN_NUMBER

Current column number

REPORT_COUNT

Total number of records processed.

PAGE_COUNT

Number of records that were processed when generating the current page.

COLUMN_COUNT

Number of records that were processed when generating the current column.

<GroupName>_COUNT

Derived from the name of the group it corresponds to, suffixed with the _COUNT sequence. This variable contains the number of records in the current group.

Scriptlets

map.apps ships with an extension for JasperReports that allows to include feature information provided by an ArcGIS Server into a report. This extension is built on top of the scriptlet mechanism of Jasper Reports.

A scriptlet is an Java class which extends the class net.sf.jasperreports.engine.JRDefaultScriptlet or net.sf.jasperreports.engine.JRAbstractScriptlet.

To ensure that a report can use a scriptlet the compiled class must be deployed inside a JAR archive and copied to the WEB-INF/lib folder of the map.apps web application. If a scriptlet requires other Java libraries, these must also be installed into the WEB-INF/lib folder.

Within a jrxml file a scriptlet can be used in two ways: As default scriptlet or as scriptlet tag:

default scriptlet
<?xml version="1.0" encoding="UTF-8"?>
<jasperReport scriptletClass="de.company.MyScriptlet" ...>
...
    <pageHeader>
        <band height="50" splitType="Stretch">
            <staticText>
                ...
                <text><![CDATA[$P{REPORT_SCRIPTLET}.methodNameInTheClass()]]></text>
            </staticText>
        </band>
    </pageHeader>
...
scriptlet tag
<?xml version="1.0" encoding="UTF-8"?>
<jasperReport ...>
...
    <scriptlet name="myscriptlet" class="de.company.MyScriptlet"/>
...
    <pageHeader>
        <band height="50" splitType="Stretch">
            <staticText>
                ...
                <text><![CDATA[$P{myscriptlet_SCRIPTLET}.methodNameInTheClass()]]></text>
            </staticText>
        </band>
    </pageHeader>
...

Map scriptlet

This scriptlet allows the production of map images inside the report. To generate map images the scriptlet communicates with a ArcGIS Server Print Task.

de.conterra.reporting.jasper.agsds.ScriptletCTMap

All parameters except CT_MAP_PRINT_TASK_URL have to be appended with a postfix of the form @<name>, for example CT_MAP_MAP_EXTENT@overview.

This postfix is also provided in the image generation methods of the scriptlet, for example <![CDATA[$P{REPORT_SCRIPTLET}.getURLForPrintImage("overview","elementName")]]>

This allows a different specification of parameters for different method calls.

Following report parameters can be defined.

Parameter Description Comments and Examples

CT_MAP_PRINT_TASK_URL

The URL of the ArcGIS Server Print Task used to generate map images.

The Export Web Map Task (name of the print task) needs to be published as synchronous job at the ArcGIS Server.

http://example.com:6080/arcgis/rest/services/ExportWebMap/GPServer/Export%20Web%20Map

CT_MAP_MAP_SCALE

Scale of the map image.

10000, the value EMPTY means that the extent defines the scale

CT_MAP_DPI

Defines the print quality of the image, dots per inch (DPI).

92, default is 96

CT_MAP_EXTENT_TYPE

Defines the algorithm how the scriptlet calculates the extent of the map image.

MANUAL

FROM_SELECTION

FROM_MARKER_POINT

CT_MAP_MAP_EXTENT

Explicit definition of the map extent. This parameter is only required if the algorithm is MANUAL (see CT_MAP_EXTENT_TYPE).

7.6,52.5,7.7,52.6 (xmin, ymin, xmax, ymax)

CT_MAP_MAP_EXTENT_SR_WKID

EPSG number of the spatial reference system of the extent. If CT_MAP_MAP_EXTENT is specified, this parameter is required,

4326

CT_MAP_POSITION_RECTANGLE

A polygon drawn on the map to display an area. At least 4 points have to be specified.

7.6,52.5;7.6,52.5;7.6,52.5;7.6,52.5;7.6;…​ Syntax: p1.x,p1.y;p2.x,p2.y;…​

CT_MAP_POSITION_RECTANGLE_SR_WKID

EPSG number of the spatial reference system of the polygon.

CT_MAP_POSITION_RECTANGLE_SYMBOL_STYLE

The style of the line symbol.

default: esriSLSSolid

CT_MAP_POSITION_RECTANGLE_SYMBOL_COLOR

The color of the line symbol.

255,0,0,255 (r,g,b,a)

CT_MAP_POSITION_RECTANGLE_SYMBOL_WIDTH

The width of the line symbol.

1

CT_MAP_MARKER_POINT

Defines the position of a marker on the map.

7.6,52.5 (x,y)

CT_MAP_MARKER_POINT_SR_WKID

EPSG number of the spatial reference system of the marker.If CT_MAP_MARKER_POINT is specified, this parameter is required.

4326

CT_MAP_MARKER_POINT_SYMBOL_URL

URL of an image which should be used as symbol for the marker. This image must be accessible from the print task specified in CT_MAP_PRINT_TASK_URL.

http://example.com/images/symbol_city.png

CT_MAP_MARKER_POINT_SYMBOL_IMAGE_DATA

Base64 encoded bytes of the marker symbol image. This is an alternative to the CT_MAP_MARKER_POINT_SYMBOL_URL parameter, which is not network dependent.

CT_MAP_MARKER_POINT_SYMBOL_WIDTH

Width of the marker symbol.

13

CT_MAP_MARKER_POINT_SYMBOL_HEIGHT

Height of the marker symbol.

12

CT_MAP_MARKER_POINT_SYMBOL_XOFFSET

Offset of the position of the symbol image in x direction from the point specified by CT_MAP_MARKER_POINT.

0

CT_MAP_MARKER_POINT_SYMBOL_YOFFSET

Offset of the position of the symbol image in y direction from the point specified by CT_MAP_MARKER_POINT.

0

CT_MAP_MARKER_POINT_SYMBOL_ANGLE

Rotates the symbol image by the specified angle.

CT_MAP_BL_{NAME}_TYPE

Type of the base layer {NAME}

Shared

CT_MAP_BL_{NAME}_URL

Url of the base layer {NAME}

http://services.arcgisonline.com/ArcGIS/rest/services/World_Topo_Map/MapServer

CT_MAP_BL_{NAME}_OPACITY

Opacity value of the base layer {NAME}

0.5 A value between 0 and 1, 0 = full transparent, 1 = full visible

CT_MAP_OL_{NAME}_TYPE

Type of the operational layer {NAME}

MapService

WMS

CT_MAP_OL_{NAME}_URL

URL of the operational layer {NAME}

http://services.arcgisonline.com/ArcGIS/rest/services/World_Topo_Map/MapServer

CT_MAP_OL_{NAME}_TOKEN

Token for token based protected services

uusEC76qlwh1JehDJh8_RMF6RxD7GIBXfpu0gwyusFx6jrydDeb7ZHkvxpuRwmGi

CT_MAP_OL_{NAME}_OPACITY

Opacity value of the operational layer {NAME}

0.5 A value between 0 and 1, 0 = full transparent, 1 = full visible

CT_MAP_OL_{NAME}_VISIBLE_LAYERS

Visible layers of the operational layer {NAME}

0,1

CT_MAP_OL_{NAME}_VERSION

Version of the operational layer. This is the WMS-Version and therefore only of interest if TYPE is WMS.

1.1.1

CT_MAP_OL_{NAME}_FORMAT

Output format of the image produced by the operational layer. This is only of interest if TYPE is WMS.

Default ist png24

CT_MAP_OL_{NAME}_TRANSPARENT_BACKGROUND

Should NO DATA values be transparent in the created image. This is only of interest if TYPE is WMS.

Default ist true

CT_MAP_OL_DRAWING_ORDER

This is the drawing order of operational layers. The first layer in the list is interpreted as top most layer.

"streets,topo"

CT_MAP_SELECTION_URL

URL of Layer of an ArcGIS Server map service or feature service which is the selection data source

http://services.arcgisonline.com/ArcGIS/rest/services/World_Topo_Map/MapServer/0

CT_MAP_SELECTION_FILTER

"Where" expression used to select features in the data source

CT_MAP_SELECTION_FILTER_OBJECTIDS

List of object IDs which define the filter for the selection.

0,1,2,3

CT_MAP_SELECTION_FILTER_SORTFIELDS

List of order by fields appended to the selection query

name ASC, date DESC

CT_MAP_SELECTION_FILTER_MAX_RECORDS

Constrain selection to maximal amount of features

100

CT_MAP_SELECTION_FILTER_FROM_DATASOURCE_FILTER

Flag if the filter expression used for the main report data source should be appended to the selection filter expression.

Boolean.FALSE

CT_MAP_SELECTION_SCALE_FOR_POINT_EXTENT

Fall-back parameter required if CT_MAP_EXTENT_TYPE is set to FROM_SELECTION and the calculated extent is a point. This parameter defines a scale to correct the selection extent

5000

CT_MAP_SELECTION_DRAWINGINFO

JSON string defining the drawing info for the selection layer

CT_MAP_SELECTION_POINT_SYMBOL_URL

URL of an image which should be used as symbol for point features from the selection

CT_MAP_SELECTION_POINT_SYMBOL_IMAGE_DATA

Base64 encoded image which should be used as symbol for point features from the selection

CT_MAP_SELECTION_POINT_SYMBOL_WIDTH

Width of the symbols for points

13

CT_MAP_SELECTION_POINT_SYMBOL_HEIGHT

Height of the symbols for points

12

CT_MAP_SELECTION_POINT_SYMBOL_XOFFSET

Offset of the position of the symbol image in x direction from the point location

0

CT_MAP_SELECTION_POINT_SYMBOL_YOFFSET

Offset of the position of the symbol image in y direction from the point location

0

CT_MAP_SELECTION_POINT_SYMBOL_ANGLE

Rotates the symbol image by the specified angle.

CT_MAP_SELECTION_POLYGON_OUTLINE_COLOR_NAME

Well-known name of the outline color of selection polygons

red

CT_MAP_SELECTION_POLYGON_OUTLINE_COLOR_RGBA

Color of the outline of selection polygons

255,0,0,255 (r,g,b,a)

CT_MAP_SELECTION_POLYGON_OUTLINE_COLOR_OPACITY

Opacity value of the selection polygons. It overwrites the alpha value of CT_MAP_SELECTION_POLYGON_OUTLINE_COLOR_RGBA if provided

0.5 A value between 0 and 1, 0 = full transparent, 1 = full visible

CT_MAP_SELECTION_POLYGON_OUTLINE_WIDTH

Width of the outline of selection polygons

1

CT_MAP_SELECTION_POLYGON_OUTLINE_STYLE

Style of the outline of selection polygons

esriSLSSolid

CT_MAP_SELECTION_POLYGON_FILL_COLOR_NAME

Well known name of the fill color of selection polygons

red

CT_MAP_SELECTION_POLYGON_FILL_COLOR_RGBA

Fill color of the selection polygons

255,0,0,255 (r,g,b,a)

CT_MAP_SELECTION_POLYGON_FILL_COLOR_OPACITY

Fill opacity value of the selection polygons. It overwrites the alpha value of CT_MAP_SELECTION_POLYGON_FILL_COLOR_RGBA if provided

0.5 A value between 0 and 1, 0 = full transparent, 1 = full visible

CT_MAP_SELECTION_POLYGON_FILL_STYLE

Fill style of the selection polygons

esriSFSSolid

CT_MAP_SELECTION_POLYLINE_COLOR_NAME

Well known name of the fill color of selection polylines

red

CT_MAP_SELECTION_POLYLINE_COLOR_RGBA

Color of the selection polylines

255,0,0,255 (r,g,b,a)

CT_MAP_SELECTION_POLYLINE_COLOR_OPACITY

Opacity value of the selection polylines. It overwrites the alpha value of CT_MAP_SELECTION_POLYLINE_COLOR_RGBA if provided

0.5 A value between 0 and 1, 0 = full transparent, 1 = full visible

CT_MAP_SELECTION_POLYLINE_WIDTH

Width of the selection polylines

1

CT_MAP_SELECTION_POLYLINE_STYLE

Style of the selection polylines

esriSLSSolid

CT_MAP_WEB_MAP_AS_JSON

A webmap JSON definition as direct input to the print task.

The scriptlet provides following methods:

Method syntax Description 
String getURLForPrintImage(
   String parameterPostfix,
   String reportElementKey
)

Executes the print task and returns the URL of the created map image.

Parameter:

parameterPostfix

for example "ov", group identifier for the parameters

reportElementKey

for example "OverviewMap" the value of a key attribute of a reportElement, which defines width and height of the image

 
String getURLForPrintImage(
   String parameterPostfix,
   String reportElementKey,
   boolean initParameters
)

Executes the print task and returns the URL of the created map image.

Parameter:

parameterPostfix

for example "ov", group identifier for the parameters

reportElementKey

for example "OverviewMap" the value of a key attribute of a reportElement, which defines width and height of the image

initParameters

true | false, defines that the variables and parameters should be recalculated. This is important if map images are created based on dynamic variables.

 
Image getImageForPrintImage(
   String parameterPostfix,
   String reportElementKey,
   boolean transparent,
   boolean grayScale)

Executes the print task and returns the created map image.

Parameter:

parameterPostfix

for example "ov", group identifier for the parameters

reportElementKey

for example "OverviewMap" the value of a key attribute of a reportElement, which defines width and height of the image

transparent

true | false, defines that the image should be transparent

grayScale

true | false, defines that the image should be converted to grayscale

 
Image getMergedImages(
   Image image1,
   Image image2
)

Merges two images

ArcGIS server data source

Part of the JasperReports extension is the ESRIAGSCustomDataSource which allows to iterate over features of an ArcGIS Server map service or feature service.

To create a report data source the queryString element must be provided and the report has to be initialized without any data source.

<!-- the query string has following syntax -->
<URL>;<'query' | 'objectids'>; < query string | object ID list >;( <sort fields>; <maxrecords> )?

<!-- Sample for a data source initialization with an object ID query -->
<queryString language="ags">
        <![CDATA[http://services.arcgisonline.com/ArcGIS/rest/services/World_Topo_Map/MapServer/0;objectids;1,2,3]]>
</queryString>

<!-- Sample for a data source initialization with a where clause -->
<queryString language="ags">
        <![CDATA[http://services.arcgisonline.com/ArcGIS/rest/services/World_Topo_Map/MapServer/0;query;OBJECTID>0]]>
</queryString>

<!-- Sample for a data source initialization with a where clause and sort field and max records -->
<queryString language="ags">
        <![CDATA[http://services.arcgisonline.com/ArcGIS/rest/services/World_Topo_Map/MapServer/0;query;OBJECTID>0;OrgFullName ASC;100]]>
</queryString>

<!-- Sample for a data source initialization with a where clause and only maxrecords (note the double ;;) -->
<queryString language="ags">
        <![CDATA[http://services.arcgisonline.com/ArcGIS/rest/services/World_Topo_Map/MapServer/0;query;OBJECTID>0;;100]]>
</queryString>

Reference a field value of a feature:

<!-- first define the field -->
<field name="title" class="java.lang.String"/>

<!-- now the following expression is allowed during the iteration of the features -->
<textField>
    ...
    <textFieldExpression>
        <![CDATA["Title of object is: " + $F{title}]]>
    </textFieldExpression>
</textField>

Iterate all fields of a feature:

<!-- first define a sub dataset -->
<subDataset name="NameValueDataset">
        <field name="Name" class="java.lang.String"/>
        <field name="Value" class="java.lang.String"/>
</subDataset>

<!-- A dataset run can be defined, for example for iteration within a table -->

<jr:table>

    <datasetRun subDataset="NameValueDataset">
        <dataSourceExpression>
            <![CDATA[((de.conterra.reporting.jasper.agsds.ESRIAGSCustomDataSource)$P{REPORT_DATA_SOURCE}).createAGSFeatureGenericJRDatasource()]]>
        </dataSourceExpression>
    </datasetRun>

    <!-- within this dataset run the fields Name and Value can be accessed -->
    <jr:column width="155">
        <jr:detailCell height="20" rowSpan="1">
            <textField>
                ...
                <textFieldExpression>
                    <![CDATA[$F{Name}]]>
                </textFieldExpression>
            </textField>
        </jr:detailCell>
    </jr:column>

    <jr:column width="155">
        <jr:detailCell height="20" rowSpan="1">
            <textField>
                ...
                <textFieldExpression>
                    <![CDATA[$F{Value}]]>
                </textFieldExpression>
            </textField>
        </jr:detailCell>
    </jr:column>
</jr:table>