Starting with the QAD 2012 Enterprise Edition, the Reporting Framework includes an infrastructure to facilitate the mass-running and distribution of reports: report bursting. A report burst is a special way that a report can be run that involves the following aspects:

The report bursting mechanism is a general capability that can be used with any report developed using the QAD Reporting Framework, but not for any other type of report. In addition to dynamic setting of output destination, the infrastructure allows for most of the report settings to be set dynamically based on the data; this includes such settings as language for translated labels, date and number formats for internationalization, output file type (PDF, Excel, RTF, and so on) and layout type (for example, different form layouts of the same data for different countries).

Report bursts internally schedule each of the split output reports to be asynchronously (but immediately) run by a report server using the QAD Reporting Framework Service (see Service Mode). This leverages the many benefits of the report server architecture such as robustness, scalability, and failover.

Although the new bursting capability is included in the QAD Enterprise Applications 2012 – Enterprise Edition release, this release does not contain any QAD application programs that take advantage of it. You can, however, set up your own desired scenarios for bursting using the following mechanisms:

The logic that controls the dynamic routing settings is completely configurable. However, the QAD Enterprise Applications 2012 – Enterprise Edition release contains no default routing logic. If dynamic routing is desired, it is necessary to first codify the needed rules using the Progress programming language in a special dynamic-routing program that can be invoked during report bursts. (See Developing Rules for Dynamic Report Burst Settings.)

If you want help with creating report burst programs or setting up the desired routing rules, please consult QAD Services.

Prior to the introduction of QAD report bursting technology, third-party solutions were required. Those products typically process a plain text report output file, parse it, split it into multiple files, transform it to alternate output formats, and route the output files to destinations such as document storage and e-mail. They typically allow dynamic routing logic to be configured based on the data in the document.

The introduction of the QAD Reporting Framework posed new challenges as well as new possibilities for such report bursting approaches. Its ability to output rich, graphical reports in binary formats such as PDF eliminate the need for third-party post-rendering, and also create a more challenging file format to feed into those products that cannot be parsed as easily as plain text.

The QAD report bursting capability now provided with the QAD Reporting Framework solves these challenges in an out-of-the-box manner that eliminates the need for third-party technology. It uses a fundamentally different approach that does not involve post-processing of report output files. Instead, report bursting is implemented internally as the report is run. It is important to understand the basic process used in order to be able to configure and administer report bursts.

When a report is run in burst mode, it operates as a driver report, which, during its processing, spawns one or more target reports, each of which performs the rendering of the final output documents. The driver report first queries the dataset for the overall burst and splits this into a smaller dataset for each target report. The target reports are not directly run in the driver report process but instead are scheduled to be run in the QADSVC batch that is processed continuously by the QAD Reporting Framework service running on one or more report server machines. This provides benefits including robustness, scalability, and increased throughput. It also records a permanent record of the report burst results, which can be viewed using Scheduled Report History Browse.

The following diagram illustrates the driver and target reports in a report burst scenario.

The report bursting process depicted in the above diagram involves the following steps:

Running a report burst involves configuring some burst report settings for the burst driver report and then running the driver report. There are two ways this can be done:

Because report bursts can result in many report output files being created and possibly e-mailed outside the corporate firewall, be sure to carefully review all settings before running a burst. You can also stop or pause the QAD Reporting Framework service running on report servers before running a test burst and then use Scheduled Report Browse to inspect the scheduled target reports and their report parameters to make sure that they are correct. If they are correct, then the Reporting Framework service can be resumed to initiate the running of the target reports.

One benefit of using the API approach to bursting is that once the programs have been developed and tested, they can be run with a high degree of confidence. On the other hand, using the burst settings form to manually enter burst settings is potentially more error prone (due to human data entry) and should be undertaken with care. For this reason, the burst settings form is hidden by default and an administrator must configure the system to expose it. When this is done, a burst settings button appears on the report viewer for all reports but only when run by users that belong to the rptAdmin role. If you want to have non-administrative users run report bursts, applications must be written for them that call the Reporting API.

The following report settings are used to configure the parameters for a report burst. When using the API technique to initiate a burst, these settings should be configured in the API call. When using the burst settings form to manually run a burst, the settings get set based on the data entered into the form.

The burst settings form is launched from the report viewer by invoking the burst settings button at the top of the form. This button is only visible to administrators (users who belong to the rptAdmin role). Furthermore, the button is hidden by default unless an administrator enables it.

To enable the burst settings button, put the following entry into the client-session.xml file on the QAD .NET UI home server:

Before running a report burst using the burst settings form, first configure any regular report settings that are desired for the burst, such as filter conditions, data and number formats, and output file type. It is recommended to invoke the run button to do a regular (non-burst) run of this report to confirm that the settings are all proper.

Next, invoke the Burst Settings button to launch the burst settings form. This form allows you to enter various settings that correspond to the burst settings described in the previous section. Once the settings have been entered, you can take one of the following actions:

The Report Burst Settings form is shown and described below:

Specifies whether to perform report splitting.

Click Run Report Burst to run the report burst as specified.

Several tools are available for administrators to monitor the status of a report burst. The first is the output of the burst driver report itself. This consists of a list detailing information about each target report that was scheduled in the burst. This information includes the destination of each target report (printer, e-mail, InBox), the status of the scheduling (success, failure, scheduled report ID), and—if splitting was specified for the burst—the split-field’s value is also listed. In addition to the scheduled report ID, each target report is also assigned a group ID. Although the scheduled report ID is different for each target report, the group ID is the same for all target reports in the same burst run. The group ID is chosen to be the same as the scheduled report ID of the first target report in the burst.

It is important to understand that since the burst driver report only schedules the target reports (and does not actually run them), the driver report output does not give any indication of the success or failure of the actual running of the target reports. To monitor the results running the target reports, you can use Scheduled Report Browse and Scheduled Report History Browse.

Scheduled Report Browse displays one record for each report scheduled to be run. Since report bursts have their target reports scheduled to the QADSVC batch for immediate processing, you should see any un-run target reports listed for this batch ID. Once each target report has been run, its record is deleted from the batch and no longer appears in Scheduled Report Browse (unless the run failed, in which case the record remains with a status of ERROR). It is convenient to search on the group ID field to filter the browse results to show just those target reports for a specific burst run.

Scheduled Report History Browse displays the results of each scheduled report for which a run has been attempted. Once a burst is complete, this browse should show a record for each target report of the burst, including information about its success or failure. It is convenient to search on the group ID field to filter the browse results to show just those target reports for a specific burst run.

If any of the target reports encountered an error, each of the above browses indicates a status of ERROR for that report. If the error was due to a transient problem, such as a network glitch, it may complete successfully if a rerun is attempted. It is possible to rerun a single target report without rerunning the entire burst. To do this, use Scheduled Report Maintenance to change the status of the scheduled target report from ERROR to NEW, which causes the QAD Reporting Framework Service to initiate another run. It is convenient to right-click on the ID value in Scheduled Report Browse and drill directly to the corresponding record in Scheduled Report Maintenance.

The dynamic parameter-setting logic for report bursts must be specified in Progress code logic in the following file located in the .NET UI Progress application server tier:

The program is invoked during a report burst, once for each target report, and is given input data containing information about the report being run as well as some of its data, and it returns a set of report settings which are then applied to the target report run. A skeletal version of this file is shipped with the 2012 EE release. It performs no setting of parameters, but contains the framework to facilitate the custom development of dynamic parameter logic.

This file is only called if the burst is configured to use dynamic parameters, as specified by setting the sys_burst_parameter_repository parameter to a value of ProgressReportParameterRepository. Otherwise, no dynamic settings are attempted, and any target-report routing must be specified in the following settings (described in more detail above):

These settings apply to all target reports. However if dynamic parameters are being used for the burst, the above parameters are completely ignored even if they are set.

This file is called during the running of the burst driver report. If report splitting is turned off for the burst, then this procedure is called once before the single target report is scheduled. If splitting is configured (by setting a split field name in the sys_burst_split_by_field_name parameter) then the ReportParameterRepository.p is called many times, before each target report is scheduled.

The input to the ReportParameterRepository.p program contains information about the report being run, the split field name and current value (if splitting is enabled), and the current row of data being processed. Any of these input data values can be used in the programming logic to determine the dynamic settings. Because the program is executed on the QAD .NET UI Progress application server tier, it also can query data from any connected database to use for determining dynamic settings. Since the routine is called only once per group of data rows containing the same split-field value, only the first row of this group of rows is input to the program. Developers should take care not to base logic on data values that may vary over the rest of that group of records.

The output of the program is a set of report parameter settings. Most settings are single-valued (name = value), but some may allow operators other than equals and may allow specifying two values forming a range. Thus the output dataset has a temp table with a structure that allows for all of these possibilities. The include file ParameterConstants.i contains many helpful preprocessor directives to assist developers with specifying the parameter names, operators, and certain values.

When building records in the output data set (one record per parameter being set), it is important to keep in mind that these parameters override any pre-set parameters of the same name that may already be set in the report context prior to the launching of the target reports. For example, if a driver report for a burst was launched from the UI of the Burst Settings Form, any user-entered number and date format settings (for example, the number of digits after the decimal point to display, set using the sys_ci_decimal_digits parameter name) that may have been set in the Settings form prior to invoking the burst are set in each target report unless overridden by being returned by ReportParameterRepository.p.

An example of a simple set of routing rules is given below:

In the above Progress program, the input dataset is dsReposRequest, which consists of two tables:

For example, if a Sales Order report is being split by Sales Order Number (ttReposRequest.groupField) but dynamic settings need to be set based on the Sold-To customer ID, then the customer ID must be looked up from the corresponding record in the ttDataRowPair table.

The output data set is called dsReposResults and consists of a single table that must be populated with one record per report parameter that is set dynamically by your logic: ttReposResults is to be populated with one record for each parameter being set for the target report. The parameter types in this output table should be set to &PARAMETER_VALUETYPE_CONSTANT to represent that they are literal values that are being set in your program. The ParameterConstants.i include file contains many useful preprocessor directives that can be used to indicate the parameter names and operators.

The logic in the main block of the program is as follows: