Data Crow allows users to add their own reports or to modify the existing reports.
The reports are created with the Jaspersoft Studio software. This software is free for download.
Prerequisites #
- For creating report the Jaspersoft studio software needs to be installed. Download the software from: https://community.jaspersoft.com/project/jaspersoft-studio. Download the latest version available.
- You need Data Crow version 4.0.7 or higher.
- You need to have the Java installed (version 17 or higher). This can be downloaded from the Oracle site: https://www.oracle.com/java/. This is also a requirement for running Data Crow.
The Report Process
#
Report Templates
Data Crow uses compiled reports from Jaspersoft (.jasper file). These are placed in the reports folder of the Data Crow installation folder.
When the software is upgraded the user will be asked whether he/she wants copy the reports over to the reports folder of the installation to the user folder. When you want to test your created or modified reports, copy them to the reports folder of the user folder.
Each time the report dialog is opened, Data Crow scans the reports folder of the user folder for existing .jasper reports files. As Data Crow consists of multiple modules, the reports need to be placed in the reports folder of the module. The folder structure for reports for a particular module is as
follows: <user folder>/Reports/<module name
Example for Microsoft Windows:
D:\Data Crow\Data\Reports\Software
D:\Data Crow\Data\Reports\Movie
Example for Linux:
/Home/Data Crow Data/Reports/Software
Note: it might be the case that your user folder also holds sub directories called PDF and HTML. These are leftovers from older Data Crow versions. These are no longer in use and can be safely removed. The same goes for the files contained within.
Report Creation
When you run a report from Data Crow (Tools > Create Report) Data Crow does three things:
- Data Crow creates an XML export of the selected items.
- Data Crow fills the .jasper report file with the XML data.
- And as a last step the filled report is saved in the selected target format (RTF, PDF or HTML).
The most important thing to note is that Data Crow uses XML extracts for creating the reports rather than accessing the database directly. We will use the XML in the next chapter to design a new (or modify an existing) report.
Secondly, it is no longer required for the reporting process to export the images. Jaspersoft does this automatically in case needed, such as is the case for the HTML reports.
Creating a New Report #
Let’s design a new report! We’ll need a XML file holding Data Crow items (as a source) to create and design a report in Jaspersoft.
Create an XML export
First, we need to have an example XML file so we can use this to design our report.
- Start Data Crow
- Select the module for which you want to create a report
- Select one or more items in the overview, right-click and select Item Export Wizard:
- Select XML export and press Next
- Select the target file and press Next
Leave the images option at the default - Leave all fields selected and press Next
- The XML will now be created and stored to disk.
Note that we will only use this XML as an example for creating our new report. Data Crow will create the XML extract automatically when you run the report from within Data Crow (Tools > Create Report). It’s important that you selected items which hold the most information as well as a couple of items with very limited information. This is always good for testing the report.
JasperSoft Studio #
Next, start Jaspersoft Studio. On a first start you will be asked to select a workspace location. Pick any location that you want. Once started close out of any of the welcome screens until you are in the actual work area.
First thing we need to do is to set up the XML file we exported as a Data Adapter. Data adapters are used to fill reports with data. Select the Repository Explorer tab and right-click on the Data Adapters. From the right-click menu, select Create Data Adapter.
Select XML Document;
Press Next to further configure the XML data adapter
Fill at least the following fields (other fields are optional and explained in the documentation of Jaspersoft Studio):
- Name: enter any name you want, recognizable to yourself.
- File: select the XML export as created by Data Crow. In my case this was text.xml. Note that for running the report by Data Crow this file will not be used, this is only for designing the report.
- Tick the “Use the report Xpath expression when filling the report”. This is very important as you otherwise will end up with an empty report for your test runs.
Press Test to test your set up.
Press Finish to end the data adapter creation.
Create a Blank report
So we now have an XML file which is set up as a data adapter in your Jaspersoft environment. Next logical step is to create a new report, using the data adapter as input.
Navigate to the Project Explorer. By default this will hold a project named MyReports. You are free to use any other project name you want to, it’s not important for the Data Crow reports.
Right-click on the project and select New, Jasper Report.
Now you can select a Report Template. For Data Crow reports you can choose any report template you want. For more details on these templates I refer you to the Jaspersoft Studio documentation. For now, I’ll choose the Blank A4 template. Press Next.
Next Jaspersoft Studio will ask you to name the report so that it can be saved into your project.
Give it a name that will make sense; the name of the report file is shown in the Data Crow report selection. For this example I’ll call this report Test. Press Next to continue to the next step.
Now, we are in step where we will link the data adapter to the report. This will allow the report to find the fields available and fill them with information when running the report.
- Select the Data Adapter from the dropdown. In my case it is called Test XML.
- In the field below the structure of the XML file is shown. Now we need to define how Jaspersoft Studio has to use the XML information. For
the example you can see I have exported software items. A total number 4 items are present, each item is represented as software-item. Looking at a single item, we can see all the fields:
- Double click on the node that holds all the fields. This makes all items available in the report.
Note that for XML exports from other modules you will see for example Movie, Book, Music Album, etcetera instead of software-item. The steps to follow are exactly the same. Press Next. - In the next step you’ll have to choose which fields to include in the report. If no fields are listed or this step is skipped it means you have made a mistake in the previous step. I have selected all fields by pressing on the >> button. I recommend adding all fields as this gives the most flexibility.
- At this point you can choose to Finish the wizard. Alternatively you can continue by pressing Next which brings you to the option to set up grouping. Grouping however is not covered in this guide; I’ll have to refer you to the Jaspersoft Studio documentation. It is supported by Data Crow, so no worries there.
Now we have a blank report with a configured data adapter.
Design tips & Tricks #
For full documentation on how to design you report in the Jaspersoft Studio software you are referred to the documentation available from the Jaspersoft site:
https://community.jaspersoft.com/project/jaspersoft-studio
There are manuals as well as Wikis available.
To help you get started, I’ll explain some of the basics.
Report Layout
In the centre of the screen you’ll find the report itself. You can see the various sections, such as Title, Page Header and so on. You can resize the sections with the mouse.
These sections can be removed (or added) from within the Outline section:
Adding Fields
All the fields as part of the XML data adapter can be found in the outline section of the workspace. From here you can drag and drop fields onto the report:
Multi-reference fields
Note that for each multi-reference field I have added a fieldname-list field (see above for examples, such as categories-list). This contains the comma separated values. If you want to iterate over the individual items instead you’ll have to add a List element.
Image fields (pictures)
Optionally you can also choose to first add a specific element onto the report and then specify which value to use. Let’s add an image for example. On the right hand side of the screen you’ll find a section called palette. Here you find all field types available. Select Image and drag and drop this onto the report.
In the dialog that appears, select Custom expression. This enables the Options field.
Press the 
button.
By
default the Fields are all shown. Select the picture field you want to add and double-click it. I have select the picture-front field.
Empty field content
Jaspersoft will print NULL in case the field is empty. I prefer to have the field show nothing in case a field is empty. This can be done though the properties of the field. Select the field by clicking on it in the Main Report view. In the example below I have selected the Title field.
Let’s change the properties of this field. Click on the field (as done in the above example). Now navigate to the Properties section.
Select Text Field.
Check the box Stretch With Overflow. It does just that; whenever the content is too large, the field will be stretched, making all of its content visible.
Field Positioning
Any field added to the report is automatically aligned, related to the top. This can be quite useful if you want your field to remain at the same place at all times; when the report is stretched the position of the field remain at the same relative distance of the top of the report section.
This problematic when you have placed the field below a text field (see above) which Stretches With Overflow.
The field will be placed on top of the stretched field as it positions itself relative to the top of the report section, not relative to the field above.
To accommodate for this set this field to Position Type Float instead:
Other Fields
There are many field types available to display the source content (the XML information). There are also fields available such as the page number. These fields can be found in the Palette section:
Report Preview #
At any time during the design process you can do a preview of the report. Click on the preview button, as shown below:
By doing a preview you get to see what the report looks like to the end user. Also, the report is checked for errors.
Compiling and Deploying the Report #
When you are ready with the report you can build it and make it available to Data Crow. First, make sure to save the report file. It’s best to always save the changes prior to building as otherwise changes you made might be missing from the final result.
Navigate to Project > Clean. This creates a .jasper file.
All you need to do now is to copy the .jasper file to the Data Crow reports folder of the user folder. The report folder structure is explained in the Report Process chapter;
<user folder>/Reports/<module name>
You do no need to restart Data Crow to run the report. Simply re-open the Report Dialog. For this example I have copied the Test.jasper file to the reports folder of my user folder:
- C:\Users\RJ\Data\Development\dc data\reports\software
Start the Create Report tool:
Celect the Test report you have just created:
And select the Report Type:
And of course the target file – the file which will contain your report.
Select run to create the report;
That’s it – you should now have a report file containing information on your items!
