Introduction
The Eclipse Business Intelligence and Reporting Tools (BIRT) is an open source framework that allows developers to build production ready reports. BIRT provides a basic WebViewer to deploy reports, but this solution is not ideal as a production ready system. The WebViewer does not support security, content management, email, or security, in addition, the solution is not designed to scale up or plug into a modern service bus architecture.
Businesses that wanted to deploy BIRT reports have been left with creating their own deployment of the BIRT Report Engine API (REAPI). Creating a simple REAPI implementation is not difficult, but a full featured production ready system presents a number of challenges. Our goal was to make it easier to quickly deploy BIRT into a production system with all of BIRT's features available.
The Spring Boot framework makes it very easy to quickly build services based applications. Using spring-boot-starters, developers can quickly easily add functionality to their applications. Convention over configuration is a core philosophy in Spring Boot, by giving up some configuration options developers gain a lot of easy to use function. Spring Cloud applies this philosophy into Cloud deployments.
After building a variety of Spring Boot BIRT implementations, Innovent decided to start over and create an open source birt-spring-boot-starter project that makes it easy for any Spring Boot or Spring Cloud application to quickly add BIRT reporting to their application. This article is the first in a series of articles that will demonstrate using the birt-spring-boot-starter. The articles are as follows:
- Getting Started with the BIRT-Spring-Boot-Starter (current)
- BIRT-Spring-Boot-Starter for Spring Cloud Applications (coming soon)
- Email and Scheduling with the BIRT-Spring-Boot-Starter (coming soon)
- Report Level Security with the BIRT-Spring-Boot-Starter (coming soon)
Step by Step Guide
Using the BIRT-Spring-Boot-Starter involves adding a dependency on the birt-spring-boot-starter and setting up the Workspace for the project. This Step by Step will walk you through both of these steps. Experienced Spring-Boot developers will be able to skip most of the Add Dependency section (skip to instruction 5). Everyone needs to configure a Workspace.
In all of the demos, we have used the Spring Tools Suite (STS) 4.0 to build our Spring Boot projects. We have also developed our reports using the BIRT 4.8.0.
NOTE: For this article, we assume that you have already worked with the BIRT designer to create some report designs. If you would like some help with that, you might want to reach out to us for our BIRT-Training course. Innovent Solutions has been a member of the BIRT project since inception in 2004. Over the years, we have helped hundreds of users to develop reports for all types of applications and purposes. Our consultants have the expertise to help you with BIRT report development.
Add BIRT-Spring-Boot-Starter as Dependency
Many of you may have already worked with Spring-Boot. If you have, you skim through most of this guide to Step 6 of this section.
Using the birt-spring-boot starter is very simple and can be summarize in two steps:
- Add the birt-spring-boot-starter as a dependency to your project
- Provide a Workspace for your birt-spring-boot-starter
The easiest way to explain things is to just go ahead and walk through the steps required to get a project running. For this example, I am assuming you are using Spring Tool Suite 4 and have BIRT reports build using BIRT version 4.80. We will be creating a new blank project, adding the birt-spring-boot-starter, and then adding an example birt-engine-workspace.
- Create a new spring-boot-project by selecting File->New->Spring Starter Project.
- Fill out the New Spring Starter Project by entering a Name, Group, and Artifact. The majority of the items can be left as defaults.
Click Next when you have filled in at least the Name, Group, and Artifact. - On the next dialog, you can add additional Spring-Boot-Starter content, but for now we will have the simplest project possible.
- Spring Tool Suite will create a new Project for you. In that project, you will find four files. An application, an application.properties, an application test, and the pom.xml. The Maven pom file is used to control your projects dependencies and build cycle. In general, spring-boot projects are smart and will have the appropriate configuration options. Opening the pom.xml file will show you that the project already has one dependency on spring-boot-starter, which is typically the root starter used in all Spring-boot projects.
- To make your project work with the birt-spring-boot-starter, you simply add a dependency to the project in your dependencies section. This can be done by either editing the XML directly (shown first) or by selecting the dependency tab, click add new dependency and fill out the dialog appropriately.
edit the pom.xml file directly<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter</artifactId>
</dependency>
<dependency>
<artifactId>com.innoventsolutions.birt-spring-boot</artifactId><groupId>birt-spring-boot-starter</groupId>
<version>0.0.7</version>
</dependency>...
or add using the UI - Once you have made this addition to your pom.xml file, save the file. Maven will download the required dependencies and your project should now have all of the required BIRT components added. Using the Boot Dashboard, you should be able to run your project either in regular or debug mode.
When you run your project, you will get a WARN error in the console that looks something like:2020-04-13 13:01:16.204 WARN 8278 --- [ main] c.innoventsolutions.birt.BirtProperties : Design Dir does not exist or is not a folder.Workspace Location: /Users/scottr/Documents/workspace/birt-engine-workspace (does not exist)Design Dir: /Users/scottr/Documents/workspace/birt-engine-workspace/rptdesign (does not exist)Check application.properties file - The error indicates that you have not setup the workspace directory correctly. Please see the next section that describes the Workspace.
Configure the Workspace
Eclipse projects (and BIRT reports are based on Eclipse) are based off the concept of a workspace. A workspace is a root folder that serves as the base for the relative paths to other directories and folders. The birt-spring-boot-starter uses this same concept with the BIRT workspace acting as the root directory for all file access, this includes:
- Birt Report designs
- Output documents (for asynchronous requests)
- Logging
- BIRT Event handler java classes
- Report file dependencies including
- Data
- CSS
- JavaScript
- Properties
- Report Libraries
By default the workspace is named birt-engine-workspace and it should be a sibling folder to the folder that holds the spring-boot project. The location of the workspace folder can be configured through application.properties entries, but the easiest thing to do is to just create a new project in STS with the same parent folder as your spring-boot project with the required folders in it. Innovent hosts a public GitHub project with a starter workspace named innoventsolutions/birt-engine-workspace. Importing this project into your STS workspace is the quickest way to get up and running with the birt-spring-boot-starter.
To add the birt-engine-workspace to your STS workspace perform the following steps:
NOTE: There are a lot of ways to import Git projects into STS, use the one that you are most comfortable with. For this example, you need to click Next on each step or it will take you on a slightly different path.
- Select File -> Import and select Git in the search window
- Select Clone URI from the Import dialog
Click Next - Enter https://github.com/innoventsolutions/birt-engine-workspace for the location of the GitHub repository to clone.
Click Next - Select the Master branch
Click Next - Select the Directory location for the new project, you may need to adjust this path to match the directory where your spring-boot-project has been setup. For my STS instance, my workspace is /Users/scottr/Documents/workspace.
click Next - Select the wizard you will use to Import the project. Since this is just a folder structure, you should select the Import as a general project.
Click Next - Name the project, you should accept the default value and finally, you can press Finish.
Click Finish - You will now have a directory structure complete with appropriate test report designs in your workspace. This project should share a common parent with your spring-boot project that is using the birt-spring-boot-starter.
- If you restart that project, you should not see the warning message in your console log anymore.
Run the Test Reports Using the Built in REST Endpoints
The birt-spring-boot-starter has a number of built in end points and reports available. But to make life easy, we have included a couple of sample end points that can be invoked from any web browser. To test, open a browser and enter the following URL:
http://localhost:8080/testPDF
It may take a couple of seconds, but you should see a report, named test_report.pdf downloaded from your browser. You will also see a message in your STS console showing the test report getting run.
The starter comes with two other test end points:
http://localhost:8080/testHTML which will deliver the report as a HTML doc.
http://localhost:8080/testSubmit which will generate 10 reports into the output directory using the Asynchronous submitJob endpoint. You will see the log messages in the console and you will see the reports generated in the birt-engine-workspace/output directory.
Using the REST API
Now that you have your spring boot application using Spring, the easiest way to access reports is through the REST endpoints, which are documented in the birt-engine-workspace project. If you open the rest-api-doc folder and open the rest-api.html using the Open With Web Browser, you will see the documentation for the built in end points.
The simplest endpoint to use is /runReport which is a Post request with a JSON body that specifies a few simple parameters. In order to Post a message with a JSON body, you will need either an application or a tool like Postman. The following screen capture shows running a report with the available parameters. As you can see in the response (bottom of the dialog) the report content is returned in line since we have requested an HTML format. Changing the format to PDF would get a PDF response that you would need to download and open using a tool like Acrobat. The runReport is a Synchronous request, meaning that the response will contain the formatted document. When using this end point, no documents will be created in the output folder.
In general, you should use the runReport endpoint for reports that run relatively quickly. Working with the report designs that are already included in the /rptdesigns folder you can run test out these endpoints.
For longer running reports or for reports that will be scheduled or emailed, you should use the SubmitJob endpoint which is an Asynchronous endpoint. When using submitJob, you will get a response with a jobId. Using the jobId you can then call GetReport, WaitForJob, or DeleteJob to get the report document in the specified output format. Since these jobs run asynchronously, you will see an intermediate (.rptdocument) and a final (e.g. pdf, html...) document in the output folder for each successful submitJob.
If you would like to run your own reports, you would add them to the birt-engine-workspace/rptdesign folder and request them through either runReport or submitJob. When you run your own report, you will probably want to pass parameters along with the report request. The following JSON body requests a report based on the param_test.rptdesign with four parameters.
{ "designFile": "param_test.rptdesign", "outputName": "failure_out", "format": "xyx", "parameters": { "paramString": "This is a test string", "paramInteger": "1111", "paramDate": "2010-05-05", "paramDecimal": "999.888" }, "wrapError": true}
Application.properties
Like any Spring Boot application, the birt-spring-boot-starter uses the application.properties file to configure the application. All of the birt-spring-boot-starter properties have context sensitive help. Simply open your resources/application.properties file and type birt.runner. and the available properties will show up.
The following section provides a list of all of the birt-spring-boot-starter application.properties that can be controlled, default values for the properties are shown, override these values if you would like to change the where your files are located.
#Root directory for file access in birt-spring-boot-starter
birt.runner.workspace=../birt-engine-workspace
#Location for BIRT report designs that will be run.
#Add your own designs to this location
birt.runner.designDir=${birt.runner.workspace}/rptdesign
#Location for log files that are generated by the report engine
#Log files generated by spring boot should be configured in standard way
birt.runner.loggingDir=${birt.runner.workspace}/log
#location for temp output files (.rptdocument) and final formatted docs (.pdf, .HTML, .docx...)
#only used for the submitJob
birt.runner.outputDir=${birt.runner.workspace}/output
#Provides the base for relative paths used in reports
#e.g. path to rptlibrary, css, properties, js, etc.
#should correlate to same relative path as set in your BIRT designer
birt.runner.resourceDir=${birt.runner.workspace}
#Location for Java libraries for BIRT event handlers
birt.runner.scriptLibDir=${birt.runner.workspace}/lib
#Location intermediate image files (for charts) are generated too
birt.runner.baseImageURL=${birt.runner.workspace}/images
#The birt runner can run commercial OpenText reports.
#This option requires a licensed version of BIRT (provided by OpenText)
birt.runner.birtRuntimeHome=not-specified
#Maximum number of concurrent runReport threads
birt.runner.runReportPoolSize=10
#Maximum number of concurrent submitJob threads
birt.runner.submitJobPoolSize=10
Next Steps
Hopefully, this article is helpful and explains the basics for using the birt-spring-boot-starter. In our next article we are going to explore using the birt-spring-boot-starter in a simple cloud configuration along with Eureka, Zuul, and a simple security scheme. We will also be publishing articles on how to add scheduling and email to the birt-spring-b0ot-starter. Finally, we will be presenting an article that offers user and role security using JSON Web Tokens (JWT) to control access to rptdesigns and output documents.
Please feel free to leave comments about the article here.
If you have comments about the birt-spring-boot-starter please feel free to raise an issue on our GitHub site for the project.
Comments