Customizing Seeded Reports

1 About Customizing Reports

Many Oracle products integrate with BI Publisher to provide the reporting functionality needed for the product. Many products also provide prepackaged reports. To customize the prepackaged reports, you have three options:

• Customize the original report.

Oracle strongly discourages modifying the original reports provided with Oracle products because any modifications are overwritten when Oracle provides a patch that updates the original report. If you choose to modify the original report, you must reapply your report changes when a patch updates the original report.

• Copy the report and customize the copy.

To avoid the risk of overwriting your customizations, an alternative is to make a copy of the report and customize the copy. With this option, you must also consider whether the original report is called by an application or process (such as the Oracle Enterprise Scheduler). These processes are typically coded with the report catalog path, therefore to enable them to execute your custom report, you must also make additional customizations to the calling application code to point to the customized copy of the report in the catalog.

• Use the Customize feature.

To facilitate the customization of prepackaged application reports, BI Publisher provides the Customize feature. When you select the Customize option for a report, BI Publisher creates a copy of the report in the "Custom" folder. This custom copy is linked internally to the original report. You can customize the custom copy of the report, leaving the original report intact. When users initiate a request to run the original report, whether from the BI Publisher catalog or through an application process, BI Publisher detects the customized version and runs your custom version instead.

The Customize feature provides the following benefits:

• Enables a customization process that mimics the convenience of an "in-place" customization. BI Publisher automatically creates the copy and the mapping.
• Removes the requirement to edit calling processes or applications to execute the custom report. Although you customize the copy, BI Publisher automatically sends all requests to run the original report to the custom copy instead.
• Removes the risk of patches overwriting your customizations of prepackaged Oracle reports.

2 Prerequisites and Limitations of the Customization Feature

Following are the prerequisites for and limitations of this feature.

2.1 Prerequisites

To enable the Customization option for reports, the following requirements must be met:

Catalog Requirements

• BI Publisher must use a shared catalog with Oracle BI Enterprise Edition.
• A folder named "Custom" must exist directly under Shared Folders. If the Custom folder is not seeded by your application, an Administrator can create it. The Administrator must grant the Write permission to the BI Author role for the Custom folder.
• Reports that are to be customized must reside in the folder hierarchy under Shared Folders. Reports under My Folders cannot be customized using this feature.

User Requirements

Following are requirements for a user to customize a report:

• A user must be granted the BI Author role (or a role that includes the permission oracle.bi.publisher.developReport)
• A user must be granted these permissions on the original report in the catalog:
• Read
• Run Publisher Report
• A user must be granted these permissions on the Custom folder in the catalog:
• Read
• Write
• The user must be granted access to the data model and data source of the original report if the same data model is used.

Following are requirements for a user to view a report in the Custom folder:

• A user must be granted the BI Consumer role
• A user must be granted these permissions on the original report in the catalog:
• Read
• Run Publisher Report
• A user must be granted these permissions on the Custom report in the catalog:
• Read
• Run Publisher Report
• The user must be granted access to the data model and data source of the original report if the same data model is used.

2.2 Limitations

Following are limitations of the Customize report option:

• The Customize option is not available through the /analytics URL used to access Oracle BI Enterprise Edition (for example: http://hostname.com:7001/analytics).

You must access BI Publisher through the /xmlpserver URL (for example: http://hostname.com:7001/xmlpserver) to see the Customize option.

• The Customize option is available only for reports. The Customize option is not available for data models, style templates, or sub templates.

To customize data models, style templates or sub templates and insulate them from potential changes from patching, follow the second approach described in the preceding section: Make a copy of the data model, style template, or sub-template and either rename it or place it in a custom directory. Ensure that you update any reports to point to the customized data model, style template, or sub-template.

• The security grants applied to the original report and folder hierarchy are not copied to the report created in the Custom folder. You must manually apply the security settings for the reports and folders that are created by the Customize feature in the Custom folder.

3 Using the Customize Feature

Assume your enterprise uses an Oracle prepackaged report called "Customer Orders" that resides under Shared Folders/Applications/Financials. Existing application processes point to this report in its current location in the catalog. Your organization wants to add a custom layout to this report that displays your company logo and color schemes. You then want the application processes to run your custom layout whenever the report is run as part of the business process, run as a separately scheduled job, or run directly from the catalog.

To use the Customize feature:

1. Log in to BI Publisher Enterprise through the /xmlpserver URL. Navigate to your report in the catalog and click Customize, as shown in Figure G-1.

Figure G-1 The Customize Task Option

BI Publisher creates a copy of the report in the Custom folder, under the identical folder hierarchy: Shared Folders/Custom/Applications/Financials and opens the report copy in the report editor.

Figure G-2 shows the custom report in the report editor. The process is seamless to the report designer. Notice that the report URL now references the report in the Custom folder.

Figure G-2 Custom Copy Opened in the Report Editor

2. Create a custom layout for this report and save it. Use the List View to customize properties of the layout, enable the custom layout as the default for this report, or inactivate the original layouts so your users no longer see them.
3. Apply security to the custom report.

Although BI Publisher creates identical folder hierarchy for the custom copy of the report, the catalog permissions present on the original folders and report are not copied to the custom report or the folder hierarchy. You must manually reapply the catalog permissions to secure the custom report identically to the original report.

To apply catalog permissions to reports:

• Use the Oracle Business Intelligence interface by logging in to Oracle Business Intelligence using the /analytics URL (for example: http:www.example.com:7001/analytics).
• You must be granted the appropriate permissions for setting permissions on the objects in the Custom folder. This typically requires having a role that is granted Full Control on the Custom folder. For more information about setting catalog permissions,

G.4 Considerations When Using the Customize Feature

When you click the Customize link, the report and the folder structure are copied to the Custom folder. The custom report still references the original data model. The data model is not copied. Because the data model referenced by the custom report is the original data model, an Oracle patch that updates the data model may impact the running of your custom report if the data structure is changed.

When an Oracle patch is applied that updates the original report, the custom report is not updated in any way.

When a custom version of a report exists, performing tasks on the original report will have the following results:

Task Performed on the Original Report	Behavior When a Custom Report Is Present
Open	Opens the custom report.
Schedule	Creates a report job for the custom report.
Edit	Edits the custom report.
Delete	Deletes the original report (only).
Copy	Copies the original report.
Cut/Paste	Cuts and pastes the original report.
Rename	Renames the original report. The custom report name is not changed.
Download	Downloads the custom report.
Customize	Edits the custom report.

To apply further edits to a report in the Custom folder perform one of the following

• Select the Customize or Edit option for the original report; this action opens the existing customized report.
• Navigate to the custom report in the Custom folder and select Edit.

If you manually create the identical folder path to a report under the Custom folder and create a report with the same name, BI Publisher treats the identically named report as a customized report and will run this report instead of the original report, as if you had used the Customize option to create it.

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