Running, Locating, and Viewing XML Publisher Reports

You can view and schedule query-based reports with XML Publisher. You can run custom reports as well as query-based reports batch through the Process Scheduler or online using PeopleCode APIs.

This chapter discusses how to:

• Run XML Publisher PeopleSoft Query reports.

• Run reports in Process Scheduler.

• Run reports using PeopleCode.

• Use Time zones in XML Publisher reports.

• Locate and view XML Publisher reports.

Running XML Publisher PeopleSoft Query Reports

You can view and schedule query-based reports with XML Publisher-delivered PeopleSoft Internet Architecture pages.

This section discusses how to:

• Run reports in Query Report Viewer.

• Schedule reports in Query Report Scheduler.

Pages Used to Run XML Publisher PeopleSoft Query Reports

Running Reports in Query Report Viewer

Access the Query Report Viewer page (Select Reporting Tools, XML Publisher, Query Report Viewer.)

The Query Report Viewer allows selection and online viewing of those reports that have a data source type of PeopleSoft Query. Existing Query security applies so that each user has access to run only the reports to which he or she has qualified Query access to the data source.

Note. The data and template translation language choice is automatically supplied to the user’s session language.

Scheduling Reports in Query Report Scheduler

Access the Query Report Scheduler page (Select Reporting Tools, XML Publisher, Query Report Scheduler.)

Query Report Scheduler uses the existing Process Scheduler functionality to:

• Select runtime parameters for query-based and connected query-based reports.

• Monitor the report process request.

• Post and secure the results to either the Report Manager, a printer, or the Process Scheduler file directory.

Note. If a query is run through Reporting Tools, Query, Schedule Query, the XML Publisher-related prompts do not appear. Only the basic table-formatted query results are generated.

See Submitting and Scheduling Process Requests.

Running Reports in Process Scheduler

This section discusses how to:

• Use the Process Scheduler Request page.

• Create the run control page.

• Create a process definition.

• Monitor requests.

Using the Process Scheduler Request Page

At runtime, the Process Schedule Request page appears after you click the Run button on the run control page. This page includes operator-selectable choices of output type and output format. Output type choices reflect the location values from the report definition. Output format choices reflect the output format values from the report definition.

Because values for output location, output format, and viewer security are associated with each report definition, these values should be passed to the Process Schedule Request page. These values are passed automatically only when the process definition type is XML Publisher.

Note. In order to execute XML Publisher reports with DB2 z/OS databases you will need to configure a Process Scheduler on a PeopleTools certified Windows or other UNIX batch server. The PeopleTools Process Scheduler on z/OS cannot execute XML Publisher reports.

Creating the Run Control Page

You need to create a custom run page that contains the prompts required by your report definition.

Your run control page should be a combination of the PeopleSoft PeopleTools-supplied run control subpage and the application-specific section for runtime parameters for the data extraction program. It should include report, template name, language, and as of date. Depending upon your application design, these values could be systematically deduced from user preferences, come from program defaults, or come from the operator input selection.

See Running Processes from PeopleSoft Applications.

Creating a Process Definition

A process type of XML Publisher is delivered as system data and is available on the PeopleTools, Process Scheduler, Process Definition page. When application processes are defined and assigned the XML Publisher process type, entries for output type and format on the runtime Process Scheduler Request page reflect the definitional metadata under the XML Publisher report definition.

The XML Publisher report name, Process Scheduler process name, and the Application Engine process name are the same.

See Defining Process Definitions.

Monitoring Requests

The Process Scheduler processes XML Publisher-based reports. You can define multiple related activities as separate processes. For example, generation of the XML data, the XML Publisher merging of that data with the template and creating the final output, and the subsequent postprocessing to send related emails. Each process appears separately in the Process Monitor. Error messages indicate whether the problem is on the data extraction or the XML Publisher portion of the report request.

Running Reports Using PeopleCode

This section provides an overview of PeopleCode XML Publisher classes and discusses how to:

• Run reports using PeopleCode.

• Choose a template.

• Pass parameters.

• Use time zones in XML Publisher reports.

• Burst reports.

• Customize printed report output.

• Distribute reports.

• Search for reports.

Understanding PeopleCode XML Publisher Classes

All report runtime functionality is available using the PeopleCode XML 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 XML 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 XML 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 Application Engine Programs.

See XML Publisher Classes.

Running Reports Using PeopleCode

The XML Publisher classes enable you to access the runtime portions of the XML publishing process programmatically, that is, after the templates and reports have been created. The XML 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.

Example: Publish a Report Based on PS Query

This is a code snippet example for publishing a report based on PS Query:

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);

Example: Print a Report Based on XMLFile

This is a code snippet example for printing a report based on XMLFile:

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);

Choosing a Template

Because report definition information is available from the PeopleCode XML 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 XML 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.

Passing Parameters

The system may need to pass runtime parameters into the XML Publisher core engine. Numbers and text are sent as strings with single quotes. By default, PeopleTools( through the RepoftDefn 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 XML 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. XML 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.

Bursting Reports

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.

Customizing Printed Report Output

The PeopleSoft application supports batch printing XML Publisher reports directly from a server using PDF output format. Printers with Postscript level 3 interpreter natively support printing PDF format. You can also convert the generated PDF report files to conventional formats supported by other printers, such as Postscript or PCL, by using an external software program. 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 an XML Publisher report to a printer, use the PrintOutput method after the ProcessReport method as shown in this example:

&MyReportDefn.ProcessReport("myTemplate", "", %Date, "PDF");
&MyReportDefn.PrintOutput(&PrinterPath);

If you want to insert conversion logic from PDF to a different printer format 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.

Distributing Reports

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 XML 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.

Searching for Reports

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

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

Using Time Zones in XML Publisher Reports

When displaying datetime values, XML Publisher takes into consideration the time zone of the user running the report. The time zone is retrieved from the user's Personalization settings (My Personalizations, Regional Settings, Local Time Zone). Personalized time zone display is dependent on the following conditions:

• The report template must be either RTF or XSL.

• The datetime element in the XML file must include the UTC offset, for example, 2008-07-28T09:00:00-0700.

  Note. A Query data source includes the offset for datetime fields.

• The time zone must have a valid 3 character time zone code, for example PST or EST. If custom time zones have been implemented in your environment, XML Publisher does not recognize these custom time zones and will display the time in UTC.

• The datetime field in the template should be formatted using an Oracle abstract format mask that displays the time zone. For example:

  <?format-date:STARTDATETIME;'SHORT_TIME_TZ'?>
  

  Note. Oracle abstract format masks are listed in Oracle Business Intelligence Publisher Users Guide, “Creating an RTF Template,” Using Oracle Abstract Format Masks.

Note. XML Publisher uses Java Time Zones based on the JRE running under the PeopleSoft application server. In some releases of JRE, a known issue exists in that Daylight Savings Time is calculated incorrectly for EST, MST, and HST timezones. This problem has been documented by Sun and a solution is available on their website: http://java.sun.com/developer/technicalArticles/Intl/alert.html

Locating and Viewing XML Publisher Reports

This section discusses how to search the XML Publisher report repository.

Pages Used to Locate and View XML Publisher Reports

Searching the XML Publisher Report Repository

Access the XML Report Search page (Select Reporting Tools, XML Publisher, XMLP Report Search.)

Enter criteria to filter the reports to list. XML Publisher Report Search ignores criteria for fields that are blank.

See Viewing Reports.

Viewing Reports Using Additional Search Keys

Users can also search by the following criteria for bursted reports:

• A specific value in the Burst By field.

  This is a read-only field that appears automatically when a value is set in the Burst by field of the Report Definition, Bursting page.

• Up to two additional values in the predefined bursting Search Key fields.

  These drop-down list boxes display the values set in the Search Keys region of the Report Definition, Bursting page.

To view bursted reports using the additional search keys:

1. Select the Case Sensitive check box to perform a case-sensitive search.

2. For the Burst By field, select a search operator.

3. Enter a value to search on.

4. For the additional Search Key fields, select the search field name, search operator and search value.

See Setting Bursting Options.