Running, Locating and Viewing XML Publisher Reports

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

This chapter discusses how to:

• Run XML Publisher PeopleSoft Query reports.

• Run reports using PeopleCode.

• Run reports in Process Scheduler.

• 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 Reports

Running Reports in 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.

Access the Query Report Viewer page.

Show Template Prompts	Click this link to expand the Report Definition Search Results grid to include the template ID and as of date template prompts.
Report Name	A read only field that indicates the name of the report.
Description	A read-only field that indicates the report's description.
Data Source ID	A read-only field that indicates the report's data source ID.
Template ID	Select from the templates associated with the report definition.
As Of Date	Select the as of date for the template version you want to view.
Format	Select from the output format choices associated with the report definition.
Burst	A read-only field that indicates whether the report definition includes bursting instructions. Bursted reports are listed, but they aren't executable from the Query Report Viewer component. Note. Bursted reports must be run from the Query Report Scheduler component.
View Report	Click this link to view the report online. When they exist, the Query’s runtime parameters are presented. A new window opens displaying the report results according to the runtime inputs. You can save the report results locally by using the browser's Save functionality. Note. This link is disabled for bursted reports.

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

Note. If an old query (created using Windows Query Manager) is used as your data source, you may receive an error message Rowset Object cannot be empty while running a report through Query Report Viewer or XML Publisher Report Scheduler. To correct this problem, resave the query in PeopleSoft Pure Internet Architecture which will update the metadata.

Scheduling Reports in Query Report Scheduler

Query Report Scheduler uses the existing Process Scheduler functionality to:

• Select runtime parameters for 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.

Access the Query Report Scheduler page.

Run Control ID	Enter a run control ID.
Language	A read-only field that indicates language of the run control. The report selects data and template translations based upon the language code of the run control. This value is set by the user on the My System Profile, General Profile Information page in the My Preferred Language for Reports and Email field. The language is displayed in the Query Report Scheduler Search Results so you are informed of the language selection criteria.
Report Name	Select the name of the Query-based report that you want to schedule. The drop-down list box values are based on previously registered report definitions. Existing Query security applies so that each user only has access to run reports to which they have Query access.
Burst Field Name	A read-only field that displays the value set in the Burst byfield of the Report Definition, Bursting page. This field appears for bursted reports only.
Dynamic Template	A read-only field that displays either Active or Inactive depending on whether there is criteria to dynamically select the template and/or language based upon a data value set in the Templategroup box of the Report Definition, Bursting page. This field appears for bursted reports only.
Bursting Security	A read-only field that displays either Active or Inactive depending on whether there is criteria to assign unique bursting security set in the Burst Securitygroup box of the Report Definition, Bursting page. This field appears for bursted reports only.
Template ID	Select from the templates associated with the report definition.
Template As Of Date	(Optional) Select the as of date for the template version to use for the report. The system looks at the report definition for templates that are active as of this date.
Channel	A read-only field that indicates the distribution channel of the template.
Update Parameters	Click this link to update the Query’s runtime prompt values. The first time a report is selected to be assigned to the run control ID, all existing Query prompts and prompt values also appear.
Report Manager	Click this link to go to the Report Manager to check the progress of your process request and to view the report content immediately after the output file is posted. The final output file is posted to the Report Manager repository for web access by authorized users. See Using Report Manager.
Process Monitor	Click this link to go to the Process Monitor to check the progress of your request. See Using Process Monitor.
Run	Click this button to access the Process Scheduler Request page. The Process Scheduler Request page enables you to specify variables, such as where a process runs and in what format the process output is generated. The values for output type and output format appear by default per the report definition and can be changed if the report definition allows it. Distribution options are also active allowing updates to viewers, again only as allowed in the report definition.
Go to XMLP Report Search	Click this link to access the XMLP Report Search page. See Searching the XML Publisher Report Repository.

See Submitting and Scheduling Process Requests.

Running Reports in Process Scheduler

This section discusses how to:

• Use the Process Scheduler Request page.

• Create 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.

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

Creating Run Control Page

You will 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 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. Multiple related activities can be defined 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 post-processing 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.

• 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 you use to define custom reports respect the report category security assigned to the report definition. Users with read-only access to report definitions are not be able to 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 Report 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 the following:

import PSXP_RPTDEFNMANAGER:*;

See Report Manager Definition Classes Constructors.

Example: Publish a report based on PSQuery

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

/* get report definition object */
&oRptDefn = create PSXP_RPTDEFNMANAGER:ReportDefn (&sRptDefn);
&oRptDefn.Get();
/* fill query runtime prompt record */
&rcdQryPrompts = %RptDefn.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:

/* 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);
/*publish report */
&oRptDefn.PrintOutput(&sDestinationPath);

Choosing a Template

Since report definition information is available using 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

It may be necessary to pass runtime parameters into the XML Publisher core engine. Numbers and text are sent as strings with single quotes.

The RepoftDefn class ProcessReport method always passes the following parameters. These tag names can be included in report templates and sub-templates. When needed, the following instructions must be entered under form fields at the top of the report’s primary template; one for each value:

• <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 support 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.

Generated XML Publisher reports are sent to a printer by calling the PrintOutput method after using the ProcessReport method, as follows:

&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 Process Scheduler server’s home directory %PS_HOME%\appserv\prcs\%domain_name% and write a call to an external conversion program in this batch file.

The following is a sample from a psxprint.bat batch file on Microsoft Windows that uses a program called pdftops to convert a PDF file generated by XML Publisher to a Postscript level 2 file:

@echo PRINT JOB LOG > %RPTOUTDIR%\prtjob.log
c:\\user\\bat\\pdftops -level2 %REPORTFILE% %RPTOUTDIR%\out.ps >> %RPTOUTDIR%\prtjob.log
copy %RPTOUTDIR%\out.ps %DESTPRINTER% >> %RPTOUTDIR%\prtjob.log

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

%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 so allowed by the report definition.

When the report definition has the Allow viewer ID assignment at report runtimecheck 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.

Locating and Viewing XML Publisher Reports

This section discusses how to:

• Search the XML Publisher Report Repository.

• View reports.

Searching the XML Publisher Report Repository

Access the XML Publisher Report Search page.

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 are also able to search by the following criteria for bursted reports:

• A specific value in the Burst By field.

  This is a read-only field that displays automatically when there is a value set in the Burst byfield 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 Keysregion 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 that you want to search on.

   Then select a search operator and a value to search on.

See Setting Bursting Options.