Running Reports Using PeopleCode

All report runtime functionality is available using the PeopleCode BI Publisher classes. The classes and methods that you use to define custom reports respect the report category security assigned to the report definition. Users with read-only access to report definitions cannot edit them.

Runtime classes are available to call and pass in XML data and a choice of report template to the BI Publisher core engine to generate the output in a desired format. For online viewing, a function is available to pass the output back to the browser. Processing a report through the Process Scheduler posts BI Publisher output entries to the web, the Report Manager, or both according to the existing processes. When processes are categorized under the XML Publisher process type, the capability to establish output destination, format, and authorized viewer choices from the related report definition is enhanced. A search method is also available for accessing reports in the report repository.

You can call the PeopleCode from a page for online processing, or you can create an application engine program to run the report in batch.

See Creating Report Definitions.

See Creating, Opening, and Renaming Programs

See Understanding BI Publisher and the BI Publisher Classes.

The BI Publisher classes enable you to access the runtime portions of the BI publishing process programmatically, that is, after the templates and reports have been created. The BI Publisher classes are not built-in classes, like rowset, field, record, and so on. They are application classes. Before you can use these classes in your PeopleCode program, you must import them to your program.

Your import statements should look like this:

import PSXP_RPTDEFNMANAGER:*;

See ReportDefn Class Constructor.

import PSXP_RPTDEFNMANAGER:*;

/* get report definition object */
&oRptDefn = create PSXP_RPTDEFNMANAGER:ReportDefn (&sRptDefn);
&oRptDefn.Get();
/* fill query runtime prompt record */
&rcdQryPrompts = &oRptDefn.GetPSQueryPromptRecord();
If Not &rcdQryPrompts = Null Then
  &oRptDefn.SetPSQueryPromptRecord(&rcdQryPrompts);
End-If;
/*generate report*/
&oRptDefn.ProcessReport (&sTmpltID, &sLangCd, &AsOfDate, &sOutFormat);
/*publish report */
&oRptDefn.Publish(&sPrcsServerName,"",&sFolder, &prcsInstId);

import PSXP_RPTDEFNMANAGER:*;

/* get report definition object */
&oRptDefn = create PSXP_RPTDEFNMANAGER:ReportDefn (&sRptDefn);
&oRptDefn.Get();
/* pass XMLFile to the report definition */
&oRptDefn.SetRuntimeDataXMLFile(&sXMLFilePath);
/*generate report*/
&oRptDefn.ProcessReport (&sTmpltID, &sLangCd, &AsOfDate, &sOutFormat);
/*print report */
&oRptDefn.PrintOutput(&sDestinationPath);

Because report definition information is available from the PeopleCode BI Publisher classes, you can incorporate prompts on runtime pages to select reports and templates. You must pass in XML data and a choice of report template to the BI Publisher core engine to generate the output in a desired format.

You can retrieve a particular template file or expose a choice of templates at runtime. Only active reports and templates are retrieved. An as of date is also required to coordinate with the template file’s effective date. If not supplied, the as of date is assumed to be the system date. At runtime, the template as of date is used to select the appropriate active effective-dated template and sub-template that is current as of that date.

A PeopleCode class is available to retrieve a report’s template IDs based on a channel value, although it is not exposed on a PeopleSoft PeopleTools-delivered Pure Internet Architecture page. You can also incorporate template administration functionality directly into your application pages. This functionality includes creating the definitions and storing the related files, as well as querying to find the templates associated with a report definition.

The system may need to pass runtime parameters into the BI Publisher core engine. Numbers and text are sent as strings with single quotes. By default, PeopleTools ( through the ReportDefn class ProcessReport method) always passes the following parameters/tags:

<?$ReportID?>
<?$ReportTitle?>
<?$RunDate?>
<?$RunTime?>

These tags can be included in the template layout wherever they are needed, they are especially useful for report headers. Before inserting these parameters into the template (or sub-template), the following declarations must be entered under a form field at the top of the report's primary template; one for each parameter called:

<xsl:param name="ReportID" xdofo:ctx="begin"/> 
<xsl:param name="ReportTitle" xdofo:ctx="begin"/> 
<xsl:param name="RunDate" xdofo:ctx="begin"/> 
<xsl:param name="RunTime" xdofo:ctx="begin"/> 

These tags can be included in the template layout wherever they are needed. These parameters are especially useful for report headers.

The PeopleSoft-delivered BI Publisher report XRFWIN demonstrates the usage of these values in a report calling a sub-template for a header.

For the standard parameter passage of report ID and report description, the translation of report descriptions may become important for report headers. BI Publisher includes PeopleSoft-related language tables for the data source, and report and template tables that support the report’s data language values for the description fields.

The ReportDefn class ProcessReport method has code built in to process a single report request to create multiple output files per the bursting instructions defined on the report definition. Bursting always occurs at runtime if a burst value is stored in the report definition's burst field value.

See Setting Bursting Options.

The PeopleSoft application supports batch printing BI Publisher reports directly from a server using PDF output format. Printers with Postscript level 3 interpreter natively support printing PDF format. You can also print to PCL and Postscript printers by specifying the type of printer in the ReportDefn.SetPrinterType() class method. The PeopleSoft application provides PeopleCode support for sending PDF files directly to a specified printer, and it also provides customization capability for inserting conversion logic from PDF to different printer formats.

To send a BI Publisher report to a printer and to specify a printer type, use the PrintOutput and the SetPrinterType methods after the ProcessReport method as shown in this example:

&MyReportDefn.ProcessReport("myTemplate", "", %Date, "PDF");
&MyReportDefn.SetPrinterType("PCL" or "PS")
&MyReportDefn.PrintOutput(&PrinterPath);

If you want to insert conversion logic from PDF to a different printer format (other than PCL and PS) before an output file is sent to a printer, create a batch file named psxprint.bat on Microsoft Windows or psxprint.sh on Unix under the Process Scheduler server home directory %PS_HOME%\appserv\prcs\%domain_name% and write a call to an external conversion program in this batch file.

In the batch file, you can use the following variables, which the ReportDefn.PrintOutput() method replaces with actual data at report runtime:

%RPTOUTDIR%

%REPORTFILE%

%DESTPRINTER%

See Setting Output Options.

PeopleCode options are available for posting your generated report to a file server, printing it, or publishing it to the Report Manager with appropriate security.

For online viewing, a method is available for passing the output back to the browser. No report results are persisted, but the user viewing the results can use the browser's Save As feature to retain the report file locally.

When the output type is Printer, the output format is limited to PDF. A printer location must be specified, and the printer must be capable of printing PDF output. If the output file is large, adequate memory must be available on the print server.

Distribute To IDs are those defined in the Report Definition, Security page. Distribution functionality within the Process Scheduler is enhanced to assign values systematically per the BI Publisher report definition. The Report Definition, Security page provides choices for selecting a Report Manager folder as well as the ability to assign viewing rights to additional roles or user IDs at runtime if allowed by the report definition.

When the report definition has the Allow viewer ID assignment at report runtime check box selected, the report requestor can add or delete IDs. If no viewers are assigned, by default the requestor’s ID is added systematically.

A search method is available for accessing reports in the Report Manager repository. PeopleCode uses additional search keys based on the report definition’s additional metadata.

See Setting Bursting Options, Searching the BI Publisher Report Repository.