Custom PDF Generation on BrightServer

Description

This tutorial provides an example BEP which incorporates a script to construct a simple PDF file on BrightServer, using server records and the Apache FOP library. The files in this tutorial may be used as a starting point with the processes involved in PDF generation and may be reworked for more complex use cases. A BSP to create these records to send to the server is also included.

Resources

• TutorialPDF.bsp

• TutorialPDF.bep

• generic.xsl

• fop-1.1-bin.zip (FOP 1.1 binary - maybe be found here: http://archive.apache.org/dist/xmlgraphics/fop/binaries/)

FOP Library

The key to this tutorial is to demonstrate how to easily specify and utilise the FOP library in BrightServer projects. This library by Apache is an independent print formatter driven by XSL-FO, reading the tree and renders to the PDF output target (amongst others). This XSL-FO file may easily be created by transforming an XML file with the necessary data via BrightServer scripts, which will be detailed in the subsequent steps of this tutorial.

BrightServer comes shipped with a previous version of the FOP library - when executing this tutorial, ensure that this file 'fop.jar' is overwritten with version 1.1 binary, from the link listed in resources. Be sure to also include any libraries included with the binary. They may be placed in the 'lib' directory of BrightServer, with no conflicts occurring.

Once the library is updated, like other libraries, it may be imported within BrightServer scripts with the following code:

The classes of the package may then be imported, for example:

Record Processing

Record data is firstly created on the device, then synchronised to server data tables via standard synchronisation rules.

The PDF generation is handled by a job script contained in the BEP – ScriptGeneratePDFs. This script runs on an interval to check records, perform the export, then mark successfully exported records as processed. The EXPORT_STATUS field determines if a record is to be processed or not; it is populated to 0 on devices, and marked as 1 (processed) by the script.

Querying the database is handled by the JDBC object to query the server database, independent of synchronisation, such that only finalised records will be processed. For more information on using this library, please refer to the Using JDBC in Scripts tutorial of this document.

Once a record is processed, three files will be generated to the script's OUTPUT_PATH - the XML file containing the data, the FO file containing the data and formatting, and the final PDF document. The details of each of these files, and their relation to one another may be viewed in the section below. The final PDF is written to disk, with the file name "pdf_output_<record id>". Expanding on this project, this file may then be further processed by the script, such as be attached to emails.

Data Transformations

In order to create the PDF file, an XSL file is applied to the XML data, creating an XSL-FO file detailing the document's content. This file is then processed by the Apache FOP library, converted into PDF. A summary of these files are as follows:

• XML file - This file contains the data to be included in the report, without any formatting. It is generated in the script by querying the database, constructing an DOM tree with values and transforming this to XML output for subsequent transformations. As the XSL file is defined to recursively and exhaustively transform XML elements, the order which they are added will determine the order they will display in the resulting document.

• XSL file - contains definitions for the transforming the XML file's data in order to generate the FO file via XSL-FO transformation. The example generic.xsl file in this tutorial contains definitions for titles, subtitles, paragraphs, links, images and a table of data.

For more information on XSL specification, please refer to www.w3.org/TR/xsl/.

• FO file - The output of the XSL-FO transformation in the script. This file is the result of applying the XSL file to the XML data, and contains the formatting for the PDF document, with data populated from the XML document.

For more information on the XSL-FO and FO files and specification, please refer to http://xmlgraphics.apache.org/fop/fo.html. A list of FOP conformance in relation to this specification may be found here http://xmlgraphics.apache.org/fop/compliance.html.

• PDF file - The file generated by the Apache FOP library, using the definition in the FO file.

For more information on the Apache FOP library, please refer to http://xmlgraphics.apache.org/fop/.

On execution of this script, all files are created via this process may be inspected the OUTPUT_PATH directory (default C:/Tutorial/Outputs/). The generic.xsl file in this document must be placed in the TEMPLATE_PATH directory (default C:/Tutorial/Template/).

Example

The attached TutorialPDF.bsp file may be used to create order headers and order lines for PDF export. Before synchronising records to the server with this file, perform the following steps to configure the BEP:

• Configure DB in Sync Panel. Create the DB on the server, and use the 'Create Database Tables ...' option to create the TUTORIAL_HEADER and TUTORIAL_DETAIL records on this database.

  

• Ensure the path exists and is configured correctly in the ScriptGeneratePDFs script. Also, ensure the server database exists and is configured in the getConnection() function of the script. These values may be configured on lines 72-78 of the script:

  

If not already configured, update BrightServer's library directories as detailed under the FOP Library section of this tutorial.

Once this has been configured, continue to perform the following steps:

• Run the BEP, either by deploying and activating it on BrightServer, or by tapping the 'execute' button in BrightBuilder.

• Deploy the BSP, and synchronise the device to server.

• Create orders, then tap the 'Send to Server' button in the main menu. This will send records to the server for processing.

• Wait for the script to run, which may be verified by the server log in INFO. Files will be exported in the OUTPUT_PATH directory configured.

After the script runs, review the outputs generated. This code may be extended and reused for other projects requiring PDF generation on the server.