Defining Report Definitions

This chapter discusses how to:

• Create report definitions.

• Use the Content Library to maintain sub-templates.

• Maintain template translations.

• Run XML Publisher-enabled reports.

Creating Report Definitions

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

• Define reports.

• Associate templates.

• Set output options.

• 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. It is the extracted application fields from the data source files that are placed into the template files to create the final report.

A report may include multiple templates. A template is used to associate different layout formats as required by different countries/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. Report definition security settings determine who can view the report once it has been run.

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 there are existing settings.

XML Publisher power users can start to define a report in order to download the sample data and schema design files to create their templates.

Pages Used to Create Report Definitions

Defining Reports

Access the Definition page.

Report Name	Enter a report name. The report name should be a unique ID, and it must not contain any special characters. If spaces are entered in the report name, they are replaced by underscores.
Data Source Type	Select PSQuery, Rowset, XML Doc, or XML File. Note. For XML Publisher power users, the data source type is PSQuery only and the drop-down list box is disabled.
Data Source ID	Select the data source ID. You can choose from data source IDs that are based on previously registered data sources. Queries can be selected whether or not 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. Upon saving 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 updated 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 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 set in the Report Category component.
Template Type	Select PDF, RTF, eText, or XSL. Only one template type is allowed per report. The type cannot be altered once the first template file has been uploaded and saved. The template file extension that can be uploaded on the Template page are controlled by this choice. This value also controls which report templates appear on the Translation component, as only RTF templates are translatable
Days Before Purge	(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 entered here overrides the system setting for retaining reports. The maximum value that can be entered is 999 days. If no value is selected, the value from the PeopleTools, Process Scheduler, System Settings, System Purge Options page applies. Only XML Publisher report developers with permission list PTPT2600 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 the ability 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 query data sources, both links always appear whether the data source is registered or not, because these files are system generated.

Associating Templates

Access the Template page.

The Template group box of 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 above is one or more effective-dated versions of the template. For example, you may 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.

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 know where they should print within the PDF template. This is often true for third party PDF templates, where the form fields already exist inside the form template. However, if you create PDF and name tags that are the same to begin with in your PDF file, no mapping is necessary.

When working with PDF map files, some indication of mapping should be included in the name to distinguish it from the unmapped template file. For example, the template file XRFWIN.pdf would have a map file XRFWINm.pdf.

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

See Mapping Data Tags.

Setting Output Options

Access the Output page.

PDF report output may be edited	Select this check box to indicate whether the internal Adobe flag of a PDF report output file has the setting turned on to allow editing.
Format Type	A read-only field that dynamically lists the available output formats based on the template type.
Enabled	Select specific values here to limit the output choices for the user at runtime.
Default	Select a default format type. This value is displayed at runtime on the prompt or run control page. It is also 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. File indicates that the output goes to a file server in a Process Scheduler server directory location. Enter the file path for the output in the Destination field. This field is available only when the output location that you select is File. 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 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.

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

Based on the template type, the output options are as follows:

Printing XML Publisher Report Output

PeopleSoft supports batch printing XML Publisher reports directly from a server using PDF output format. When Printer is selected 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.

It is also possible to convert the generated PDF files to other conventional printer output formats with an external software program. PeopleSoft provides PeopleCode support for inserting conversion logic from PDF to different printer formats.

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

Setting Security Options

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.

Access the Security page.

Allow viewer ID assignment at report runtime	Select this check box to indicate whether the report requestor can add to the standard Distribute To values on the Process Scheduler Request, Distribution Detail page.
ID Type	Select an ID type of either Role or User ID.
Distribution ID	Select a corresponding distribution ID based on the ID type.
Description	A read-only field that displays the related description of the distribution ID.

Setting Bursting Options

Bursting is an optional advanced feature that is only available when reports are run through Process Scheduler and 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. It is possible to make entries on the Bursting page that would cause the report to fail at runtime. When you generate a bursted report, separate document files are created 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 schema. For Bursting to work, there should be only one high level repeating group in the XML source.

Bursting can only be defined when the report’s data source has an associated schema file. Numerous bursting instructions depend upon the data coming from the application as defined by the schema tags.

As 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. There is also a view only permission list (PTPT2500) option for XML Publisher power users that provides view-only access to the bursting information. The bursting page appears for the power user only when there are existing bursting instructions for the report.

Note. In order for a schema field to take advantage of the bursting features, it must be registered with the data source of the report definition.

Access the Bursting page.

Burst by

Select a Burst by field to enable report bursting. All subsequent bursting features are disabled until this value is selected. 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 assigned to the report definition. Once selected, 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 bursting by EmplID or one report for each department (that includes multiple occurrences of the report, one for each employee) when bursting by DeptID.

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.

A template ID should be selected 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 the base untranslated template is applied. If a data value is encountered that is not assigned on the report definition, then the template ID entered on the run control is assigned. If no Template ID selection is captured at runtime, then the default template of the report definition is applied.

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, this information is used to determine who can view each bursted report instance. Bursting security can be utilized 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 are able to 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 determine 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.

At least one type of security should be completed either on the Security page or on the Bursting page. Set security in both places to secure bursted files differently from securing the report definition. If security on the Bursting page is blank, then the security set on the Report Definition Security page applies. If the Security page is also blank, then the report requestor gets put in as the viewer by default and all the bursted report files are accessible only by the report requestor. Security can be assigned from all three places, if desired.

Search Keys (Optional)

When report results are burst into separate files, it is important to 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. Additional search keys may be defined 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 utilize 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 really want to see. By adding a data value in the data source for ‘pay period’ and assigning that field as a bursting search key, the employee is then able to enter a date when searching their pay advises.

Using the Content Library to Maintain 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 and/or code in every template, you have the ability to 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. Any XSL style sheets or other RTF or XSL templates can be imported by following standard XSL import and call functions. PeopleTools simplified sub-template syntax is also supported.

Primary templates calling nonexistent or inactive sub-templates present an error 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 sub-template ID/Name, 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, select users can be assigned Read Only access for a Report Category. These users are able to 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. There is no method 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.

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 user's 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. This field is used 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 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 sub-template file selection logic uses this field in conjunction with the Effective Date field to determine which sub-template file should be used at runtime. At least one file must be active to save a sub-template in the Content Library.
Template File	A read-only field indicating the name of the sub-template file.
Upload	Click this button to attach an actual effective dated sub-template file. Once the sub-template is saved, this button becomes disabled. To reupload a new version of the sub-template, you must delete and re-add it.
Download	Click this button to download the sub-template to your local computer for updating.
View	Click this button 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 interfaces 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, as 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. Once 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 or not 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, there must be multiple PDF templates 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.

To search for a template translation:

1. Select either the Report Template or the 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. This check box, when selected, enables you to search for templates that have already been translated into the selected target language. If cleared, you are searching for templates that have not yet been translated into the target language.

3. Once 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.

Template ID/Sub-Template ID	A read only field indicating the unique template ID or sub-template ID.
Effective Date	A read only field that indicates 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 is displayed. This information is not displayed 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. The <target-language> tag must be updated to the language you are translating into. Initially the <source-language> and <target-language> values are the same. Prior to uploading the translated file into the database, the <target-language> tag must be edited to the translated language code. The value must a 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 is presented.

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.

There is no naming restriction on XLIFF files, however, it is advised to 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.

Below 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 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 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

The Translation Files grid is where you maintain the translated XLIFF files for your templates.