Custom PDF Reports for a Data Insight

This page includes the following:

Each data insight type comes with a default report layout for the PDFs you can print from it. If you want to create PDF reports based on the same data that the data insight provides but presented in a different format, you can create a custom report definition that you upload to the data insight definition.

For Users—Differences When Printing a Custom PDF

When printing a PDF from a data insight based on a custom template, that is on the Report Settings the Template option Custom is selected, the following is true:

• Same for custom and default PDF reports:

  • Filters:

    Like PDF reports that use the default template, any filters that are applied to the data insight at the time that the PDF is triggered are used to select the data for the report. For PDF reports that are triggered with the Print PDF action, the filters that are applied on the view when you trigger the PDF are used. For scheduled PDF reports, the filters in the data insight definition are used. For information, see Printing a Data Insight. and Scheduling Data Insights, respectively.

  • Data sort:

    Rows are sorted by the sort order defined for the columns at the time that the PDF is printed.

• Different for custom PDF reports:

  To change any of these configurations, someone has to change the default template file. For information, see Changing a Custom Template for a Data Insight.

  • Layout:

    The layout in the custom template is applied to the report.

  • Show/hide columns:

    The columns that appear are defined in the custom report template and cannot be overridden on the data insight view or on the Columns tab of the data insight definition.

  • Column arrangement:

    The column arrangement from left to right is defined in the custom report template and cannot be overridden on the data insight view or on the Columns tab of the data insight definition.

  Note:

  The adherence to the column show/hide or arrangement configurations in the template are necessary to prevent unexpected and corrupted results.

An Overview of Creating a Custom PDF Template

The overall procedure involves the following steps:

1. Download the default PDF report definition from the Report Settings tab of a data insight of the type that provides the data that you want to include in your report.

   The file format for the template is a Jasper-formed XML file format, called JRXML.

2. Customize the JRXML in Jaspersoft® Studio, a report designing tool for Jasper files.

3. Upload your customized JRXML file to the Report Settings tab to the data insight that you want to use. You can do this in one of two ways:

   • Edit the data insight that you downloaded the default report from and upload your customized JRXML file.

   • Add a new data insight of the same type and upload your customized JRXML file.

   For information about what can or cannot be edited when printing a PDF for a data insight with a custom template, see For Users—Differences When Printing a Custom PDF.

Required Skills and Tools for Customizing a PDF Report

To be able to customize the JRXML file from the default template, you must have good mastery of Jaspersoft® Studio, a report designing tool for Jasper files. If you do not have that skill among your staff, you can contact Broadcom Support or its Client Services team for help. For complex reports that go beyond formatting, consider using a service partner with advanced report designing skills.

What You Can Customize in a PDF Report

In principle, you are free to design a PDF report for a data insight any way you want, as long as you stay within the limits listed in Restrictions and Requirements When Creating a Custom PDF Report.

This means that you can do any of the following: 

• Modify the standard report sections that you find in the default template

• Use full rich text formatting (bold, italics, various fonts and sizes, colors, lists, headings)

• Include or exclude one or more graphics of any kind

  The three standard graphics that are used in the default PDF reports for data insights are pie, line, and stacked bar charts. You can define these for your template or any of the other chart types that Jaspersoft® Studio offers.

• Include or exclude a data table

• Add hard-coded text

  You could even create a report with only hard-coded text and no data extracted from the data insight, if that serves your purposes.

• Group rows by a common value, such as business area, assuming that business area is among the data available to the data insight type

• Add report and section headers

• Add Java code for any data manipulations or to create complex filters—keeping in mind that filters can be based only on the data available to the data insight type

• You can use any of the widgets and macros in Jaspersoft® Studio.

Restrictions and Requirements When Creating a Custom PDF Report

Although you have a lot of design freedom when customizing a PDF report for a data insight, you must adhere to the following limits, otherwise the PDF and its data will not render as you intend. These apply to whether you are customizing the JRXML template file in Jaspersoft® Studio or manually.:

• Use the correct template file type:

  The template that you upload must be a valid JRXML file, the Jasper Report format.

• Include only data that is valid for the data insight type:

  You can include only data that is available to the data insight type that you will use the template for.

  To include AAI data in the report, refer to its field name, such as jobStreamName, businessArea, and so on. You find the available data fields in the default JRXML template file for the data insight type.

Considerations for Manually Customizing a PDF Report Template

If you want to manually update the code in the default JRXML file, in addition to the standard requirements listed under Considerations for Manually Customizing a PDF Report Template, you need to keep the following considerations in mind, otherwise the PDF and its data will not render as you intend:

• Ensure you have the necessary coding skills:

  It is possible to manually edit the JRXML file, which is an XML file. However, this is not recommended unless you have expert XML coding and report designing skills.

• For a table, use the correct element and attribute:

  The data to populate the report table must be defined in the subDataset element with the attribute called "Insights", which you find in the JRXML template file. (Search for <subDataset name="Insights".)

• For a chart, use a correct data source parameters:

  For the data source, you must use one of the available data source parameters: CHART_DATASET or DATA_SOURCE.
  

  There are three standard graphics that are used in the default PDF reports for data insights: pie, line, and stacked bar charts. You can define these for your template or any of the other chart types that Jaspersoft® Studio offers as long as you adhere to the same element structure and data source requirement.

Preparing a Custom Template for PDF Reports

To facilitate creating a custom PDF report template, every data insight has the default template that you can download and use that as a starting point for customization.

Prerequisites: Before you begin, make sure to review what you can customize as well as the restrictions and requirements for a custom template in the related subsections under Understanding Creating Custom PDFs for Data Insights.

To download a default PDF template

To download the default template for a specific data insight and then customize it, use the following steps:

1. Open the Report Settings tab.

2. In the Template section, in the far right of the Default option, click the Download [XML] button.

3. Click Cancel to leave the data insight definition.

4. Edit the downloaded template file to define the report format you want.

   • Find the JRXML template file in the Download folder on your device. The file name is the name of the data insight followed by the date of the download.

   • Open the file in the Jaspersoft® Studio report designing tool and customize it as required.

     Note:

     Using Jaspersoft® Studio is the recommended way to edit a report template file.

     It is possible to manually edit the JRXML file, which is an XML file. However, this is not recommended unless you have expert XML coding and report designing skills. See also Considerations for Manually Customizing a PDF Report Template.

Uploading a Custom Template to a Data Insight

Prerequisite: You have created a custom JRXML report template file for the same data insight type. For information, see Preparing a Custom Template for PDF Reports.

To upload a custom PDF report template

To upload an JRXML file with the PDF report template that you prepared for a data insight, use the following steps:

1. Open the Report Settings tab.

2. In the Template section, select Custom.

3. Click Choose File and locate and select your prepared template JRXML file.

4. Optionally, change the PDF Format print settings:

   • Page Orientation: Select either Landscape, Portrait, or Automatic (default). Automatic bases the orientation on the width of the table data.

   • Page Size: Select from a list of standard paper sizes.

   • Maximum Pages: You can limit the number of pages that are included in the PDF or have all the data print regardless of how many pages it ends up being.

     This can be helpful to limit the size of the attachment that goes out with emails. However, the PDF might not have all data rows. It contains the header information, the graphic, and as many data rows in the table that can fit within the page limit.

   • Color: Select either Color, Outline (lower quality and smaller sized files), or Black and White.

5. Save the data insight by clicking one of the following:

   • Save: This saves all settings, closes the definition, and returns to the Data Insights list.

   • Save & Run: This saves all the settings and then produces and downloads an output file as defined on this tab.

6. To test the results, select Print (PDF) from the Action menu either on the open data insight or from the Data Insights list.

Changing a Custom Template for a Data Insight

You can attach a different custom template to a data insight definition, or you can edit the current template and upload the revised version. In either case, you must edit your custom templates outside of AAI, and then upload the new version.

Prerequisite: You have prepared a new custom JRXML file or edited the custom JRXML file that is currently attached to a data insight, and it is ready for upload. Before preparing the new or edited JRXML file, make sure to review what you can customize as well as the restrictions and requirements for a custom template in the related subsections under Understanding Creating Custom PDFs for Data Insights.

The change the custom PDF report template

When you have the edited version of your template ready, continue with the following steps to add it to your data insight:

1. Open the Report Settings tab.

2. In the Custom option of the Template section, click Choose File and then find and select the new template XML.

3. Optionally, change the PDF Format print settings.

4. Save the data insight by clicking one of the following:

   • Save: This saves all settings, closes the definition, and returns to the Data Insights list.

   • Save & Run: This saves all the settings and then produces and downloads an output file as defined on this tab.

5. To test the results, select Print (PDF) from the Action menu either on the open data insight or from the Data Insights list.

Removing a Custom Template from a Data Insight

You can remove a custom report template from a data insight definition that you no longer want to use. In this case, the default template for the data insight will be used when someone selects Print PDF action or a scheduled PDF is generated.

To remove a custom PDF report template

To remove a custom template from a data insight definition, use the following steps:

1. Open the Report Settings tab.

2. In the Custom option of the Template section, click Delete. Then confirm the deletion.

3. To remove the warning icon and activate the save buttons, click the Default option.

4. Optionally, change the PDF Format settings.

5. Save the data insight by clicking one of the following:

   • Save: This saves all settings, closes the definition, and returns to the Data Insights list.

   • Save & Run: This saves all the settings and then produces and downloads an output file as defined on this tab.