Use a Java preprocessor

This topic provides an example of using a Java preprocessor to generate Excel reports.

In this topic:

Overview of Java preprocessor

If you have advanced requirements to process data in the report template, using the scripting features in the template might be tedious. In this case, you can define a Java preprocessor class that can be run before the report and can fill data in the report.

A Java preprocessor enables you to get data by calling a web service, or use Java code to assemble complex SQL statements that cannot be done using a dashboard data source.

All the report field values available to the template are also available to the Java processor, so you can modify the existing data or add new data to the report. You can use the ppmdb or reportingdb object, and the execQuery(…) method on the data. You can also use the getPPMDBConnection() and getReportingDBConnection() methods to get a JDBC connection to PPM databases or reporting databases. When you create a JDBC connection, you don't need to close the connection; it is automatically closed when the report completes.

The following sections provide an example of using a Java preprocessor to create an Excel report. This example report takes a search text as an input field, and returns all the PPM project names containing the text as well as links from the first result page of Bing.com.

Back to top

Create a report type

Follow the steps below to create a report type:

1. Copy the report type created in Create a report type in PPM workbench.

   1. In the Workbench, select the report type and click Copy.
   2. Name it Java PreProcessor Excel Report.

2. In the Fields tab of the report type, configure the following settings for the report type fields:

   Field name	Requirement
   Filed Prompt	Type Search for:
   Token	Type SEARCH_STRING
   Attributes tab -> Required field	Select Always

3. Click the Commands of the report type, in the Command Steps area, change the Excel template path from reports/rm/ResourcesDetailsTemplate.xlsx to reports/preprocessor/SamplePreprocessorTemplate.xlsx.

4. To use a Java preprocessor, add the following line:

   DATA_PREPROCESSOR_CLASS=your.preprocessor.class.full.Name

   between the first and the last line of the command steps.

   The command steps should look like the following:

   ksc_run_excel_report reports/preprocessor/SamplePreprocessorTemplate.xlsx
   REPORT_ID=[RP.REPORT_SUBMISSION_ID]
   DATA_PREPROCESSOR_CLASS= com.hp.ppm.excelreports.SamplePreProcessorClass
   ksc_end_report_parameters

5. Save the report type.

Back to top

Create a Java preprocessor class

To create a Java preprocessor class, in the knta_classes.jar file located in the <SERVER_HOME>\deploy\itg.war\WEB-INF\lib directory, extend the com.mercury.itg.common.excel.exporter.data.ExcelReportDataPreprocessor abstract class.

All the jar files available in this folder are on the classpath when PPM is running, so you can use them as third party libraries when working on your Java preprocessor class.

You can find the source code of a sample preprocessor class in Samples\4 - Using a Java pre-processor\1 - Sample Preprocessor source code\com\hp\ppm\excelreports\SamplePreProcessorClass.java.

This code is provided for educational purposes only. It is extensively commented and demonstrates the features available from the preprocessor. You are encouraged to modify it and add your custom behavior.

Back to top

Deploy the Java preprocessor class

To deploy the Java preprocessor class, all you need to do is to put the compiled class on classpath of PPM.

Use either of the following to deploy the Java preprocessor class:

• Take the class file (you can extract it from the JAR) and put it with its package folder hierarchy in <SERVER_HOME>/deploy/itg.war/WEB-INF/classes.

  This should be used for testing purpose only. PPM cleans up the content of this folder during the upgrade, even it is only installing a new PPM patch release.

• Put the JAR file in <SERVER_HOME>/deploy/itg.war/WEB-INF/lib (recommended) or in <SERVER_HOME>/lib.

  PPM cleans up the content of this folder during the upgrade, even it is only installing a new PPM patch release.

• Put the JAR file in <JAVA_HOME>/jre/lib/ext.

  This method is not recommended because this will make the class file available to every Java application run with this Java Virtual Machine.

After the Java preprocess class is deployed, start or restart your PPM server.

Back to top

Create the Excel template

You can find an example Excel template in Samples\4 - Using a Java pre-processor\2 - Template for Java pre-processor.xlsx. Move it to the PPM server in the templates folder; make sure to put it in the reports/preprocessor subfolder and rename it SamplePreprocessorTemplate.xlsx.

This template demonstrates some of the features from the JETT third-party library:

• Script in the ${} placeholders to pluralize words when there is more than one item in a list.
• Use the <jt:if> tag to only show table header cells if there is some data to display in the table.
• Use the <jt:hyperlink> tag to create a link with dynamic text and URL.

Back to top

Run the report

Run the report from the PPM menu. You can pass any search string you want.

The result of running this report on PPM demonstration environment with the search String ‘ERP’ is provided in the Samples\4 - Using a Java pre-processor\3 - Created Report with Java pre-processor.xlsx file.

Back to top

See also:

• Use a Java report postprocessor
• Use a Java report streaming class