This guide also applies to on-premises implementations


This chapter contains the following:

Oracle BI Publisher Best Practices for SaaS Environments: Overview

Oracle Business Intelligence Publisher is an enterprise reporting solution for creating highly formatted, pixel perfect reports. It offers a single solution environment to author, manage, and deliver a variety of business documents. Oracle BI Publisher is available to customers with Oracle BI Suite Plus and Oracle BI Foundation. The product is also available standalone as Oracle BI Publisher Enterprise. Often these reports process large amounts of data, which requires product teams and end customers to understand the best practices of Oracle BI Publisher.

Often the reports process large amounts of data, which requires product teams and end customers to understand the best practices of Oracle BI Publisher. This white paper provides a detailed list of best practices that are recommended by Oracle when using Oracle BI Publisher in a Software-as-a-Service (SaaS) environment. For more information, see Oracle BI Publisher Best Practices for SaaS Environments document ID 2145444.1 on My Oracle Support at

Customizing Reports

Creating and Editing Reports: Explained

Use reports to generate and print documents for internal operations, external business transactions, or legal requirements. To meet specific requirements, you may need to create or edit reports to capture different data, or present data in another way.

Report Components

Each report has components that you can customize, as described in this table:

Report Component Description Tool for Customizing

Data model

Defines the data source, data structure, and parameters for the report. Multiple reports can use the same data model. Each report has one data model.

Data model editor in the application


Defines the presentation, formatting, and visualizations of the data. A report can have multiple layouts. There are different types of layout templates, for example Excel and RTF.

Depending on the template file type:

  • XPT: Layout editor in the application

  • RTF: Microsoft Word

  • PDF: Adobe Acrobat Professional

  • Excel: Microsoft Excel

  • eText: Microsoft Word


Specifies formatting and other settings for the report.

Report editor in the application

What You Can Create or Edit

This table gives just a few examples of creating or editing reports.

Task Example

Edit the layout of a report.

Add your company logo to the report output.

Add a new layout to a report.

Design a new layout template that provides less detail than the existing template.

Edit a data model.

Add two fields to the data model used by a report so you can add those new fields to a custom layout for the report.

Create a new report based on a new data model.

Create a new data model based on data from an external system, and create reports using the custom data model.

Accessing Report Components to Customize: Points to Consider

To create or edit reports, you must access the business intelligence (BI) catalog. In the catalog, objects of type Report represent the report definition, which includes report properties and layouts. Data models are separate objects in the catalog, usually stored in subfolders called Data Models.

Accessing the BI Catalog

You can access the BI catalog in any of the following ways:

  • In the Reports and Analytics pane, click Browse Catalog to open the BI catalog, and find your report or data model in the Folders pane.

  • In the Reports and Analytics pane, find your report and select More to go to the report directly in the catalog. The data model associated with the report should be in the Data Models subfolder within the same folder as the report.

  • Sign in to the application directly (for example: http://host:port/analytics/saw.dll) to open the catalog.

  • Sign in to the BI server directly (for example: to open the catalog.

    • Alternatively, once you are in the catalog using another method, for example, through the Reports and Analytics pane, change the final node of the URL. For example, change (http://host:port/analytics/saw.dll) to xmlpserver. So the URL you use would be: http://host:port/xmlpserver.

Predefined Reports

A special Customize option is available only:

  • For predefined reports, not data models.

  • Through direct access to the BI server using the /xmlpserver URL. When you find your report in the BI catalog, select Customize from the More menu.

The Customize option automatically creates a custom copy of a predefined report and stores it in the Shared Folders - Custom folder within the catalog. The new report is linked to the original, so that when users open or schedule the original, they are actually using the custom version.

If you don't have access to the Customize option or don't want the original version linked to the new report, then make a copy of the predefined report and save it in the Custom folder.

Predefined Data Models

Don't edit predefined data models. Instead, copy the data model into the Custom folder and edit the copy.

Using the Customize Option for Predefined Reports: Points to Consider

The Customize option automatically creates a custom copy of a predefined report and stores it in the Shared Folders - Custom within the business intelligence (BI) catalog. The custom copy includes the report definition, folder structure, and original report permissions, and is linked internally to the original report. You can edit the custom copy of the report, leaving the original report intact. When users open or schedule the original report, they are actually using the custom version.

Benefits of the Customize Option

In addition to conveniently copying a predefined report to the Custom folder, the Customize option:

  • Makes it unnecessary to update processes or applications that invoke the report. For example, if the original report is set up to run as a scheduled process, you don't need to change the setup. When users submit the same scheduled process, the custom report runs instead of the original.

  • Automatically copies the security settings of the original report.

  • Removes the risk of patches overwriting your edits. If a patch updates the original report, the custom report is not updated in any way.

    Note: The custom report still references the original data model. The data model is not copied. A patch that updates the data structure of the data model might affect your custom report.

Accessing the Customize Option

To access the Customize option:

  1. Sign in to the BI server (for example,

  2. In the Folders pane, select the predefined report.

  3. Select Customize from the More menu for the report.

  4. The copied report in the Custom folder opens, so proceed to edit this report.

To edit the custom report again later, you don't need to be in the BI server. Just go to the BI catalog and either:

  • Select the Customize or Edit option for the original report.

  • Find your custom report in the Custom folder and select Edit.

Links Between Original and Custom Reports: Points to Consider

The Customize option for predefined reports creates a custom copy of the report that is linked to the original. Consider the following points when you work with both the original and custom versions.

Maintaining the Link Between Reports

The link between the predefined and custom report is based on the name of the custom report and its location within the Custom folder in the business intelligence (BI) catalog.

  • If you manually create a report with the same name as a predefined report, and give it the same folder path under the Custom folder, then the new report becomes a custom version of the original. It would be as if you had used the Customize option to create the custom report.

  • You can edit the custom report so that it uses a different data model. But if the original data model is updated later, then your custom report doesn't benefit from the change.

Important: The link to the original report breaks if you rename the custom or original report.

Tasks Performed on Original Reports

This table describes what happens when you use the original report and a corresponding custom report exists.

Task Performed on the Original Report Result When There's a Custom Report


Opens the custom report.


Creates a report submission for the custom report.


Edits the custom report.


Deletes the original report only. If you delete the custom report, the original report is not deleted.


Copies the original report.

Cut and Paste

Cuts and pastes the original report.


Renames the original report. The custom report name is not changed.

Caution: This breaks the link between the original and custom reports.


Downloads the custom report.


Edits the custom report.


Opens the job history of the custom report.

Creating and Editing Report Layouts: Overview

The layout determines what and how data is displayed on report output. Each report has at least one layout template. This topic describes the following aspects of report templates:

  • Layout templates

  • Layout template types

  • Overall process of managing layouts

  • Deleting layout templates

Layout Templates

To customize a layout, you edit the layout template, which:

  • Defines the presentation components, such as tables and labeled fields.

  • Maps columns from the data model to these components so that the data is displayed in the right place.

  • Defines font sizes, styles, borders, shading, and other formatting, including images such as a company logo.

Layout Template Types

There are a few types of template files to support different report layout requirements.

  • RTF: Rich text format (RTF) templates created using Microsoft Word.

  • XPT: Created using the application's layout editor, these templates are for interactive and more visually appealing layouts.

  • eText: These templates are specifically for Electronic Data Interchange (EDI) and electronic funds transfer (EFT) information.

You can also create and edit other types of templates using Adobe PDF, Microsoft Excel, Adobe Flash, and XSL-FO.

Overall Process to Create or Edit Layouts

Editing or creating report layout, for example using Microsoft Word or the layout editor, involves making the actual changes to the template file. But that task is just one part of the entire process for customizing layouts.

  1. Copy the original report and save the custom version in Shared Folders - Custom in the business intelligence (BI) catalog. You create or edit templates for the custom copy of the report.

    Tip: You can use the Customize option if the original is a predefined report.
  2. Review report settings for online viewing.

  3. Generate sample data for the report.

  4. Edit or create the layout template file.

  5. Upload the template file to the report definition. Skip this step if you're using the layout editor.

  6. Configure the layout settings.

Deleting Layout Templates

To remove a layout template for a report:

  1. Select your report in the BI catalog and click Edit.

  2. In the report editor, click View a list.

  3. Select the layout template and click Delete.

Customizing Data Models: Procedure

A data model defines where data for a report comes from and how that data is retrieved. If a data model can't give you all the data that you need in your report, then you can either copy and edit an existing data model or create a new one.

Creating a Data Model

  1. In the business intelligence (BI) catalog, click the New button and select Data Model under Published Reporting.

  2. Optionally click the Data Model node in the Data Model pane to set properties for the data model.

  3. Click the Data Set node in the Data Model pane to create or edit data sets, which determine where and how to retrieve data.

  4. Click the New Data Set button and select a data set type. It's best practice to use the BI repository as a data source, so you should select either:

    • Oracle BI Analysis: To use columns from a selected analysis.

    • SQL Query: To use a Query Builder tool to define what to use from the repository. Select Oracle BI EE as the data source.

  5. Optionally, to limit the data included in the report output, click the Parameters node in the Data Model pane to define variables that users can set when they use the report.

    Note: The order of parameters is important if there are job definitions defined for reports that use your data model. If you change the order in the data model, you must also update the job definitions.
  6. Optionally, define other components of the data model.

  7. Save your data model.

Editing a Data Model

  1. To edit a predefined data model:

    1. Find the data model in the BI catalog and click Copy.

    2. Paste within Shared Folders - Custom in a subfolder that has a folder path similar to the folder that stores the original data model.

    3. For the data model you pasted, click More, and select Edit.

  2. Optionally click the Data Model node in the Data Model pane to set properties for the data model.

  3. Click the Data Set node in the Data Model pane to create or edit data sets.

    Most predefined data models are of type SQL Query, and are set up to get application data from the following tables:

    • ApplicationDB_FSCM: Financials, Supply Chain Management, Project Management, Procurement, and Incentive Compensation

    • ApplicationDB_CRM: Sales

    • ApplicationDB_HCM: Human Capital Management

  4. Perform steps 5 through 7 from the preceding Creating a Data Model task, as needed.

Creating Custom Reports: Procedure

Create a custom report when the predefined reports don't provide the data you need. Or, if you want to use a predefined data model, and also want to change other aspects of the report other than layout. Save your custom report to Shared Folders - Custom in the business intelligence catalog.

Creating a Report

  1. Open the Reports and Analytics work area, or the Reports and Analytics pane if available in other work areas.

  2. Click Create and select Report.

  3. Select the data model to use as the data source for your report.

  4. Continue with the wizard to create the report layout, or choose to use the layout editor and close the wizard.

  5. Define the layout for the report.

  6. Click the Properties button in the report editor to set specific formatting, caching, and processing options for your report.

Setting Up Access

You or your administrator can:

  • Create a job definition so that users can run your custom report as a scheduled process.

  • Set up the report for scheduling in the Reports and Analytics pane.

  • Secure general access to your report and its job definition, if any.

Making Reports Available for Online Viewing: Procedure

Some reports are set up so that you can only view them through another application or submit them as scheduled processes. To view your report online while you're editing it, you must define a few settings. When you're done editing your report, make sure that you reset these settings as needed.

Updating Report Properties

  1. Select your report in the business intelligence catalog and click Edit.

  2. In the report editor, click Properties at the top of the page.

  3. In the Report Properties dialog box, select Run Report Online and deselect Report is Controlled by External Application.

Updating Layout Settings

  1. Back in the report editor, click View a list.

  2. Make sure that the View Online check box is selected.

Generating Sample Report Data: Procedure

Depending on the type of report layout changes you're making, sample data can be required or optional. You generate sample data, and then load it for use with your layout so that you can map data fields to layout components. For example, for the Start Date table column in your layout, you can set it so that the data displayed in that column comes from the Start Date field in the sample data.

You can generate sample data from the:

  • Report data model

  • Report viewer

  • Scheduler

Generating Sample Data from the Data Model

Follow these steps:

  1. Select your data model in the business intelligence (BI) catalog and click Edit.

    Tip: If you're not sure which data model is the source for your report, find the report in the catalog and click Edit. The data model is displayed in the upper left corner of the report editor.
  2. In the data model editor, click View Data.

  3. Enter values for any required parameters, select the number of rows to return, and click View.

  4. To save the sample data to the data model, click Save As Sample Data.

    If you're designing an RTF template, click Export to save the file locally.

  5. Save the data model.

Saving Sample Data from the Report Viewer

For reports that are enabled for online viewing, you can save sample data from the report viewer:

  1. Select the report in the BI catalog.

  2. Click Open to run the report in the report viewer with the default parameters.

  3. On the Actions menu, click Export, then click Data.

  4. Save the data file.

Saving Sample Data from the Scheduler

For reports that are enabled for scheduling (not necessarily as a scheduled process), you can save sample data from the scheduler:

  1. Select the report in the BI catalog.

  2. Click Schedule.

  3. On the General tab, enter values for any report parameters.

  4. On the Output tab, ensure that Save Data for Republishing is selected.

  5. Click Submit.

  6. Open the Report Job History page.

  7. On the global header, click Open, then click Report Job History.

  8. Select your report job name in the Job Histories table.

  9. On the details page, under Output and Delivery, click the XML Data Download icon button.

Working with Templates

Creating and Editing Report Layout Templates Using the Layout Editor: Procedure

The layout editor in the application provides an intuitive, drag-and-drop interface for creating pixel-perfect reports with PDF, RTF, Excel, PowerPoint, and HTML output. The layout template files you create with this tool have an .xpt extension. The layout editor tool is the only editing tool that provides dynamic HTML output. Users can interact with this output in a browser, for example by sorting, applying filters, and so on.


Make sure that sample data is generated from the data model that your report is using.

Using the Layout Editor

To customize XPT templates:

  1. Select the report in the business intelligence (BI) catalog and click Edit.

  2. In the report editor, click Edit to update a template.

    Or, click Add New Layout and select a template type under the Create Layout section.

  3. Create or edit the layout.

  4. Click Save to save the layout to the report definition.

Setting Up for RTF and Excel Report Layout Templates: Procedure

You can use Microsoft Word or Microsoft Excel to create or edit RTF and Excel layout templates, in addition to the layout editor in the application. If you use Word or Excel directly, you must download and install the appropriate add-in so that the Microsoft application has the features you need to design report layouts.

Note: If you're designing a new layout for your report, consider using the layout editor instead unless you are an experienced layout designer.

Installing the Add-In

  1. Open the Reports and Analytics work area, or the Reports and Analytics pane if available in other work areas.

  2. Click the Browse Catalog button.

  3. Click Home.

  4. Under the Get Started pane, click Download BI Desktop Tools.

  5. Select the add-in for the type of template you're working with.

    • Template Builder for Word: RTF templates

    • Analyzer for Excel: Excel templates

  6. Save and then run the installer.

Creating and Editing RTF Report Layout Templates: Procedure

An RTF template is a rich text format file that contains the layout instructions to use when generating the report output. Use Microsoft Word with the Template Builder for Word add-in to design RTF templates.


Install the Template Builder for Word add-in, and generate sample data.

Using Template Builder for Word

To customize an RTF template:

  1. If you are editing an existing layout:

    1. Select your report in the business intelligence catalog and click Edit.

    2. In the report editor, click the Edit link of the layout to download the RTF file.

    If you are creating a new layout, skip this step.

  2. Open the downloaded RTF template file in Microsoft Word. Or, if you're creating a new template, just open Microsoft Word.

  3. Load the sample data that you generated.

  4. Edit or create the layout template.

  5. Save the file as Rich Text Format (RTF).

Changing the Branding Logo in a Predefined Oracle Fusion Project Performance Reporting RTF Report Template: Worked Example

The Update Project Performance Data report layout includes a standard Oracle logo in the report header. You want to replace the Oracle logo with your own logo.

The following table summarizes the key decisions for this scenario.

Decisions to Consider In This Example

What version of Microsoft Word are you using?

Microsoft Word 2007

What image do you want to use as your logo?


Which data model do you need to download sample report data from?


Do you want to preview the changed template?



  1. Install the Template Builder for Word add-in, and download sample data (save it locally).

Changing the Logo

To change the logo in the report output:

  1. Select the Update Project Performance Data Execution Report in the BI catalog and click Edit.

  2. In the report editor, click the Edit link of the Update Project Performance Data Execution Report layout to download the RTF file.

  3. Open the RTF file in Microsoft Word.

  4. In the BI Publisher tab, click Sample XML in the Load Data group, and select sample data that was saved from the data model.

  5. In the template, delete the Oracle logo and the text Fusion Projects and Project Performance Reporting.

  6. On the Insert tab in the Illustrations group, click Picture.

  7. Select the O_FusionApps_ProjectPortfolioMgmt_clr.gif file and insert it into the Word document.

  8. Resize the image if you need to.

  9. If the template file includes section breaks, you must insert the new logo for each section header.

  10. In the Oracle BI Publisher tab, in the Preview group, click PDF. You can preview the PDF output that's generated with the sample data that you loaded.

eText Report Layout Templates: Explained

An eText template is an RTF-based report template that is used for Electronic Funds Transfer (EFT) and Electronic Data Interchange (EDI). The template is applied to an input XML data file to create a flat text file that you transmit to a bank or other organizations. Use Microsoft Word to create or edit eText templates.

File Format

Because the output is for electronic communication, not printing, you must follow specific format instructions for exact placement of data on the template. You design eText templates using tables.

  • Each record is represented by a table.

  • Each row in a table corresponds to a field in a record.

  • The columns of the table specify the position, length, and value of the field.

Special Commands

You might need to set up special handling of the data from the input XML file. This table describes the two levels of handling and where you declare the corresponding commands.

Level Example Setup


Character replacement


Declare global commands in separate setup tables.



Declare functions in command rows, in the same table as the data.

Uploading the Layout Template File to the Report Definition: Procedure

If you're creating or editing a report layout using the layout editor, the layout is automatically saved to the report definition, so you can skip this step. For all other layout types, for example RTF, upload the template file to the report definition after you're done making layout changes.

Uploading the Template File

  1. Select your report in the business intelligence catalog and click Edit.

  2. In the report editor, click View a list.

  3. In the table that lists the layouts, click Create.

  4. Under Upload or Generate Layout, click Upload.

  5. In the Upload Template File dialog box:

    1. Enter a layout name.

    2. Browse for and select the layout template file that you created or edited.

    3. Select the template file type.

    4. Select the locale, which you can't change once the template file is saved to the report definition.

    5. Click Upload.

  6. Save the report definition.

Configuring Layout Settings for Reports: Procedure

As part of creating or editing layout, you can set report properties related to layout. These settings determine, for example, which layouts users can choose from when viewing or scheduling the report. The settings apply only to your report.

Setting Layout Properties

  1. Select your report in the business intelligence catalog and click Edit.

  2. In the report editor, click View a list.

  3. Set layout properties, some of which are described in this table.

    Setting Usage

    Output Formats

    Depending on the requirements for a report, you may want to limit the output file formats (for example PDF or HTML) that users can choose from. The available output formats vary depending on the template file type.

    Default Format

    When multiple output formats are available for the report, the default output format is generated by default when users open the report in the report viewer.

    Default Layout

    When multiple layouts are available for the report, you must select a default layout to present it first in the report viewer.


    Active layouts are available for users to choose from when they view or schedule the report.

    View Online

    Select this check box so that layouts are available to users when they view the report. Otherwise, the layout is available only for scheduling the report.

  4. Click Save Report.