Jasper Report Downloads

Overview

Helium Rapid version 1.57 introduces functionality to download existing jasper reports directly to a user's machine using normal actions that are triggered by buttons, view actions, widget actions etc.

This is only available for reports that are available in the jasper-reports folder of the app source code.

To trigger a report download from an action, the following is required:

• A call to the Mez:downloadReport built-in function
• A submission of the view to Helium's backed. This is done automatically when a DSL_VIEW value or null is returned from the actions function.
• Upon the next view response, as a result from the above, the download will trigger.

Note that multiple downloads cannot currently be queued. So even if Mez:downloadReport is called multiple times before returning from the action function, only the last download request will be triggered on the user's browser.

Mez:downloadReport

The Mez:downloadReport built-in function can be called as follows:

Mez:downloadReport(DSL_REPORTS.My_Report_Reference, reportArguments, DSL_REPORT_FORMAT.Pdf, optionalFilename)

The arguments as used above is described in the following sections.

{
	"name":"All Farmer Purchases",
	"referenceName":"All the Farmer Purchases",
	"actionsDisplay":"close",
	"actionsLabel":"Menu",
	"description":"All farmer purchases system wide",
	"rolesAllowed":["System Admin"]
}

DSL_REPORTS.All_the_Farmer_Purchases

{
	"name":"Your Purchases",
	"referenceName":"Your Purchases",
	"description":"Your purchases",
	"rolesAllowed":["Farmer"],
	"parameters":[
		{
			"parameterName":"startDate",
			"displayName":"Start date",
			"type":"date",
			"searchDestination":"ReportParameterFilters:setStartDate"
		},
		{
			"parameterName":"endDate",
			"displayName":"End date",
			"type":"date",
			"searchDestination":"ReportParameterFilters:setEndDate"
		},
		{
			"parameterName":"shopId",
			"displayName":"Shop",
			"type":"uuid",
			"searchType":"Shop.name",
			"searchSource":"ReportParameterFilters:shopFilter"
		},
		{
			"parameterName":"minCost",
			"displayName":"Minimum purchase cost",
			"type":"string"
		}
	]
}

string downloadPurchases() {
    date startDate = Date:addDays(Mez:now(), -7);
    date endDate = Date:addDays(Mez:now(), 1);
    int minPurchaseAmout = 0;
    uuid shopId = shop._id;

    json args = "{}";
    args.jsonPut("startDate", startDate);
    args.jsonPut("endDate", endDate);
    args.jsonPut("shopId", shopId);
    args.jsonPut("minCost", minPurchaseAmout);

    Mez:downloadReport(DSL_REPORTS.Your_Purchases_1, args, DSL_REPORT_FORMAT.Pdf);

    return null;
}

Report Reference

The DSL_REPORTS enum is a new built-in enum provided with Helium Rapid. The values for this enum represents the report within the jasper-reports folder of the app source code.

The values for the enum is derived from the value for the "referenceName" field specified for the reports in its report.json file.

The values are derived by replacing all spaces with underscores. No underscores are allowed in the value for the "referenceName" field in report.json.

In addition the converted values need to be unique and should conform to the normal syntax rules for enums in the DSL.

Consider the following example:

{
	"name":"All Farmer Purchases",
	"referenceName":"All the Farmer Purchases",
	"actionsDisplay":"close",
	"actionsLabel":"Menu",
	"description":"All farmer purchases system wide",
	"rolesAllowed":["System Admin"]
}

Based on the above report.json the following value will be available in the app:

DSL_REPORTS.All_the_Farmer_Purchases

Report Arguments

The report arguments represent values for the parameters specified in the report.json file for the report.

The key for the argument needs to match the parameter name specified in the report.json file.

In addition the type of the specified argument value should match the type specified in the report.json file. If not a ProgramException will be thrown by Helium. These exceptions can be handled using the standard try catch functionality available in the DSL.

Consider the following example:

{
	"name":"Your Purchases",
	"referenceName":"Your Purchases",
	"description":"Your purchases",
	"rolesAllowed":["Farmer"],
	"parameters":[
		{
			"parameterName":"startDate",
			"displayName":"Start date",
			"type":"date",
			"searchDestination":"ReportParameterFilters:setStartDate"
		},
		{
			"parameterName":"endDate",
			"displayName":"End date",
			"type":"date",
			"searchDestination":"ReportParameterFilters:setEndDate"
		},
		{
			"parameterName":"shopId",
			"displayName":"Shop",
			"type":"uuid",
			"searchType":"Shop.name",
			"searchSource":"ReportParameterFilters:shopFilter"
		},
		{
			"parameterName":"minCost",
			"displayName":"Minimum purchase cost",
			"type":"string"
		}
	]
}

string downloadPurchases() {
    date startDate = Date:addDays(Mez:now(), -7);
    date endDate = Date:addDays(Mez:now(), 1);
    int minPurchaseAmout = 0;
    uuid shopId = shop._id;

    json args = "{}";
    args.jsonPut("startDate", startDate);
    args.jsonPut("endDate", endDate);
    args.jsonPut("shopId", shopId);
    args.jsonPut("minCost", minPurchaseAmout);

    Mez:downloadReport(DSL_REPORTS.Your_Purchases_1, args, DSL_REPORT_FORMAT.Pdf);

    return null;
}

Report Format

The file format for the report download. DSL_REPORTS_FORMAT is a new built-in enum that is available to all apps. The available value are as follows:

• DSL_REPORTS_FORMAT.Pdf
• DSL_REPORTS_FORMAT.Xls

Optional File Name

Report Privileges

The same access restriction for report display / rendering applies report downloads from DSL code. 

If "rolesAllowed" is specified in the report's report.json file, those access restrictions will also apply to the Mez:downloadReport built-in function.

If Mez:downloadReport is called from the context of a user who does not have access to the report ProgramException will be thrown. These exceptions can be handled using the standard try catch functionality available in the DSL.

Exception Handling

In general, the built-in exception handling provided by the DSL's try catch mechanism can be used to handle exceptions with report generation.

At present, though, SQL exceptions that result from the report's queries cannot be handled in the same way.

Additional Mentions and References