Overview
Bursting BI Publisher reports breaks up a single report into multiple output files. Every time the value changes in a specific designated field, a new document is generated.
As delivered, PeopleTools wants bursted reports to run from the Process Scheduler delivering reports to the Report Manager. Users access the bursted reports through the report manager.
Bursting is an older technology rarely used in our current architecture. In most cases, there are better ways than bursting to accomplish the requirements.
Caveats
This discussion will cover bursting and bursting template control.
It will not cover:
• Burst Security
• Burst Search Keys
• Report Manager Configuration and usage
Getting Started
Before setting bursting options, start with a working BI Publisher Report running through the process scheduler. The process generates one report with all documents contained in the XML File.
BIP Data Source
The BIP Data Source defines the structure of an XML file.
The BI Data Source only needs a good example of the expected XML Data file.
PeopleToold version 8.59 and any other currently supported version does not require an XML Schema files.
In older BI Publisher versions, an XML Schema is required for bursting and other advanced functions
BIP Report Definition
A basic report definition working from batch
RTF Template
Your RTF Template defines how the data is presented in your report. Bursting is not defined at the template
App Engine to generate the report in batch
Bursted reports should run in batch and post to the Report Manager
The report distribution option in your App Engine PeopleCode should be publish the report (see Appendix A for entire Peoplecode Event)
&oRptDefn = create PSXP_RPTDEFNMANAGER:ReportDefn(&ReportName);
&oRptDefn.Get();
&oRptDefn.SetRuntimeDataXMLFile(&xmlFile);
&oRptDefn.ProcessReport(&TemplateId, &LanguageCd, &AsOfDate, &oRptDefn.GetOutDestFormatString(&OutDestFormat));
&oRptDefn.Publish("", "", "", &ProcessInstance);Associated PeopleTools Objects
Pages, components, records, and process definitions to control the process.
Data Source Structure
Bursting a report starts with the design of the source data set.
BI Publisher will only burst on one XML tag in the highest group node of the file. This means the burst field must be in the high-level structure if working with complex report.
When creating a detail report such as a training report or an itemized invoice, ensure the field to burst on is in the highest-level node of the XML File. If using a tool like PSQuery where the data structure is flat, make sure your burst field is in the data area that is not summarized by the tool in a table on a page
Bursting a BI Pub Report
Bursting is controlled though the BIP Report Definition, not the template.
Once you have tested your BI Pub objects and the report is running successfully from the process scheduler, open the BIP Report Definition and navigate to the “Bursting” tab
Navigation: Home > Reporting Tools > BI Publisher > Create BIP Report Definitions
The top of the page contains the “Burst by” field. Clicking on this field’s drop down, a list of all possible burst fields as per your Data Source Definition will appear. If your desired field is not in this list, the data source is not correctly structured for bursting.
In this example, we are busting by the DEPTID field in the XML File.
ReRun the report and review the Report Manager for the generated reports.
The same report run now produced a different report for each distinct DEPTID value in the file. Notice the report name.
In this example, the reports for all employees in DEPTID 22000 are in this document. Each document contains one or more reports as per the Burst Field Value.
Enforce Unique Burst Value
This option forces the report to expect unique values in the Burst By field. The report process will stop and generate an error if a duplicate value is received in the Burst By field.
For example, bursting employee checks by Emplid. With this checkbox selected, the process will error if an employee has two checks.
With this option off, all rows having the same value in the burst field will be combined into a single report.
Bursting Template Selection
We can control which template is used for a burst report through the “Template” section on the BIP Report Definition Bursting page.
Define template control by any field in the highest-level node of the XML File. These templates must already be defined under the “Template” tab of the Report Definition.
In the example above, the report is bursting by Emplid, meaning a document will generate for each EMPLID value in the XML file. The Template is controlled the DEPTID field.
• If the employee’s DEPTID = 10000, then the report will use the X_PT3_BIBRST_ACC template to generate the report
• If the employee’s DEPTID = 13110, then the report will use the X_PT3_BIBRST_HR template to generate the report
• If the employee’s DEPTID is NOT one of the listed values, the default template is used to create the report
It’s important to know that if the “Burst By” field and “Template Controlled by” field are different fields, then all data in a bursted report must have the same value in the “Template” field to use the different template. If at least one row of the Burst section does not have the same value in the Template control field, the report will use the default template.
Here you can see the output from the template control. The templates are essentially the same, just the color scheme has been changed to show us that the different template had been used.
- Employees in DEPTID 13110 received the purple report
- Employees in DEPTID 10000 received the green report
- All other employees received the default template, which has the light blue title and table.
Structural differences with BI Publisher Reports
When bursting BI Pub Reports, it’s important to remember that the BI Publisher Report Generator on the server does not just create multiple reports in one output directory on the file server. The process creates a separate sub-directory under the report’s “/RptInst/” folder for each report.
Where a non-burst BI Publisher process places the result report in the “/RptInst/” folder, the bursting process creates a new individual folder in that “/RptInst/” folder for each of the reports generated. That new sub-folder is simply named with the sequence number of that report. The actual report is in that sub-folder.
Should you run a payroll report for 5,000 employee and burst by EMPLID, the process will create 5,000 sub-directories under the main folder, one for each employee’s report. Below is an example of a report generated 15th in the sequence.
This massive number of additional directories per each run can become a performance issue on your file server if not carefully managed.
Should you use Bursting?
In most cases, no.
There are better ways to control and group BI Reports than bursting. Creating specific data sets before sending them to BI Pub allows finer control of the input and final document produced. You also don’t have to track the sequence a key value appears in the data file against the resulting folder sequence of the bursted reports.
We generally get better system performance running multiple controlled reports rather than parsing a single, huge datafile bursted into multiple reports. BI Publisher recommends we DON’T use PSQuery for larger reports due to the extra overhead of that data source.
We also get to choose where the report runs: batch, online in the user’s section, or both.
So, I would easily find other better ways to produce the results than bursting.
Appendix A
App Engine PeopleCode Event generating Bursted Report
import PSXP_RPTDEFNMANAGER:*;
Function ExecXmlpReport(&RunControlId As string, &ProcessInstance As number, &ReportName As string, &TemplateId As string, &LanguageCd As string, &AsOfDate As date, &OutDestFormat As number) Returns boolean
Local PSXP_RPTDEFNMANAGER:ReportDefn &oRptDefn;
Local number &i;
Local ApiObject &PSMessages;
Local number &MsgSetNbr, &MsgNbr;
Local boolean &bResult;
Local string &xmlFile;
Local string &sXMLString, &buffer;
Local array of string &Ar_Files;
&xmlFile = RTrim(X_PT3_BRST_AET.FILENAME);
&nOrigPSMessagesMode = %Session.PSMessagesMode;
%Session.PSMessagesMode = 1;
try
/* get the report defn object */
&oRptDefn = create PSXP_RPTDEFNMANAGER:ReportDefn(&ReportName);
&oRptDefn.Get();
&oRptDefn.SetRuntimeDataXMLFile(&xmlFile);
&oRptDefn.ProcessReport(&TemplateId, &LanguageCd, &AsOfDate, &oRptDefn.GetOutDestFormatString(&OutDestFormat));
&oRptDefn.Publish("", "", "", &ProcessInstance);
catch Exception &Err
WriteToLog(%ApplicationLogFence_Error, &Err.ToString());
Return False;
end-try;
%Session.PSMessagesMode = &nOrigPSMessagesMode;
&bResult = True;
/* check session message for errors */
If %Session.PSmessages.Count > 0 Then
&PSMessages = %Session.PSmessages;
For &i = 1 To &PSMessages.Count
If (&PSMessages.Item(&i).MessageType <= 1) Then
&MsgSetNbr = &PSMessages.Item(&i).MessageSetNumber;
&MsgNbr = &PSMessages.Item(&i).MessageNumber;
WriteToLog(%ApplicationLogFence_Error, MsgGet(&MsgSetNbr, &MsgNbr, "Message Not Found : " | &MsgSetNbr | "," | &MsgNbr));
&bResult = False;
Break;
End-If;
End-For;
End-If;
Return &bResult;
End-Function;
If ExecXmlpReport(X_PT3_BRST_AET.RUN_CNTL_ID, X_PT3_BRST_AET.PROCESS_INSTANCE, X_PT3_BRST_AET.REPORT_DEFN_ID, X_PT3_BRST_AET.TMPLDEFN_ID, "", %Date, 2) = True Then
Exit (0);
Else
Exit (1);
End-If;
