Defining Report Definitions

This chapter discusses how to:

• Create report definitions.

• Assign report viewers at runtime.

• Maintain sub-templates.

• Maintain template translations.

Creating Report Definitions

This section provides an overview of report definitions and discusses how to:

• Define reports.

• Associate templates.

• Set output options.

• Set report properties.

• Set security options.

• Set bursting options.

Understanding Report Definitions

Report definitions associate a data source with template files. A data source registers the schema and sample data design files. The extracted application fields from the data source files are placed into the template files to create the final report.

A report can include multiple templates. A template is used to associate different layout formats as required by different countries and regions or as required by different channels (web posting, printer, fax, and so on).

The defined output options from the report definition are reflected on the output type and format prompts on the Process Scheduler request page when the application process that runs the report is assigned the process type of XML Publisher. Security settings for a report definition determine who can view the report when it has been run.

Report properties can be set to control formatting of the report.

With the advanced bursting feature, report generation results in separate output files when bursted reports are run through Process Scheduler.

Report definition access is based on user permission list security and roles. For example, bursting is read-only for XML Publisher power users, because only developers can set up bursting, and the page only appears when settings exist.

XML Publisher power users can start to define a report to download the sample data files to create their templates.

Pages Used to Create Report Definitions

Defining Reports

Access the Definition page (Reporting Tools, XML Publisher, Report Definition, Definition.)

Report Name	Enter a report name. The report name must be unique, and it must not contain any special characters. If you enter spaces in the report name, the system replaces them with underscores.
Data Source Type	Select Connected Query, PS Query, Rowset, XML Doc, or XML File. Note. For XML Publisher power users, the data source type is PS Query only and the drop-down list box is disabled. Rowset and XMLDoc are deprecated in PeopleTools 8.50. If the data source was defined in a previous release, it will be available. You can not create a new data source for rowset or XmlDoc. See Registering Data Sources.
Data Source ID	Select the data source ID. You can choose from data source IDs that are based on previously registered data sources. You can select queries regardless of whether they have been previously registered as data sources. For queries, the lookup table respects the public, private, and query access group security for the current user ID. When you save a report definition with an unregistered query data source, the query is systematically registered as a data source. The query has no object owner ID, but that value can be entered manually on the Data Source page, if required.
Data Source Description	This is a read-only field that reflects the value that was entered when the data source was registered. For unregistered query data sources, this field reflects the query description.
Report Description	(Optional) Enter descriptive text that provides more detail about the report. If this field is left blank, the report name appears by default.
Report Status	Select Active, In Progress, or Inactive. Setting the report status allows work in progress as well as retirement of report definitions. Active reports must have at least one active template. Only active reports can be selected at runtime and run to success.
Report Category ID	Select a report category ID. This is a grouping mechanism for reports that provides row-level security for editing report definitions per the rights defined on the report category setup table. See Setting Up Report Categories.
Object Owner ID	(Optional) Indicate which product, feature, or application owns this report. Note. The default value that appears here is based on the Object Owner ID setting in the Report Category component (PSXPSETUPRPTCAT).
Template Type	Select PDF, RTF, ETX, or XSL. Note. ETX is only available if the data source is XML file. Only one template type is allowed per report. The template file extension that you can upload on the Template page is controlled by this value. This value also controls which report templates appear on the Translation component (PSXPTMPLTRNS), because only RTF templates are translatable.
Retention Days	(Optional) Enter a value to set the option to purge the reports from the Report Repository and archive the data to the Report Archive table. The value that you enter overrides the system setting for retaining reports. The maximum value that you can enter is 999 days. If you don't select a value, the value from the PeopleTools, Process Scheduler, System Settings page applies. Only XML Publisher report developers or power users with permission list PTPT2600 or PTPT2500 can set this value. See Maintaining Reports.
Registered Date/Time	This is a read-only field maintained by the system that indicates the date that the initial report definition was registered.
Updated Date/Time	This is a read-only field maintained by the system that indicates the date that the last update to the report definition was made.
Registered By	This is a read-only field maintained by the system that indicates the user ID of the operator who initially registered the report definition.
Updated By	This is a read-only field maintained by the system that indicates the user ID of the operator who last updated the report definition.
Download	Click Data Schema to detach the schema file or Sample Data to detach the data file. Detaching the files enables the user to view the data elements prior to finalizing the report definition. These links appear if the related files exist on the registered data source. For PS Query data sources, both links always appear regardless of whether the data source is registered because these files are system-generated. See Registering Data Sources.

Associating Templates

Access the Template page (Reporting Tools, XML Publisher, Report Definition, Template.)

The Template group box on the Template page refers to a particular template layout, because one report definition can associate multiple template layouts differentiated by language code or channel.

Adding Template Files

Within each template layout defined previously is one or more effective-dated versions of the template. For example, you can have a new government form for each year. In the Template Files group box, you attach effective-dated files that are the actual report templates.

Note. The preview button uses the sample XML data file to generate report output. Sometimes, if the sample data does not match the real data, you may find discrepancies between preview and real report outputs. This is specifically true when the report template uses sample data in variables and conditional formatting. Creating your own sample file with real data makes the report look more realistic. This sample file can also be used to preview reports using template builder.

See Mapping Data Tags.

Mapping PDF Template Files

For PDF files, a mapping is sometimes required between the field elements from the data source and the form field elements on the PDF template in order for the XML data element tags to print in the correct place within the PDF template. This is often true for third-party PDF templates, for which the form fields already exist inside the form template. However, if you create PDF form fields and XML tag names that are the same, no mapping is necessary.

The following fields appear on the Template page for PDF templates files:

This is an example of XML file that requires full path mapping:

<PayChecks> 
  <PayCheck> 
    <EmpNo>00001</EmpNo> 
    <CompanyInfo> 
      <Address>1 Company st. CA 00001</Address> 
      <Description>Company Info</Description> 
    </CompanyInfo>   
    <EmployeeInfo> 
      <Address>1 Employee st. CA 00001</Address> 
      <Description>Employee Info</Description> 
      <Salary>50000</Salary> 
      <Vacation>12</Vacation> 
      ...... 
    </EmployeeInfo> 
  </PayCheck> 
  <PayCheck> 
    ...... 
  </PayCheck> 
  <PayCheck> 
    ...... 
  </PayCheck> 
</PayChecks>

The JavaScript plug-in will use the full path for address data elements instead of the element name. So it will use PayCheck.Employee.Address to map to the employee’ address form field, and use PayCheck.Company.Address to map to the company’s address field.

See Mapping Data Tags.

Setting Output Options

Access the Output page (Select Reporting Tools, XML Publisher, Report Definition, Output.)

Format Type	Dynamically lists the available output formats based on the template type.
Enabled	Select specific values to limit the output choices for the user at runtime.
Default	Select a default format type. This value appears at runtime on the prompt or run control page. It specifies the output format that the system uses if no other value is fed into the XML Publisher engine.
Location	Select one of the following locations: Any indicates that the user can select the output location at runtime. Email indicates that the output goes to email. Note. The users defined in the distribution list must have a valid email address defined in the user profile. If Allow viewer assignment at report runtime is selected, you can enter additional email addresses at runtime. File writes the output to the file that you indicate in the Output Destination field. Printer indicates that the output goes directly to a printer. Specify the printer destination for the output in the Printer field. This field is available only when the output location that you select is Printer. Printer is a valid selection only when PDF output format is enabled. Web indicates that the output goes to a web report repository that is accessible by the Report Manager. Select the folder for the output from the Report Manager Folder Name lookup. This field is available only when the output location that you select is Web. This is the default location used at runtime if no location is selected. Window indicates the output will be posted, like Web output, to the report repository and then streamed to the browser window, the same way scheduled query runs to Window. Note. Window output is supported for scheduled and non-bursted reports only. Users building a custom process request page should check for the bursting field name (BurstFieldName) in the ReportDefn class before issuing a process request.
File Name	Specify a file name template that gets translated at runtime to a physical file name. This field accepts a combination of output variables and plain text. Output variables are enclosed within percent signs (%) and used as part of the descriptive report name on report search page. The following variables are supported. %ASD% inserts the as of date. %RID% inserts the report ID. %BTV% inserts the burst field value. %field% where field is the name of a field from the XML data that lies below the first repeating field. For example, if you want the employee ID value to appear in the file name, you would use %EMPLID%. Note. All burst key candidates on the bursting page are eligible. For example, if you have a report CERTIFICATE that is burst by STUDENT_ID, you can use the file name to provide more details: If no file name is specified, the report description will use the report name, such as CERTIFICATE[2916]-CERTIFICATE.HTM. If a file name of LOCATION %TRAINING_LOC% %END_DT% is specified, the report description will include the variables, such as CERTIFICATE[2916]-LOCATION BOSTON 2009–03–13.HTM. If a file name of%STUDENT_NAME% is specified, the report description will include the variables, such as CERTIFICATE[2916]-LEE,JAMES.HTM. Note. If you leave the File Name field blank, the system uses the report ID as the file name. For bursted report, burst value can be used as file name if set programmatically through the ReportDefn class property UseBurstValueAsOutputFileName. The Userfilename can also be set programmatically as a property of the ReportDefn class. If a Userfilename is set either in PeopleCode or on the page, it overrides the UseBurstValueAsOutputFileName property.

Note. The XML Publisher report definition output options are reflected in the output type and output format prompts on the Process Scheduler Request page only when the application process that runs the report is assigned the process type of XML Publisher.

Output Format Options

The output options are based on the template type as shown in this table:

Printing XML Publisher Report Output

PeopleSoft applications support batch printing XML Publisher reports directly from a server using PDF output format. When you select Printer as the output location, PDF is the only output format displayed in the Process Scheduler Process Request Dialog page. When PDF format is not supported for a report definition, printing is not supported for that report. If you are not printing directly upon posting the report, you must open and print the report from Adobe Acrobat. All bursted output reports are sent to a single printer, but as multiple print jobs.

You can also convert the generated PDF files to other conventional printer output formats with an external software program. PeopleSoft applications provide PeopleCode support for inserting conversion logic from PDF to different printer formats.

See XML Publisher Classes, Scheduling Process Requests, Customizing Printed Report Output.

Setting Report Properties

Access the Properties page (Select Reporting Tools, XML Publisher, Report Definition, Properties.)

Properties defined in the report definition will override the global properties for this report.

See Defining Global Properties.

Setting Security Options

Access the Security page (Select Reporting Tools, XML Publisher, Report Definition, Security.)

The Security page captures attributes regarding who can view web-posted output in the Report Manager repository and through the XML Publisher Report Repository Search page.

Note. The users and roles defined on this page can view all bursted reports. If you are using security join tables to limit report distribution, do not enter any roles or users on this page.

Setting Bursting Options

Bursting is an optional advanced feature that is available only when reports are run through Process Scheduler. It is not intended for real-time online viewing. It is typically used when you are repeating the generation of a templated report layout many times for multiple like sets of data, for example, generating a batch run on vendor purchase orders or customer invoices. With bursting, you can generate individual report files resulting in separate secured output, for example, generating a file for each vendor, customer or employee.

Setting up bursting requires thorough knowledge and understanding of data values and schema structures. You could possibly make entries on the Bursting page that would cause the report to fail at runtime. When you generate a bursted report, the system creates separate document files for each unique data value for a specified field tag.

Note. This Burst by field tag must be from the highest level repeating group (node) in the XML data. For bursting to work, only one high-level repeating group should be in the XML source.

Because bursting is an advanced feature, PeopleTools delivers permission list security that is intended for XML Publisher report developers (PTPT2600). When users are assigned a role with this permission list, they have access to setup entries on the Bursting page. A view-only permission list (PTPT2500) option also exists for XML Publisher power users that provides view-only access to the bursting information. The Bursting page appears for the power user only when bursting instructions exist for the report.

Note. In previous versions of XML Publisher, schemas were necessary for bursting. For backwards compatibility, you can still register and use schemas to define bursting. Sample files are the recommended approach since the existence of schema file in the data source definition indicates that backward compatibility is necessary and therefore schema will be used.

Access the Bursting page (Select Reporting Tools, XML Publisher, Report Definition, Bursting.)

Burst by

Select a burst by field to enable report bursting. All subsequent bursting features are disabled until you select this value The values in the drop-down list box are the children from the highest-repeating level (group node) in the XML schema associated with the data source that is assigned to the report definition. When you select a burst field, the report generates multiple files at runtime with a separate report instance file generated each time a unique value appears for the Burst by data tag. For example, this could be one report file for each employee when you are bursting by EmplID or one report for each department (that includes multiple occurrences of the report, one for each employee) when you are bursting by DeptID.

Use Unique Burst Value

Select this check box to indicate that the Burst by field contains unique values. If a non unique value is found, the report will not be published and an error will be logged. It is recommended to use unique bursting values. If this check box is cleared, bursted files with the same Burst by field will be combined in one report. Note. Prior to 8.5x, unique burst value was not enforced. Non unique burst value will produce unpredictable results including incorrect search.

Template Assignment for Bursting (Optional)

This feature dynamically drives the template assignment at runtime based upon the data value of a designated schema tag. You can assign a language code to apply a specific template translation as well. This means that the various bursted report occurrences in one batch run can each have an appropriately assigned template and translation. For example, you can print Canadian paychecks in English or French depending upon the employee’s preference.

You should select a template ID for each data value that requires a special template.

At runtime, the process looks for the specified template and language. If the language does not exist, then it applies the base untranslated template. If the process encounters a data value that is not assigned on the report definition, then it assigns the template ID that is entered on the run control. If the system captures no template ID selection at runtime, then it applies the default template of the report definition.

Security for Bursting (Optional)

When a report is set up to be bursted, the report designer can also designate how the generated documents are secured when they are posted to the Report Manager. At runtime, the system uses this information to determine who can view each bursted report instance. You can use bursting security to supplement or replace the basic report viewer security by role or user ID. Otherwise, the system limits access to each report instance based on preexisting system security definitions.

The system automatically limits access to each report instance based on the Burst by field. For example, if the report is burst by employee ID, only the users designated with access to each employee ID can view the output file.

The report designer must provide the record name of the security join table and designate the common fields to join with the bursting field. The system performs the join and determines who can view the report instances. This matching allows the Report Manager’s posting process to dynamically identify the user IDs or roles that are assigned viewing rights for each report instance.

Note. If a user has the role ReportDistAdministrator, that user can view all bursted reports, regardless of security join table.

Search Keys (Optional)

When report results are burst into separate files, you should be able to locate the desired individual report from the Report Manager repository. Delivered search keys include Burst By, Report Definition Name, and Generated On Date. You can define additional search keys to provide even more specific granularity.

At report runtime, the report posting program uses this information to store the key names defined here along with the specific data values for each burst report. From the XML Publisher Report Search page, users can use these configurable search fields to locate a specific report occurrence. For example, if the pay advice report runs regularly and posts numerous report files for self-service access, and as an employee you want to locate a particular dated advise, you would not want to browse through all the advise files to locate the one you want to see. By assigning the pay period as a Search Field in the report definition, the user can enter a date to search for the correct advise.

Assigning Report Viewers at Runtime

There are three settings in the report definition that determine how web reports are distributed at runtime:

1. Report Viewer List on the report definition security page.

   Assign users and roles allowed to view the reports regardless of whether the report is bursted or not.

2. Security Join Table on the report definition bursting page.

   Assign users that can view individual bursted report files based on security join tables. These users are combined with the users and roles defined on the security page.

   Note. When security join tables are used, and the Allow viewer ID assignment at report runtime check box is selected, any users, roles or email addresses added at runtime will see all bursted reports. If roles or users are defined on the security page or at runtime, they can view all bursted reports ignoring the security join table.

3. Allow viewer ID assignment at report runtime check box on the report definition page.

   Allows the users running the report the ability to modify (add or remove) additional roles, users or email addresses on the runtime report distribution page.

This table describes how viewers are selected for non-bursted reports based on the report definition security settings.

This table describes how viewers are selected for bursted reports based on the combination report definition settings.

Maintaining Sub-Templates

This section provides an overview of sub-templates and discusses how to maintain sub-templates.

Understanding Sub-Templates

You may have text, images, or logic in your templates that you want to reuse across many report templates. Examples include company headquarter address information or standard legal language. Rather than replicate this text, code in every template, or both, you can store sub-template files that include the reusable content. These sub-template files are referenced with standard XSL commands in the primary template file. Sub-template functionality is available for use only with primary RTF and XSL templates.

Sub-templates are secondary RTF or XSL templates that are imported by primary RTF or XSL report templates. The primary template accesses the sub-template through the XSL import style sheet feature. You can import any XSL style sheets or other RTF or XSL templates using standard XSL import and call functions. PeopleTools simplified sub-template syntax is also supported.

Primary templates calling nonexistent or inactive sub-templates causes an error message to be issued indicating the reason for the problem. This error information is incorporated into Process Scheduler error handling as well as into online viewing or previewing of the report.

The sub-template files are independently stored and are not registered in association with a data source or primary template. This being the case, if any form fields exist inside the sub-template, the report in which the sub-template is placed must have a related data source that supplies those fields, or the data must be passed in as runtime parameters.

The Content Library is a component provided for the registration of reusable sub-template files. The metadata is similar to that of primary template files and includes the sub-template ID, sub-template description, language, object owner ID, report category, effective date, and status. As with Report Definition security, sub-template editor registration security is applied through report categories. Because Report Category secures the data in the component, you can assign select users read-only access for a report category. These users can browse, view, and download sub-template files but not add them. This facilitates the offline design of primary templates for users who can access the library of existing sub-templates but who can’t alter them.

Sub-template names are not exposed to the end user at either report design time or runtime. The complete template (primary and sub-templates) is systematically assembled by the XML Publisher engine during report generation. The same occurs during online previewing as long as the sub-template file exists.

Note. No method is available for viewing which report templates include which sub-templates. This means that users must be careful about changing, deleting, or inactivating sub-templates.

Page Used to Maintain Sub-Templates

Maintaining Sub-Templates

Access the Content Library page (Select Reporting Tools, XML Publisher, Content Library.)

Sub-Template ID	Enter a unique sub-template ID.
Description	(Optional) Enter descriptive text that provides more detail about the sub-template and identifies its use.
Language	Select a language code for the sub-template. The default value reflects the users base language.
Report Category ID	Select a report category ID. This is a grouping mechanism that provides row-level security for editing sub-templates per the rights defined on the report category setup table. See Setting Up Report Categories.
Object Owner ID	(Optional) Indicate which product, feature, or application owns this sub-template. Use this field to extract and package production data source and report registrations and their supporting files.
Sub-Template Type	Select RTF or XSL.
Effective Date	Select an effective date for the sub-template file in order to maintain new versions or versions that are specific to a particular time period. For example, a new file could be uploaded to reflect a new format or new legal language for reports, and the new sub-template is automatically used as of the new effective date. The default date for a newly added sub-template file is the current system date. This effective date has no correlation with the effective date of the primary template. The as of date on the Query Report Viewer, Query Report Scheduler, or Run Control page determines which effective-dated templates and sub-templates are run.
Status	Select a status of In Progress, Active, or Inactive for the sub-template file. This field indicates the usability of the sub-template file. Runtime selection logic for a sub-template file uses this field in conjunction with the Effective Date field to determine which sub-template file to use at runtime. At least one file must be active to save a sub-template in the Content Library.
Template File	Displays the name of the sub-template file.
Upload	Click to attach an actual effective-dated sub-template file. When you save the sub-template, this button becomes disabled. To reupload a new version of the sub-template, you must delete and add it again.
Download	Click to download the sub-template to your local computer for updating.
View	Click to view the contents of the sub-template.

Maintaining Template Translations

This section provides an overview of template translations and discusses how to:

• Search template translations.

• Maintain template translations.

Understanding Template Translations

The Template Translation component interacts with both report definition templates and Content Library sub-templates. Template translation files can be created only when a report’s template type is RTF. Template Translation is a separate component with no row-level security, because the target user is different from the report developer, requestors, or viewers.

The Template Translation feature is based upon standard Localization Interchange File Format (XLIFF) .xlf file processing. Each report template or sub-template file can have related translation XLIFF files. These XLIFF files include translation units for each content element to be translated. The translatable units include all the fixed verbiage of the template excluding any values supplied by the data source. The Template Translations page includes an action button that generates a translatable file that must then be manually edited with the appropriately translated values. When the translation exercise is complete, the XLIFF file is uploaded and integrated into the XML Publisher translation system.

The Template Translation Search page provides advanced search capabilities to facilitate the location and management of template translations. Using this search page, you can determine whether a particular translation exists. The search can be focused by template or report, thus handling both Report Definition templates and Content Library sub-templates. You can also search based on target language.

Note. A template must exist before it can be translated.

Template translations are not available for template types other than RTF. For a PDF report, multiple PDF templates must be registered to the report, one for each locale or language as required.

Pages Used to Maintain Template Translations

Searching Template Translations

Access the Template Translations Search page (Select Reporting Tools, XML Publisher, Translations.)

To search for a template translation:

1. Select either the Report Template or Sub-template option, depending on whether you want to search the Report Definition templates or the Content Library sub-templates.

   The subsequent search prompts vary depending upon this choice. For example, the Report Name drop-down list box appears only if Report Template is selected.

2. Select your search criteria and click the Search button.

   The Translated check box appears only when you have selected a value in the Target Language field. When selected, this check box enables you to search for templates that have already been translated into the selected target language. If this check box is cleared, you are searching for templates that have not yet been translated into the target language.

3. When your search results appear, select the effective date of the template for which you want to maintain translations.

Maintaining Template Translations

Access the Template Translations page (Select Reporting Tools, XML Publisher, Translations.)

Template ID/Sub-Template ID	Displays the unique template ID or sub-template ID.
Effective Date	Displays the effective date as registered for the template under the Report Definition component or for the sub-template under the Content Library component. Note. The translation inherits the same date and cannot be changed.

Report Properties

When the file to be translated is a report template, basic metadata about the report appears. This information does not appear when the file selected is a Content Library sub-template.

Template Properties/Sub-Template Properties

The Template Properties/Sub-Template Properties group box displays basic metadata about the base-language template file that has been selected for translation.

Translatable Files

The generated translatable XLIFF file includes the template’s static headings and body text that require translation into another language. At the top of the file, the <source-language> tag indicates the base language value. You must update the <target-language> tag to the language that you are translating into. Initially the <source-language> and <target-language> values are the same. Prior to uploading the translated file into the database, you must edit the <target-language> tag to the translated language code. The value must be the two-character ISO language code.

For example, fr equals French, jp equals Japanese, and so on. The file won't load if the file type isn’t .xlf or if the <source-language> equals the <target-language> and an error message appears.

In the <body> section of the file, each <trans-unit id> tag contains both a <source> tag and a <target> tag. The <source> tag contains the text in the base language. The corresponding <target> tag contains the translate fixed text.

No naming restriction is placed on XLIFF files; however, you should keep them close to the template file name and include the language. For example, for a French translation of the XRFWIN template, you could use XRFWIN_FR.xlf.

This code is an example of a translated XLIFF file:

  <?xml version="1.0" encoding="utf-8" ?>
- <xliff version="1.0">
 - <file source-language="en-US" target-language="fr-FR" datatype="XDO" 
     original="orphen.rtf" product-version="orphen.xlf" product name="">
     <header />
   - <body>
     - <trans-unit id="" maxbytes="4000" maxwidth="15" 
         size-unit="char" translate="yes">
         <source>Total</source>
         <target>Totale</target>
         <note>Text located: body/table</note>
       </trans-unit>
     - <trans-unit id="" maxbytes="4000" maxwidth="22" 
         size-unit="char" translate="yes">
         <source>Seq Name/</source>
         <target>Nom de Seq/</target>
         <note>Text located: body/table/table header</note>
       </trans-unit>

Translation Files

You maintain the translated XLIFF files for your templates in the Translation Files grid .