Wikiadmin: /* Parameter Definition */

2018-10-15T13:46:05Z

‎Parameter Definition

Wikiadmin: Created page with "== Introduction == This how to will add a new Report using a Process Definition and create a menu entry to invoke it. The implementation requires development experience with..."

2018-10-14T13:57:02Z

Created page with "== Introduction == This how to will add a new Report using a Process Definition and create a menu entry to invoke it. The implementation requires development experience with..."

New page

== Introduction ==

This how to will add a new Report using a Process Definition and create a menu entry to invoke it.

The implementation requires development experience with Process Definitions. See the following concept pages for background information:
* [[How_to_create_a_Standard_Process_Definition|How to create a Standard Process Definition]]
* [[How_to_create_a_Report]] to build the Jasper Report templates.

{{(!)| This feature is available from '''3.0PR15Q2'''}}

== Example Module ==
This howto is supported by an example module which includes the simple report described in the examples of this document. The report is named ''Product Simple Report'' and prints in PDF a list of Products that can be filtered by Product Category.

The code of the example module can be downloaded from this mercurial repository: https://code.openbravo.com/erp/mods/org.openbravo.platform.features

== Report Definition in Application Dictionary ==

=== Process Definition ===

Create a new record in ''Process Definition'' window. Fields to consider:

;'''UI Pattern''': Set ''Report (Using JR Templates)''. This value will display the Report Definition tab.
;'''Action Handler''':If none is set when the UI Pattern is selected the ''org.openbravo.client.application.report.BaseReportActionHandler'' is set.

[[Image:howto-report-pd-processdefinition.png|600px|thumb|center]]

The ''BaseReportActionHandler'' is the default action handler to use in reports. In case you desire to make some Java validations or include some extra parameters that are not defined in the Process Definition parameters tab it is possible to use a custom Action Handler that extends the ''BaseReportActionHandler''.

=== Parameter Definition ===

In the ''Parameter'' tab are added all the parameters that are needed to filter the results of the report. Their values are handled by the ''BaseReportActionHandler'' and sent to Jasper Reports as parameters. This parameters need to be defined in the JR template with the same name as the column name.

[[Image:howto-report-pd-parameterad.png|600px|thumb|center]]
[[Image:Howto-report-pd-parameterjr2_.png|200px|thumb|center]]

When the filter parameter is a Selector reference the value is sent as a ''JSONOBject'' that includes 2 keys:
* ''value'' with the id of the selected BaseOBObject to be used in the SQL query
* ''identifier'' with the readable identifier that can be used to print in the report the filter values.

In case of Multiple Selectors the ''JSONObject'' includes 4 keys:
* ''values'' with a JSONArray including all the selected ids.
* ''identifiers'' with a JSONArray including all the identifiers.
* ''strValues'' with a comma separated String with all the selected ids that can be used in a SQL ''IN'' clause.
* ''strIdentifiers'' with a comma separated String with all the selected identifiers.

In the Jasper Template the parameter has to be defined using the class ''org.codehaus.jettison.json.JSONObject''.
In the example it is set a ''Product Category'' multiple selector. As this parameter is optional, the filter is included in the query using an auxiliary parameter (''AUX_Product_category''). The auxiliary parameter has a default expression that returns ''" 1 = 1 "'' when there is no category selected and the corresponding where clause when some categories are selected:

("".equals($P{M_Product_Category_ID}.getString("strValues"))) ? " 1 = 1 " : " pc.m_product_category_id IN ("+$P{M_Product_Category_ID}.getString("strValues")+")"

This parameter is then included in the query using the "$P!{}" notation to replace it with the parameter value instead of using SQL Parameters.

FROM m_product p
JOIN m_product_category pc ON p.m_product_category_id = pc.m_product_category_id
WHERE $P!{AUX_Product_category}
AND p.ad_client_id = $P{Current_Client_ID}

The identifiers can be shown in a Text field with the following Expression:
$P{M_Product_Category_ID}.getString("strIdentifiers")

[[Image:howto-report-pd-prodcat2.png|350px|thumb|center]]
[[Image:howto-report-pd-auxprodcat2.png|350px|thumb|center]]

The ''BaseReportActionHandler'' and the ''ReportingUtils'' class used to generate the report includes some additional parameters that can be used in the template:

;'''SUBREPORT_DIR''': The path where the main template is located. Useful to set the paths of the subreports.
;'''jasper_process''': A ''org.openbravo.client.application.Process'' object with the Process Definition of the report.
;'''jasper_hbSession''': A ''org.hibernate.Session'' object with the current hibernate session.
;'''jasper_obContext''': A ''org.openbravo.dal.core.OBContext'' with the OBContext that has launched the report.
;'''AMOUNTFORMAT''': A ''java.text.DecimalFormat'' object with the format to be used on Amounts.
;'''QUANTITYFORMAT''': A ''java.text.DecimalFormat'' object with the format to be used on Quantities.
;'''REPORT_FORMAT_FACTORY''': JR Base parameter with the date format.
;'''Current_Client_ID''': String with the current ''AD_Client_ID''. Useful to filter the SQL of the report.
;'''Readable_Organizations''': Comma separated String with the readable organizations of the User/Role executing the report. Useful to filter the SQL of the report.

Depending on the report output some additional parameters are set:

'''PDF''' output:
;'''IS_IGNORE_PAGINATION''': with '''false''' value to ensure that there report is break in different pages.
'''XLS''' output:
;'''IS_IGNORE_PAGINATION''': with '''true''' value to ensure that there report is not break in different pages and all the results are shown in the same sheet.

In case it is desired to add more parameters that cannot be defined as ''Parameters'' of the ''Process Definition'' it is possible to use a custom ''Handler'' that extends the ''BaseReportActionHandler'' and overwrites the ''addAdditionalParameters'' method.

It is possible to check all the parameters and values sent to the Jasper Report engine by enabling the ''DEBUG log level'' on the ''org.openbravo.client.application.report.ReportingUtils'' class by modifying the log4j.lcf file:

DEBUG org.openbravo.client.application.report.ReportingUtils - list of parameters available in the jasper report
DEBUG org.openbravo.client.application.report.ReportingUtils - parameter name: SUBREPORT_DIR value: /home/gorkaion/src/openbravo/pi-reporting-merge/WebContent/web/org.openbravo.platform.features/jasper/
DEBUG org.openbravo.client.application.report.ReportingUtils - parameter name: Current_Client_ID value: 23C59575B9CF467C9620760EB255B389
DEBUG org.openbravo.client.application.report.ReportingUtils - parameter name: REPORT_FORMAT_FACTORY value: org.openbravo.erpCommon.utility.JRFormatFactory@14ffa3fc
DEBUG org.openbravo.client.application.report.ReportingUtils - parameter name: REPORT_VIRTUALIZER value: net.sf.jasperreports.engine.fill.JRSwapFileVirtualizer@1b670029
DEBUG org.openbravo.client.application.report.ReportingUtils - parameter name: jasper_process value: OBUIAPP_Process(70889433974B409BAC4F9D7BFB211248) (name: Product Simple Report)
DEBUG org.openbravo.client.application.report.ReportingUtils - parameter name: M_Product_Category_ID value: {"values":["291B401A38354A2C8247DFF0DFBDF4AE","5525FCABFE9545018EE221E8802AA283"],"identifiers":["Bio","Fruit juice"],"strValues":"'291B401A38354A2C8247DFF0DFBDF4AE', '5525FCABFE9545018EE221E8802AA283'","strIdentifiers":"Bio, Fruit juice"}
DEBUG org.openbravo.client.application.report.ReportingUtils - parameter name: AMOUNTFORMAT value: java.text.DecimalFormat@674dc
DEBUG org.openbravo.client.application.report.ReportingUtils - parameter name: QUANTITYFORMAT value: java.text.DecimalFormat@674dc
DEBUG org.openbravo.client.application.report.ReportingUtils - parameter name: Readable_Organizations value: 'E443A31992CB4635AFCAEABE7183CE85','0','DC206C91AA6A4897B44DA897936E0EC3','7BABA5FF80494CAFA54DEBD22EC46F01','BAE22373FEBE4CCCA24517E23F0C8A48','19404EAD144C49A0AF37D54377CF452D','B843C30461EA4501935CB1D125C9C25A','2E60544D37534C0B89E765FE29BC0B43'
DEBUG org.openbravo.client.application.report.ReportingUtils - parameter name: jasper_obContext value: org.openbravo.dal.core.OBContext@73b91cd
DEBUG org.openbravo.client.application.report.ReportingUtils - parameter name: jasper_hbSession value: SessionImpl(PersistenceContext[entityKeys=...
DEBUG org.openbravo.client.application.report.ReportingUtils - parameter name: IS_IGNORE_PAGINATION value: false

=== Report Datasource Definition ===

{{AvailableFrom|3.0PR17Q1}}

There exists two ways of defining the data to be displayed by the report:

# Defining a '''query''' in the jrxml template
# Providing a '''datasource''' to the jrxml template

In case of the second approach, we need to use a custom ''Handler'' that extends the ''BaseReportActionHandler'' and overwrites the ''getReportData'' method. This method receives a parameter map as an argument that contains:

* The parameters of the HTTP request
* The parameters available inside the Jasper Report. They are available through another map that can be accessed by using the ''JASPER_REPORT_PARAMETERS'' key.

<source lang="java">
protected JRDataSource getReportData(Map<String, Object> parameters) {
// Retrieve the report id (HTTP request parameter)
String reportId = (String) parameters.get("reportId");
// retrieve the map of JR Parameters
Map<String, Object> jrParameters = (Map<String, Object>) parameters
.get(JASPER_REPORT_PARAMETERS);
// Here goes the logic to generate the JRDataSource
...
}
</source>

This allows to generate the report data dynamically, i.e, based on some kind of logic built with the value of any of these parameters.

=== Sub-Report Runtime Compilation ===

{{AvailableFrom|3.0PR17Q1}}

In case our process definition report contains sub-reports, the infrastructure allows to compile the sub-reports at runtime. In that case we will need to:

# Use a custom ''Handler'' that extends the ''BaseReportActionHandler'' and overwrites the ''isCompilingSubreports'' method. This method will return <code>true</code>.
# The parameter name for the sub-report in the main report will follow this pattern: <code>SUBREP_name_of_the_sub_report_file</code>.
# The sub-reports (jrxml files) must be placed in the same folder as the main report.

=== Report Definition ===

In the ''Report Definition'' tab are defined the JR Templates of the report. Each Process Definition can only have a Report definition. It is also needed to define at least one template: HTML, PDF or Excel.

{{(!)| The '''HTML''' output is available since version '''[http://wiki.openbravo.com/wiki/Release_Notes/3.0PR17Q1 3.0PR17Q1.]'''}}

* If PDF and Excel outputs share the same template, it is possible to set the PDF template and check the ''Use PDF as Excel Template'' flag.
* If PDF and HTML outputs share the same template, it is possible to set the PDF template and check the ''Use PDF as HTML Template'' flag.
* If HTML, PDF and Excel outputs share the same template, then the PDF template must be set and both flags must be checked.

The templates need to be stored in the ''web'' folder.

[[Image:Report_process_definition.png|600px|thumb|center]]

== Result ==

The result is shown in a new form with all the parameters and the corresponding Export button(s).

[[Image:PD - Form buttons enabled.png|600px|thumb|center]]

Once the report is generated a file download is requested in the browser. The form is kept enabled so it is possible to rerun the report with different parameters.

== Additional Information ==
An example of XLS Report defined with a Process Definition can be found [http://wiki.openbravo.com/wiki/How_to_create_an_XLS_Report_with_Formulas here].
[[Category:HowTo]]

An example of a Process Definition Report using the HTML output (displayed in a tab) can be downloaded from this [https://code.openbravo.com/erp/mods/org.openbravo.platform.features/ repository].

@@ Line 99: / Line 99: @@
   DEBUG org.openbravo.client.application.report.ReportingUtils - parameter name: jasper_hbSession value: SessionImpl(PersistenceContext[entityKeys=...
   DEBUG org.openbravo.client.application.report.ReportingUtils - parameter name: IS_IGNORE_PAGINATION value: false
 === Report Datasource Definition ===

How to create a Report using Process Definition - Revision history

Wikiadmin: /* Parameter Definition */

Wikiadmin: Created page with "== Introduction == This how to will add a new Report using a Process Definition and create a menu entry to invoke it. The implementation requires development experience with..."