Use of the PDFCreator Integration Unit

Before you can use the PDFCreator Integration Unit, you need to install specially compiled libraries. You can install these using the following instructions:

1. The Integration Server must be stopped.

2. Remove the file ebd_jasperreports-6.0.0.jar from the ./lib directory, if it still exists.

3. Remove all batik-*.jar files from the ./lib directory, except batik-all-X.XX.jar.

4. Remove any existing Jasper libraries from the ./extlib directory. Only JDBC drivers and drivers for other purposes may be located there.

5. Unpack the delivered libraries into the ./extlib directory. The classes must not be located in any subdirectory.

6. Delete PDFCreator, if present, from the ./ext directory.

7. Restart the Integration Server.

8. Import the supplied sample profile and run it as a test.

Helpful links for Jaspersoft Studio

You can familiarize yourself with this application in advance with the help of the online tutorials:

• https://www.tutorialspoint.com/jasper_reports/jasper_report_sections.htm

• https://community.jaspersoft.com/documentation/tibco-jaspersoft-studio-user-guide/v60/report-elements

• https://www.oodlestechnologies.com/blogs/Using-Jasper-Reports-Part-1--%28Understanding-iReport-Elements%29

Usage of the test profile

After installing the libraries and restarting the Integration Server, import the test profile and start a new run.

If the profile runs without errors, you will receive a PDF file based on the Jasper report.

Create the profile

Create a new profile or use an existing profile.

If you are not yet certain about the source structure when creating a new profile, select the 'Data Routing' option in the basic data. This allows you to define the input agent and the source structure later.

The target structure should be as flat as possible at the beginning so that you can create a simple CSV file. In general, we recommend that all data you want to use in the report, whether dynamic or static, be pre-created and populated in the target structure.

Please note that the target structure fields and the fields in the report must have the same name. The path for an image, such as logos or other image files, can be passed to the report via the value of a field, allowing it to be dynamically transmitted to the reference data.

Using the integration unit 'CSVWithHeaderUnit' and the output path 'File' - 'Content of the IU', you can output a file in CSV format. This file is useful for creating the fields in Jaspersoft Studio in the further process.

Create a DataAdapter in Jaspersoft Studio

The creation of a data adapter supports you in setting up the report. You can use the preview to display the output and formatting of the PDF from the design.

Using the generated CSV file, you can create a data adapter in Jaspersoft Studio. The fields in the report are automatically generated using this. The field names are generated from the header of the CSV file.

To create a new data adapter using the generated CSV file, please proceed as follows:

• Switch to the Jaspersoft Studio.

• Create a new adapter under File - New - DataAdapter.

• Give the data adapter a descriptive name.

• Use the content of the data from CSV.

• Add the path to the CSV file.

• Adjust the separator under the 'Separators' tab.

• Check the 'Skip the first line' box.

• Adjust the encoding.

Create a report in Jaspersoft Studio

A new report is created in Jaspersoft Studio via File - New - JasperReport. The previously created data adapter can be added via the wizard.

By default, the report is created empty with the predefined properties and all bands. The bands are used to structure and display elements in the PDF. Please note that the detail band is the only band that allows the repetition of field values.

The Jaspersoft Studio is organized as follows:

• Project Explorer - The created and compiled reports and data adapters are listed here.

• Outline - This area is used to structure the report.

  • Report properties

  • Fields

  • Variables

  • Bands

• Palette - The palette contains elements that can be added to the report.

• Properties - Properties for displaying in bands and formatting the fields.

Create fields

Dynamically integrate images

If you want to add a dynamic logo or an image file to your PDF, create a field in the target structure that contains the path to this logo as a value. To do this, you can store the path as a fixed value via the field properties or use the 'copy' function on the field.

Please ensure that the path to the logo or image file can be reached from the Integration Server. It is advisable to store it within the Integration Server installation directory in the ./conf subfolder.

In Jaspersoft Studio, add an image element to the design of the report. Here you can store a previously created dynamic field via Properties - Image - Expression. The value of the field, which must contain a path to the image file, is resolved there. You can also work with fixed paths.

Click on the following link for an explanation of how to integrate images via an mklink:

https://learn.microsoft.com/de-de/windows-server/administration/windows-commands/mklink

Add barcodes

To integrate barcodes, you also use dynamic fields that you fill with your values.

In Jaspersoft Studio, add the desired barcode as an element in the design of the report. The reference to the values is formed by storing the dynamic field via Properties - Barcode - Expression.

If your barcode contains special control characters, these must be incorporated using variables within Jaspersoft Studio in order to obtain special fixed values. In this case, the string value in quotation marks and the variable with + V{Variable} must be adjusted under Properties - Barcode - Expressions.

Alternatively, you can use the 'create barcode (a, b, c, d)' function to create barcodes. This function creates a Base64-encoded barcode image, which you can save decoded using the 'write into file' function by setting the parameter d = true and use as an image file.

Compile report

In the last step, save the report and compile it by right-clicking in the Project Explorer - JasperReports - Compile Report. Save the generated *.jasper file in a directory to which the Integration Server has access.

Adjust the profile

Instead, you need the com.ebd.hub.datawizard.postexec.GeneratePdfPostExecuter, which you can copy into the field in phase 5 or phase 6 of a response path for post-processing.

For the unique selection of values in an XML file via XPath expressions, we recommend uniquely identifying the data records via IDs. To do this, you can extend the target structure so that the values are given unique numbers using the “iteration-level” function.

The profile generates an XML file using the 'XMLNoTemplateUnit' integration unit, which you can then use to generate the report.

To create the PDF, you need an additional response path of the type File with the following settings:

• Output of IU

• Encoding UTF8

• Postexecuter: com.ebd.hub.datawizard.postexec.GeneratePdfPostExecuter

The configuration file for the Postexecuter must contain the following parameters:

report_template = <Filename of Report>

report_format =1|2|3|4|5|6

• 1 => PDF

• 2 => CSV

• 3 => Rtf

• 4 => Odt

• 5 => Xls

• 6 => ZPL

report_folder = <Path to Jasper-File>

Create a DataAdapter with XPath expressions

Once the XML file has been created, it can be used to create the fields in the report using a data adapter and to create the report using them.

Use the wizard to create a new data adapter for the existing XML document via File - New - Data Adapter.

The required fields from the XML structure can then be added to the report using XPath expressions.

To check whether the XPath expressions read the required fields and values, you can use the plugin 'Test XPath' or search the Internet for common tools.

Create the report

Create a new report via File - New - JasperReport and add the stored data adapter.

The necessary fields can be added using XPath expressions. You can then set up your report as desired and display a preview of the PDF via the Preview tab.

Create subreports

If you want to work with subreports, add the basic element “Subreport” to your main report. A wizard appears in which you can integrate an existing report or create a new one.

As soon as this report has been created, compile it.

Within the properties of the main report, the path of the report is stored within the expression for linking. It is important that both jasper files are located in a directory to which the Integration Server has access.

Note: When using an XML via a data adapter, XML_DATA_DOCUMENT must be stored in the subreport parameters with the expression $P{XML_DATA_DOCUMENT}.

An example profile for an overview with reports and data adapters is available for download.

Subreport_Beispiel.zip

Missing classes

If certain libraries are missing for using the report and generating the PDF, a ClassNotFound exception will occur. Please send an extract of the libraries to our support for checking.

You can use the following links to check which missing classes are involved:

• https://mvnrepository.com/

• https://sourceforge.net/

Embedding images

When embedding an image with a dynamic path, an error message may appear if this image cannot be found:

A dynamically stored image path is stored in a field in the target structure. The field must then be created in Jaspersoft Studio with the same name.

Within the properties of an image element, the created field is stored under Properties - Image - Expression. The value of the field contains the path to the image file. You can also work with fixed paths in Jaspersoft Studio.

Please ensure that both the Integration Server and Jaspersoft Studio can access the path.

Report can not be compiled

When creating a PDF via a profile, you receive the following error message:

This is an error message that the report was not compiled correctly.

Please check whether the fields in the report have been adapted and formatted correctly. Then compile the report again.

Please also ensure that the correct, compiled version of the report is used.

Could not initialize class "net.sf.jasperreports.engine.util.JRStyledTextParser"

In this case, send an extract of the libraries to our support for checking.

Please check the ./lib directory for the ebd_jasperreport.jar file. If this library is present, you can delete it from the directory and restart the Integration Server.

If this error message occurs under Linux, please check whether the 'libfontconfig1' package is installed. To install the package, the following command can be issued in the console:

Is the package installed already, the following message will appear:

On Linux systems, an error may also occur if the dejavu-fonts font is required. A possible solution is to set the system property: -Djava.awt.headless=true