BI Publisher Bursting in PeopleSoft

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

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.

*Note: Per MOS Doc ID: Doc ID 962712.1:
PSQuery and rowset data sources may not be the most efficient way to generate the XML file that is used as input to BI Publisher, (XML Publisher). Consider using SQR or other mechanisms to generate the XML file

My Oracle Support

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;