Setting Up BI Publisher

This section discusses how to:

  • Set up report categories.

  • Define global properties.

  • Work with template design helpers.

Access the Report Category page (Select Reporting Tools > BI Publisher > Setup > Report Category.)

Image: Report Category page

This example illustrates the fields and controls on the Report Category page. You can find definitions for the fields and controls later on this page.

Report Category page

Report Category is a required attribute on all report definitions and Content Library sub-templates. By assigning a report category, you are actually applying row level security to the data on those components.

Field or Control

Definition
Report Category ID

Enter a report category ID to define a grouping that enables users to control who can access and edit report definitions and Content Library sub-templates.
Description

(Optional) Enter descriptive text that provides more detail about the report category.
Object Owner ID

Indicate which product, feature, or application owns this report category.
ID Type

Select an ID type of either Role or User ID to grant authorization to.
Security ID

Select the authorized editor’s security ID based on the ID type.
Description

A read-only field that indicates the related display value for the security ID.
Read Only

(Optional) Select to indicate that the designated ID is only able to view the report definitions under this category and not update them.

Note: The PeopleCode BI Publisher classes also respect report category settings and read-only access rights.

Access the Global Properties page (select Reporting Tools > BI Publisher > Setup > Global Properties.)

Note: To change the property setting at the global level and at the report-definition level, you require the BIP Report Developer role.

Image: Global Properties page

This example illustrates the fields and controls on the Global Properties page. You can find definitions for the fields and controls later on this page.

Global Properties page

Field or Control

Definition
Property Group

Select the property group. The options are:

  • FO Processing

  • HTML Output

  • PDF Digital Signature

  • PDF Output

  • PDF Security

  • PDF Submit Settings

  • PDF Template

  • PeopleTools Settings

  • Printer Properties

  • RTF Output

  • RTF Template

  • XLS Output

Note: This section provides documentation for the PeopleTools Settings and Printer Properties property groups.

For details about the other properties, see Report Designer's Guide for Oracle Business Intelligence Publisher, “Introduction to Designing Reports,” About Setting Run-Time Properties.”

In addition, note that the Oracle Business Intelligence Publisher User's Guide (XDOUserGuide.pdf) is downloaded with Template Builder for Word and available in the directory selected for download. For example, C:\Program Files\Oracle\BI Publisher\BI Publisher Desktop\Template Builder for Word\doc\XDOUserGuide.pdf.

Property

All properties available for the property group selected appear.
Prompt

Select the value for the property.
Default

Displays the default value for the property.

PeopleTools Settings

The properties in PeopleTools Settings control report attributes that are specific to PeopleSoft implementation of BI Publisher.

Field or Control

Definition
psxp_pdf_optimized

This property controls whether or not the core engine uses the "optimized" PDF Form Processing feature. This increases the efficiency and performance of PDF-template based reports, while disabling certain features. Valid values are:

  • True.

    Enables core engine optimization for PDF-based reports. The optimized engine will provide better performance, while disabling certain PDF-template specific features such as repeated fields and editable fields.

    Note: Full path mapping can be used.

  • False

    Uses the unoptimized engine (same as BIP server), which will enable repeated fields and editable fields in a PDF template.

    Allows using digital signature on PDF reports and creating updatable PDF reports.

    Note: Full path mapping is not supported.

    Note: The default setting for the psxp_pdf_optimized property is True at the global level, but you can override this setting at the report-definition level if required.

Note: The default behavior of PeopleSoft BIP PDF Form Processing engine that existed since 8.48.02 release is to enable multiple document output meaning that the PDF template is used to generate as many documents in the output as there are instances of the high level repeating node in the XML data. This uses the "performance optimized" engine introduced by the Oracle Core BIP product team specifically for PeopleSoft use.

By design, the "performance optimized" engine does not support editable fields. The editable fields feature was eliminated in order to meet the necessary performance goals of the "performance optimized" engine. At the present time, to get the editable fields feature, the user must fall-back to the non-performance optimized engine by setting psxp_pdf_optimized=false.

Also by design, the "non-performance optimized" engine does not, and never did support producing multiple documents based on the PDF template.

See the table at the end of this section for a summary of the behavior differences when setting this property.
psxp_usedefaultoutdestination

This property is used to indicate that default processing directory is exposed to the OutDestination property even if this value has not been previously set. The default value is False.

  • True

    A basic tools directory is exposed to the user, without showing an additional RptInst directory. This is the behavior in pre-8.50 BI Publisher.

    If this property is set to True and the user does not set value for OutDestination at runtime, then Tools will create an output file <Domain>\files\XMLP\123456789\RptInst\MyReport.HTM where 123456789 is for a directory name being generated with a random name. In this example the OutDestination property will return the value: <Domain>\files\XMLP\123456789.

    Some directories will not be cleaned up after processing is done and the report is delivered into Report Manager. Any empty directories that are left after the BI reports are delivered to the Report Manager will be cleaned up when the regularly scheduled Application Engine process PRCSYSPURGE runs. You can also run the Application Engine program PSXP_DIRCLN to clean up the directories.

  • False

    This is the default value. Querying the OutDestination property without previously setting it at runtime, will cause it to return blank. After the reports have been delivered to the report repository, the temporary files and directories used for processing will be deleted.
psxp_debug

This property controls whether or not to leave temporary files on the application server or the process scheduler server for debugging purpose. It is recommended to set this property at the report definition level to debug a specific report. Valid values are:

  • True

    Temporary files will not be deleted from application server or process scheduler server for debugging purpose.

  • False

    Temporary files are deleted from application server or process scheduler server.

Note: If this property is set to true, remember to change it back to False when debugging is completed.
psxp_nocdatafields

This property is used to indicate if character fields should not be wrapped in CDATA xml sections. By default, Query and Connected Query use CDATA xml sections for all character fields.

Use the Text field to indicate any fields that should not be wrapped in CDATA.

See Understanding Rich Text Editor Data in BI Reporting.
psxp_excel_outputformat

This property is used to indicate the Microsoft Excel output format of reports, that is whether you want to view the reports in the .xls or the .xlsx format. The valid values of this property are:

  • XLS-HTML

    The report can be viewed in Microsoft Excel versions 2002 and higher.

  • XLS-MHTML

    The report can be viewed in Microsoft Excel versions 2002 and higher.

  • XLSX

    This is the default value. The report can be viewed in Microsoft Excel versions 2007 and higher.

Note: You can override the global property setting for a specific report by changing the property setting at the report-definition level. For example, if you set the property to XLS-MHTML at the global level, you can override it for a specific report by choosing XLSX at the report-definition level.
psxp_number_format_src

This property allows you to modify the behaviour regarding the personalization of number values in a report run online through a PIA page. It does not have any effect on scheduled reports.

The valid values are:

  • Browser. (Default.)

    Formatting of a number value will be based on the PeopleSoft Regional Settings. The effective settings are determined after considering the user-specified overrides, browser-locale defaults, and system defaults, in that order.

  • LangCode.

    Formatting of a number value will be based on the language code of the current user session. This is the behavior in PeopleTools 8.55 and earlier releases.

Note: This property does not have any effect on reports run through the process scheduler, as number formatting in a scheduled report is always be driven by the language code of the process run control. See Applying PeopleSoft Regional Settings Personalizations to BI Publisher Reports
psxp_ext_email_appclass

Enter the name of an application class to retrieve a list of external email addresses to which to send reports.

See Emailing BI Publisher Reports to External Users
psxp_expand_entityref

This property eliminates XML entity expansion (XML Bomb). The default value is False.

Only a user with the Security Administrator role can see and modify this property setting on the Global Properties page. You cannot override this property setting at the report-definition level.

Note: PeopleSoft recommends that you do not change the default value of this property.
psxp_private_report_access

This property allows the sharing of a private report, so that it may be run by other users that also have a private query sharing the same name as the private query data source associated with the report. Note that report category permissions are enforced, so that only those users who have at least read-only permissions to the report can share the report.

The valid values are:

  • Owner.(Default)

    Only the owner of the private Query data source can access and run this report.

  • Shared.

    Users that have a private query that shares the same name as the private query data source associated with the report may also run the report, provided they have permissions to access the report based on its report category definition.

    These users also have read-only access to the report definition.

This table shows a summary of the differences in behavior when setting the psxp_pdf_optimized property:

psxp_pdf_optimized = true

psxp_pdf_optimized = false

  1. Editable Fields NOT supported.

  2. Repeated Fields NOT supported.

  3. Full Path mapping supported.

  4. Repeated document generation for each instance of high level repeating node in XML:.

    <?xml version="1.0"?>
<root>
<employee_details> repeating high level node
  <employee_id>1247</employee_id>
  <employee_name>Lesnar, Brock</employee_name>
  …
</employee_details>
<employee_details>
  <employee_id>1248</employee_id>
  <employee_name>Couture, Randy</employee_name>
  …
</employee_details>
...
</root>

  1. Editable Fields supported.

  2. Repeated Fields supported.

  3. Full Path mapping NOT supported.

  4. Single document output for single high level node in XML:

    <?xml version="1.0"?>
<root>
<employee_details> single high level node
  <employee_info>
     <employee_id>3256</employee_id>
     <employee_name>Carano, Gina</employee_name>

     …
  </employee_info>
  <employee_address>
     <Street_Address>24 Park Avenue</Street_Address>
     <City>Richmond</City>
     <State>Virginia</State>
     …
  </employee_address>
…
</employee_details>
</root>

  5. Digital signature in PDF reports supported.

  6. Updatable PDF reports supported.

Printer Properties

The printer properties are described here:

Field or Control

Definition
PDF2X_COPIES

This property is used to indicate the number of copies to be printed. This property is translated to PCL number of copies command (<esc>&l#X) on the output. The default value is 1.

Valid value for this property is an integer greater than 0.
PDF2X_MEDIA_SIZE_NAME

This property is used to specify the media size. When this property is set, media size in PDF is ignored. This property's value is translated to corresponding value of PCL page size command (<esc>&l#A).

Note: For PostScript output, the RTF template must be in the media size that you want for the final report output.

Valid values:

  • A3

  • A4

  • Com-10

  • Executive

  • International - b5

  • International - c5

  • International - dl

  • Ledger

  • Legal

  • Letter

  • Monarch

Media is selected based on page’s media size.
PDF2X_PAGE_ORIENTATION

This property is used to specify the page orientation. This property is valid only when the pdf2x-media-size-name property is specified. The default page orientation is portrait.

Valid values:

  • Landscape

  • Portrait

  • Reverse-landscape

  • Reverse-portrait
PDF2X_PAGE_RANGES

This property is used to specify a range of pages to be printed. For example, 1, 3–5. The default value is all pages.
PDF2X_SIDES

This property is used to specify whether printing should be done on one side of paper only or both sides, and if it is both sides, which layout to use. This property does not work unless the printer has duplex unit.

By default, no values are set. A printer determines the sides for printing.

Valid values:

  • Duplex

  • One-sided

  • Tumble
PDF2X_PAGE_WIDTH

This property is used to specify the width of a print media in points (1/72 inches). This property is valid only when the pdf2x-page-height property is also set. When this property is set, media size in PDF is ignored. This property's value is translated to the corresponding value of PCL page size command (<esc>&l#A).

The default value is the PDF page's width
PDF2X_PAGE_HEIGHT

This property is used to specify the height of a print media in points. This property is valid only when it is used in conjunction with the pdf2x-page-width property. When this property is set, media size in PDF is ignored. This property's value is translated to the corresponding value of PCL page size command (<esc>&l#A).

The default value is the PDF page's height.
PDF2X_MEDIA_TRAY

Use this property to specify the media tray or bin for PCL and PostScript compatible printers.

Valid values are:

  • auto: (Default.) Feed paper from the default paper tray as defined in the printer properties.

  • manual: Manual feed paper to the printer.

  • tray1: Feed paper from lower tray.

  • tray2: Feed paper from the printer-specified tray.

  • tray3: Feed from optional paper source.

For output to PostScript printers, auto and manual values are supported for this property. For output to PCL printers, all values are supported.

When this property is not specified, the printer selects the appropriate tray based on page size.

This property is ignored if the pdf2x-media-size-name property is specified.

PDF2X_SHEET_COLLATE

This property is used to specify whether or not the media sheets of each copy of each printed document in a job are to be in sequence, when multiple copies of the document are specified by the pdf2x-copies property. Printer determines collation when this property is not specified and number of copies is greater than 1.
PDF2X_PS_CID_FONT_CONVTYPE

When converting to Postscript and if the PDF has embedded CID Font Type 2, this property determines whether to convert the font to Postscript Type0+Type42 fonts or Type0+Type3 fonts.

Valid values are 3 and 42. The default value is 42.

Note: Type42 font normally renders faster and produces better quality output. However, because of Postscript's internal limitation, an error may occur when the font has large number of glyphs (greater than 32768). Type3 font does not have the limitation, but it is slower on most printers. Type3 font may still hit memory limitation when font has large number of glyphs.
PCL_COLOR_SUPPORTED

This property is used to specify whether a PCL printer supports color prints. The default value is false.

Valid values:

  • True

    When this property is set to true, the output will use PCL 5c, color PCL, commands. Text, vector, and raster graphics data are generated in RGB color. The output is printable only by color PCL printer supporting PCL 5c.

  • False

    When this property is not set or set to false, the output will use PCL 5 commands only and color information is translated to black and white.

Note: Most PCL printers do not support PCL 5c unless these are color printers. Unlike Postscript printers which automatically translate color information to grayscale if printer only supports black and white, PCL 5c commands are not accepted by black and white PCL printers and sending PCL 5c file to black and white printer may produce garbage output.
PCL_EDGE_TO_EDGE_SUPPORTED

Unlike Postscript printers which allow use of the full extent of the media by default, PCL printers imposes some margins around printable area (see the Printable Area section of PCL 5 Printer Language Technical Reference Manual). However, some PCL printers support elimination of PCL margins around printable area by using the XEDGETOEDGE PJL (Printer Job Language) command. When this property is set to true, the XEDGETOEDGE PJL command is set to on. Use this property with pcl-page-scale=1.0 to get the unshrinked 100% size page output. This property works only on PCL printers that support XEDGETOEDGE PJL command, not on all the PCL printers.

Valid values are true or false. The default value is false.
PCL_X_ADJUSTMENT

Adjust the x position of objects on a page. This property is translated to the Left Offset Registration PCL command (<esc>&l#U). This is helpful in aligning position of text on pre-printed form, typically used for check printing.

The adjustment is in points.

The default value is 0.
PCL_Y_ADJUSTMENT

Adjust the y position of objects on a page. This property is translated to the Top Offset Registration PCL command (<esc>&l#Z). This is helpful in aligning position of text on pre-printed form, typically used for check printing.

The adjustment is in points.

The default value is 0.

PDF Digital Signature

PDF Digital Signature properties are described here.

Note: The psxp_signature_appclass, psxp_signature_mapfields, and psxp_signature_digitalID properties are specific to the PeopleSoft implementation of BI Publisher.

Field or Control

Definition
signature-enable

Set this property to true to enable digital signature for PDF report.

The default value is False.
signature-field-name

This property reflects the digital signature field name. This property applies to PDF templates only.

If your report is based on a PDF template, you can enter a field in the PDF template where the digital signature will be placed.

For more information on designating a field for a signature in a PDF template, see Report Designer's Guide for Oracle Business Intelligence Publisher, “Creating PDF Templates, ” Adding or Designating a Field for a Digital Signature.”
signature-field-location

This property is applicable to RTF or PDF layout templates. The default value is top-left.

Valid values:

  • Top-center

  • Top-left

  • Top-right

Note: If you set this property, do not set the X and Y coordinates or width and height properties.
signature-field-pos-x

This property is applicable to RTF or PDF layout templates. The default value is 0.

Using the left edge of the document as the zero point of the X axis, enter the position in points that you want the digital signature to be placed from the left. For example, if you want the digital signature to be placed horizontally in the middle of an 8.5 inch by 11 inch document (which is 612 points in width and 792 points in height), enter 306.
signature-field-pos-y

This property is applicable to RTF or PDF layout templates. The default value is 0.

Using the bottom edge of the document as the zero point of the Y axis, enter the position in points that you want the digital signature to be placed from the bottom. For example, if you want the digital signature to be placed vertically in the middle of an 8.5 inch by 11 inch document (which is 612 points in width and 792 points in height), enter 396.
signature-field-width

Enter in points (72 points equal one inch) the desired width of the inserted digital signature field. The default value is 0.

This property should be set only if you set the X and Y coordinates properties.
signature-field-height

Enter in points (72 points equal one inch) the desired height of the inserted digital signature field. The default value is 0.

This property should be set only if you set the X and Y coordinates properties.
psxp_signature_appclass

This property sets which application class should be called by BI Publisher to map a generated PDF document to a signing authority. The application class should be created by application development implementing the IPT_PDFSIGNATURE_INT:IPDFSignature interface.

For example, APPS_PDFSIGNATURE_UNITTEST:PDFSignatureId.

You must set this property if you do not specify a value for the psxp_signature_digitalID property.

Note: This property is specific to the PeopleSoft implementation of BI Publisher.
psxp_signature_mapfields

A list of fields to be used by supplying data values to the application class. Values of these fields could be used to figure out the required signer ID.

You can separate field values by using comma, semicolon, colon, pipe (|), or white space.

This property is optional.

Note: This property is specific to the PeopleSoft implementation of BI Publisher.
psxp_signature_digitalID

If you do not specify a value for the psxp_signature_appclass property, you must specify the digital ID of the signer directly. If you specify the digital ID of the signer, do not set the psxp_signature_appclass property.

If the psxp_signature_appclass property and the psxp_signature_digitalID property are set, the psxp_signature_digitalID property is ignored.

Note: This property is specific to the PeopleSoft implementation of BI Publisher.

Note: PeopleSoft recommends that all properties of the PDF Digital Signature property group are set at the report-definition level.

PDF Submit Settings

The properties of PDF Submit Settings are described here:

Field or Control

Definition
psxp_submit_enable

This property defines whether a PDF report is updatable. The default value is False.

At runtime, BI Publisher embeds Acrobat JavaScript into the template to create a Save or Submit button. The Save or Submit button may not be visible in a template, but appears on the PDF report.

If you set the value of this property to False, all other properties in the PDF Submit Settings property group are ignored.
psxp_submit_field_name

This property allows you to designate an existing field in the PDF template as the Save or Submit button.

If you set this property, BI Publisher will not automatically create a Save or Submit button. Instead, BI Publisher will use the designated field for the Save or Submit button.
psxp_submit_location

This property specifies the location of the Submit button. The default value is bottom-right.

Valid values:

  • Bottom-left

  • Bottom-right

  • Top-left

  • Top-right
psxp_submit_caption

This property reflects the message catalog entry and should be set in the following format:

message_set,message_number

The default value is 235,250.
psxp_submit_tooltip

This property reflects the message catalog entry and should be set in the following format:

message_set,message_number

The default value is 235,251.
psxp_submit_width

Enter in points (72 points equal one inch) the desired width of the Submit button. The default value is 90.
psxp_submit_height

Enter in points (72 points equal one inch) the desired height of the Submit button. The default value is 18.
psxp_submit_appclass

This property specifies the application class name that saves submitted data to the database, and the application class name should be entered in the following format:

Application_Package:Application_class

For example, PDF_SUBMIT_TEST:PDFCONFIRM
psxp_submit_use_HTTPS

This property sets the network protocol (HTTP or HTTPS) that will be used while submitting a PDF report. The default value is True.

Valid values:

  • True

  • False
psxp_submit_service_operation_alias

BI Publisher provides a default IB Service operation to be used for updatable reports. The default service operation is intended to be used mainly for self-service operations. If an updatable report is to be used for other purposes, you should provide an alternate IB service operation.

The default value is PSXP_PDF_SUBMIT.

The psxp_submit_service_operation_alias and the psxp_submit_service_operation_version properties enable you to specify an IB service operation.
psxp_submit_service_operation_version

Enter a value in the following format:

v<VERSION_NUMBER>

For example, v1.

Editing PDF Output

In previous releases the ability to edit PDF output was defined on the Report Definition Output page using the PDF report output may be edited check box. Starting with PeopleTools 8.50, this is now configured via properties set either on the Global Properties page for all reports or on the Report Properties page for a specific report.

To allow editing of PDF reports, the properties for the following property groups should be set as indicated:

Property

Value

pdf-security

True

pdf-encryption-level

2

pdf-changes-allowed

2 or higher

Property

Value

all-field-readonly

False

Property

Value

psxp_pdf_optimized

False

Note: It is recommended to set these properties at the report definition level.

Access the Design Helper page (Select Reporting Tools > BI Publisher > Setup > Design Helper.)

Image: Design Helper page

This example illustrates the fields and controls on the Design Helper page.

Design Helper page

During template creation, a design helper facilitates the insertion of application data tag placeholders into your templates. A schema or sample data file is required for using a design helper. If you use a sample data file, you can preview your template offline during the design process.

Two template design helpers are available: one for designing RTF reports (MS Word Template Builder) and one for the PDF template that gets embedded as a JavaScript inside the PDF template itself when you upload the template to PeopleTools.

This page enables users to download a plug-in for Microsoft Word to facilitate offline RTF template design. Two versions of the plug-in are available: one for 32–bit Word and another for 64–bit Word. Select a version that applies from the list to enable the download button.

The plug-in is downloaded as a zip file. Based on your selection, the zip file contains either BIPublisherDesktop32.exe or BIPublisherDesktop64.exe that should be run to install the plug-in.

Included in the BI Publisher desktop plug-in setup, multiple directories are created that contain documentation, samples, tutorial, and demos. The program is also added to the Start menu.

See Using PDF Templates.